|
| Graphics.UI.Gtk.General.Drag | | Portability | portable (depends on GHC) | | Maintainer | gtk2hs-users@lists.sourceforge.net Stability : provisional |
|
|
|
|
|
| Description |
Drag-and-Drop functionality.
GTK+ has a rich set of functions for doing inter-process communication via
the drag-and-drop metaphor. GTK+ can do drag-and-drop (DND) via multiple
protocols. The currently supported protocols are the Xdnd and Motif
protocols. As well as the functions listed here, applications may need to
use some facilities provided for Selections. Also, the Drag and Drop API
makes use of signals in the Widget class.
|
|
| Synopsis |
|
|
|
|
| Types
|
|
| data DragContext |
 Instances | |
|
|
| class GObjectClass o => DragContextClass o |
| | Instances | |
|
|
| data DragAction |
Used in DragContext to indicate what the
destination should do with the dropped data.
- ActionDefault: Initialisation value, should not be used.
- ActionCopy: Copy the data.
- ActionMove: Move the data, i.e. first copy it, then delete it from the source.
- ActionLink: Add a link to the data. Note that this is only useful if source and
destination agree on what it means.
- ActionPrivate: Special action which tells the source that the destination will do
something that the source doesn't understand.
- ActionAsk: Ask the user what to do with the data.
| | Constructors | | ActionDefault | | | ActionCopy | | | ActionMove | | | ActionLink | | | ActionPrivate | | | ActionAsk | |
| | Instances | |
|
|
| data DestDefaults |
The DestDefaults enumeration specifies the various types of action that
will be taken on behalf of the user for a drag destination site.
- DestDefaultMotion: If set for a widget, GTK+, during a drag over this
widget will check if the drag matches this widget's list of possible
targets and actions. GTK+ will then call
dragStatus as appropriate.
- DestDefaultHighlight: If set for a widget, GTK+ will draw a
highlight on this widget as long as a drag is over this widget and the
widget drag format and action are acceptable.
- DestDefaultDrop: If set for a widget, when a drop occurs, GTK+ will
will check if the drag matches this widget's list of possible targets and
actions. If so, GTK+ will call dragGetData on
behalf of the widget. Whether or not the drop is successful, GTK+ will
call dragFinish. If the action was a move,
then if the drag was successful, then True will be passed for the
delete parameter to dragFinish
- DestDefaultAll: If set, specifies that all default actions should be
taken.
| | Constructors | | DestDefaultMotion | | | DestDefaultHighlight | | | DestDefaultDrop | | | DestDefaultAll | |
| | Instances | |
|
|
| data DragProtocol |
| Used in DragContext to indicate the protocol according to which DND is done.
| | Constructors | | DragProtoMotif | | | DragProtoXdnd | | | DragProtoRootwin | | | DragProtoNone | | | DragProtoWin32Dropfiles | | | DragProtoOle2 | | | DragProtoLocal | |
| | Instances | |
|
|
| castToDragContext :: GObjectClass obj => obj -> DragContext |
|
| toDragContext :: DragContextClass o => o -> DragContext |
|
| Methods
|
|
| dragContextActions :: Attr DragContext [DragAction] |
| A set of actions that the source recommends to be taken. Only valid if
dragContextSuggestedAction is set to ActionAsk.
|
|
| dragContextSuggestedAction :: Attr DragContext DragAction |
| The action suggested by the source.
|
|
| dragContextAction :: Attr DragContext DragAction |
| The action chosen by the destination.
|
|
| dragDestSet :: WidgetClass widget => widget -> [DestDefaults] -> [DragAction] -> IO () |
Sets a widget as a potential drop destination.
|
|
| dragDestSetProxy |
| :: WidgetClass widget | | | => widget | | | -> DrawWindow | The window to which to forward drag events.
| | -> DragProtocol | The drag protocol which the DrawWindow accepts.
| | -> Bool | If True, send the same coordinates to the destination,
because it is an embedded subwindow.
| | -> IO () | | | Sets this widget as a proxy for drops to another window.
|
|
|
| dragDestUnset :: WidgetClass widget => widget -> IO () |
| Clears information about a drop destination set with dragDestSet. The
widget will no longer receive notification of drags.
|
|
| dragDestFindTarget :: (WidgetClass widget, DragContextClass context) => widget -> context -> Maybe TargetList -> IO (Maybe TargetTag) |
| Looks for a match between the targets mentioned in the context and the
TargetList, returning the first matching target, otherwise returning
Nothing. If Nothing is given as target list, use the value from
destGetTargetList. Some widgets may have different valid targets for
different parts of the widget; in that case, they will have to implement a
dragMotion handler that passes the correct target list to this
function.
|
|
| dragDestGetTargetList :: WidgetClass widget => widget -> IO (Maybe TargetList) |
| Returns the list of targets this widget can accept for drag-and-drop.
|
|
| dragDestSetTargetList :: WidgetClass widget => widget -> TargetList -> IO () |
| Sets the target types that this widget can accept from drag-and-drop. The
widget must first be made into a drag destination with dragDestSet.
|
|
| dragDestAddTextTargets :: WidgetClass widget => widget -> IO () |
| Add the text targets supported by the selection mechanism to the target
list of the drag source. The targets are added with an InfoId of 0. If
you need another value, use targetListAddTextTargets and
dragSourceSetTargetList.
|
|
| dragDestAddImageTargets :: WidgetClass widget => widget -> IO () |
| Add image targets supported by the selection mechanism to the target list
of the drag source. The targets are added with an InfoId of 0. If you
need another value, use
targetListAddTextTargets and
dragSourceSetTargetList.
|
|
| dragDestAddURITargets :: WidgetClass widget => widget -> IO () |
| Add URI targets supported by the selection mechanism to the target list
of the drag source. The targets are added with an InfoId of 0. If you
need another value, use
targetListAddTextTargets and
dragSourceSetTargetList.
|
|
| dragFinish |
| :: DragContextClass context | | | => context | | | -> Bool | a flag indicating whether the drop was successful
| | -> Bool | a flag indicating whether the source should delete the original data.
(This should be True for a move)
| | -> TimeStamp | the timestamp from the dragDrop signal.
| | -> IO () | | | Informs the drag source that the drop is finished, and that the data of
the drag will no longer be required.
|
|
|
| dragGetData |
| :: (WidgetClass widget, DragContextClass context) | | | => widget | The widget that will receive the dragDataReceived signal.
| | -> context | | | -> TargetTag | The target (form of the data) to retrieve.
| | -> TimeStamp | A timestamp for retrieving the data. This will generally be
the time received in a dragMotion or dragDrop signal.
| | -> IO () | | | Gets the data associated with a drag. When the data is received or the
retrieval fails, GTK+ will emit a dragDataReceived signal. Failure of
the retrieval is indicated by passing Nothing in the selectionData signal.
However, when dragGetData is called
implicitely because the DestDefaultDrop was set, then the widget will
not receive notification of failed drops.
|
|
|
| dragGetSourceWidget :: DragContextClass context => context -> IO (Maybe Widget) |
Queries he source widget for a drag.
- If the drag is occurring within a single application, a pointer to the
source widget is returned. Otherwise the return value is Nothing.
|
|
| dragHighlight :: WidgetClass widget => widget -> IO () |
| Draws a highlight around a widget. This will attach handlers to
the expose handlers, so the highlight will continue to be displayed
until dragUnhighlight is called.
|
|
| dragUnhighlight :: WidgetClass widget => widget -> IO () |
| Removes a highlight set by dragHighlight from a widget.
|
|
| dragSetIconWidget |
| :: (DragContextClass context, WidgetClass widget) | | | => context | | | -> widget | | | -> Int | x hot-spot
| | -> Int | y hot-spot
| | -> IO () | | Changes the icon for a drag to a given widget. GTK+ will not destroy
the widget, so if you don't want it to persist, you should connect to the
dragEnd signal and destroy it yourself.
- The function must be called with the context of the source side.
|
|
|
| dragSetIconPixbuf |
| :: DragContextClass context | | | => context | | | -> Pixbuf | | | -> Int | x hot-spot
| | -> Int | y hot-spot
| | -> IO () | | | Set the given Pixbuf as the icon for the given drag.
|
|
|
| dragSetIconStock |
| :: DragContextClass context | | | => context | | | -> StockId | | | -> Int | x hot-spot
| | -> Int | y hot-spot
| | -> IO () | | | Sets the icon for a given drag from a stock ID.
|
|
|
| dragSetIconName |
| :: DragContextClass context | | | => context | | | -> String | | | -> Int | x hot-spot
| | -> Int | y hot-spot
| | -> IO () | | | Sets the icon for a given drag from a named themed icon. See the docs for
IconTheme for more details. Note that the size of the icon depends on the
icon theme (the icon is loaded at the DND size), thus x and y hot-spots
have to be used with care. Since Gtk 2.8.
|
|
|
| dragSetIconDefault :: DragContextClass context => context -> IO () |
| Sets the icon for a particular drag to the default icon. This function
must be called with a context for the source side of a drag
|
|
| dragCheckThreshold |
| :: WidgetClass widget | | | => widget | | | -> Int | startX | | -> Int | startY | | -> Int | currentX | | -> Int | currentY | | -> IO Bool | | | Checks to see if a mouse drag starting at (startX, startY) and ending
at (currentX, currenty) has passed the GTK+ drag threshold, and thus
should trigger the beginning of a drag-and-drop operation.
|
|
|
| dragSourceSet :: WidgetClass widget => widget -> [Modifier] -> [DragAction] -> IO () |
| Sets up a widget so that GTK+ will start a drag operation when the user
clicks and drags on the widget. The widget must have a window. Note that a
set of possible targets have to be set for a drag to be successful.
|
|
| dragSourceSetIconPixbuf :: WidgetClass widget => widget -> Pixbuf -> IO () |
| Sets the icon that will be used for drags from a particular widget from a
Pixbuf.
|
|
| dragSourceSetIconStock :: WidgetClass widget => widget -> StockId -> IO () |
| Sets the icon that will be used for drags from a particular source to a
stock icon.
|
|
| dragSourceSetIconName :: WidgetClass widget => widget -> String -> IO () |
| Sets the icon that will be used for drags from a particular source to a
themed icon. See the docs for IconTheme for more details.
|
|
| dragSourceUnset :: WidgetClass widget => widget -> IO () |
| Undoes the effects of dragSourceSet.
|
|
| dragSourceSetTargetList :: WidgetClass widget => widget -> TargetList -> IO () |
Changes the target types that this widget offers for drag-and-drop. The
widget must first be made into a drag source with dragSourceSet.
|
|
| dragSourceGetTargetList :: WidgetClass widget => widget -> IO (Maybe TargetList) |
Gets the list of targets this widget can provide for drag-and-drop.
|
|
| dragSourceAddTextTargets :: WidgetClass widget => widget -> IO () |
Add the text targets supported by
Selection to the target list of
the drag source. The targets are added with info = 0. If you need
another value, use
targetListAddTextTargets and
dragSourceSetTargetList.
|
|
| dragSourceAddImageTargets :: WidgetClass widget => widget -> IO () |
Add the image targets supported by Selection to the target list of the
drag source. The targets are added with info = 0. If you need another
value, use targetListAddTextTargets and dragSourceSetTargetList.
|
|
| dragSourceAddURITargets :: WidgetClass widget => widget -> IO () |
Add the URI targets supported by Selection to the target list of the
drag source. The targets are added with info = 0. If you need another
value, use targetListAddTextTargets and dragSourceSetTargetList.
|
|
| Signals
|
|
| dragBegin :: WidgetClass self => Signal self (DragContext -> IO ()) |
| The dragBegin signal is emitted on the drag source when a drag is
started. A typical reason to connect to this signal is to set up a custom
drag icon with dragSourceSetIcon.
|
|
| dragDataDelete :: WidgetClass self => Signal self (DragContext -> IO ()) |
| The dragDataDelete signal is emitted on the drag source when a drag
with the action ActionMove is successfully completed. The signal handler
is responsible for deleting the data that has been dropped. What "delete"
means, depends on the context of the drag operation.
|
|
| dragDataGet :: WidgetClass self => Signal self (DragContext -> InfoId -> TimeStamp -> SelectionDataM ()) |
| The ::drag-data-get signal is emitted on the drag source when the
drop site requests the data which is dragged. It is the
responsibility of the signal handler to set the selection data in
the format which is indicated by InfoId. See
selectionDataSet and
selectionDataSetText.
|
|
| dragDataReceived :: WidgetClass self => Signal self (DragContext -> Point -> InfoId -> TimeStamp -> SelectionDataM ()) |
The dragDataReceived signal is emitted on the drop site when the
dragged data has been received. If the data was received in order to
determine whether the drop will be accepted, the handler is expected to call
dragStatus and not finish the drag. If the data was received in response
to a dragDrop signal (and this is the last target to be received), the
handler for this signal is expected to process the received data and then
call dragFinish, setting the success parameter depending on whether the
data was processed successfully.
The handler may inspect and modify dragContextAction before calling
dragFinish, e.g. to implement ActionAsk as shown in the following
example:
|
|
| dragDrop :: WidgetClass self => Signal self (DragContext -> Point -> TimeStamp -> IO Bool) |
| The dragDrop signal is emitted on the drop site when the user drops
the data onto the widget. The signal handler must determine whether the
cursor position is in a drop zone or not. If it is not in a drop zone, it
returns False and no further processing is necessary. Otherwise, the
handler returns True. In this case, the handler must ensure that
dragFinish is called to let the source know that the drop is done. The
call to dragFinish can be done either directly or in a
dragDataReceived handler which gets triggered by calling dropGetData
to receive the data for one or more of the supported targets.
|
|
| dragEnd :: WidgetClass self => Signal self (DragContext -> IO ()) |
| The dragEnd signal is emitted on the drag source when a drag is
finished. A typical reason to connect to this signal is to undo things done
in dragBegin.
|
|
| dragLeave :: WidgetClass self => Signal self (DragContext -> TimeStamp -> IO ()) |
| The dragLeave signal is emitted on the drop site when the cursor
leaves the widget. A typical reason to connect to this signal is to undo
things done in dragMotion, e.g. undo highlighting with dragUnhighlight
|
|
| dragMotion :: WidgetClass self => Signal self (DragContext -> Point -> TimeStamp -> IO Bool) |
The dragMotion signal is emitted on the drop site when the user moves
the cursor over the widget during a drag. The signal handler must determine
whether the cursor position is in a drop zone or not. If it is not in a drop
zone, it returns False and no further processing is necessary. Otherwise,
the handler returns True. In this case, the handler is responsible for
providing the necessary information for displaying feedback to the user, by
calling dragStatus. If the decision whether the drop will be accepted or
rejected can't be made based solely on the cursor position and the type of
the data, the handler may inspect the dragged data by calling dragGetData
and defer the dragStatus call to the dragDataReceived handler.
Note that there is no dragEnter signal. The drag receiver has to keep
track of whether he has received any dragMotion signals since the last
dragLeave and if not, treat the dragMotion signal as an "enter"
signal. Upon an "enter", the handler will typically highlight the drop
site with dragHighlight.
|
|
| Produced by Haddock version 0.8 |
