gtk-0.12.0: Binding to the Gtk+ graphical user interface library.

Portability | portable (depends on GHC)
Maintainer | gtk2hs-users@lists.sourceforge.net Stability : provisional

Graphics.UI.Gtk.General.Drag

Contents

- Types
- Methods
- Signals

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 `Selection`s. Also, the Drag and Drop API makes use of signals in the `Widget` class.

Synopsis

- data DragContext
- class GObjectClass o => DragContextClass o
- data DragAction
  - = ActionDefault
  - | ActionCopy
  - | ActionMove
  - | ActionLink
  - | ActionPrivate
  - | ActionAsk
- data DestDefaults
  - = DestDefaultMotion
  - | DestDefaultHighlight
  - | DestDefaultDrop
  - | DestDefaultAll
- data DragProtocol
  - = DragProtoMotif
  - | DragProtoXdnd
  - | DragProtoRootwin
  - | DragProtoNone
  - | DragProtoWin32Dropfiles
  - | DragProtoOle2
  - | DragProtoLocal
- data DragResult
  - = DragResultSuccess
  - | DragResultNoTarget
  - | DragResultUserCancelled
  - | DragResultTimeoutExpired
  - | DragResultGrabBroken
  - | DragResultError
- castToDragContext :: GObjectClass obj => obj -> DragContext
- gTypeDragContext :: GType
- toDragContext :: DragContextClass o => o -> DragContext
- dragContextActions :: Attr DragContext [DragAction]
- dragContextSuggestedAction :: Attr DragContext DragAction
- dragContextAction :: Attr DragContext DragAction
- dragDestSet :: WidgetClass widget => widget -> [DestDefaults] -> [DragAction] -> IO ()
- dragDestSetProxy :: WidgetClass widget => widget -> DrawWindow -> DragProtocol -> Bool -> IO ()
- dragDestUnset :: WidgetClass widget => widget -> IO ()
- dragDestFindTarget :: (WidgetClass widget, DragContextClass context) => widget -> context -> Maybe TargetList -> IO (Maybe TargetTag)
- dragDestGetTargetList :: WidgetClass widget => widget -> IO (Maybe TargetList)
- dragDestSetTargetList :: WidgetClass widget => widget -> TargetList -> IO ()
- dragDestAddTextTargets :: WidgetClass widget => widget -> IO ()
- dragDestAddImageTargets :: WidgetClass widget => widget -> IO ()
- dragDestAddURITargets :: WidgetClass widget => widget -> IO ()
- dragStatus :: DragContext -> Maybe DragAction -> TimeStamp -> IO ()
- dragFinish :: DragContextClass context => context -> Bool -> Bool -> TimeStamp -> IO ()
- dragGetData :: (WidgetClass widget, DragContextClass context) => widget -> context -> TargetTag -> TimeStamp -> IO ()
- dragGetSourceWidget :: DragContextClass context => context -> IO (Maybe Widget)
- dragHighlight :: WidgetClass widget => widget -> IO ()
- dragUnhighlight :: WidgetClass widget => widget -> IO ()
- dragSetIconWidget :: (DragContextClass context, WidgetClass widget) => context -> widget -> Int -> Int -> IO ()
- dragSetIconPixbuf :: DragContextClass context => context -> Pixbuf -> Int -> Int -> IO ()
- dragSetIconStock :: DragContextClass context => context -> StockId -> Int -> Int -> IO ()
- dragSetIconName :: DragContextClass context => context -> String -> Int -> Int -> IO ()
- dragSetIconDefault :: DragContextClass context => context -> IO ()
- dragCheckThreshold :: WidgetClass widget => widget -> Int -> Int -> Int -> Int -> IO Bool
- dragSourceSet :: WidgetClass widget => widget -> [Modifier] -> [DragAction] -> IO ()
- dragSourceSetIconPixbuf :: WidgetClass widget => widget -> Pixbuf -> IO ()
- dragSourceSetIconStock :: WidgetClass widget => widget -> StockId -> IO ()
- dragSourceSetIconName :: WidgetClass widget => widget -> String -> IO ()
- dragSourceUnset :: WidgetClass widget => widget -> IO ()
- dragSourceSetTargetList :: WidgetClass widget => widget -> TargetList -> IO ()
- dragSourceGetTargetList :: WidgetClass widget => widget -> IO (Maybe TargetList)
- dragSourceAddTextTargets :: WidgetClass widget => widget -> IO ()
- dragSourceAddImageTargets :: WidgetClass widget => widget -> IO ()
- dragSourceAddURITargets :: WidgetClass widget => widget -> IO ()
- dragBegin :: WidgetClass self => Signal self (DragContext -> IO ())
- dragDataDelete :: WidgetClass self => Signal self (DragContext -> IO ())
- dragDataGet :: WidgetClass self => Signal self (DragContext -> InfoId -> TimeStamp -> SelectionDataM ())
- dragDataReceived :: WidgetClass self => Signal self (DragContext -> Point -> InfoId -> TimeStamp -> SelectionDataM ())
- dragDrop :: WidgetClass self => Signal self (DragContext -> Point -> TimeStamp -> IO Bool)
- dragEnd :: WidgetClass self => Signal self (DragContext -> IO ())
- dragFailed :: WidgetClass self => Signal self (DragContext -> DragResult -> IO Bool)
- dragLeave :: WidgetClass self => Signal self (DragContext -> TimeStamp -> IO ())
- dragMotion :: WidgetClass self => Signal self (DragContext -> Point -> TimeStamp -> IO Bool)

# Types

data DragContext

Instances

Eq DragContext |
Ord DragContext |
GObjectClass DragContext |
DragContextClass DragContext |

class GObjectClass o => DragContextClass o

Instances

DragContextClass DragContext |

data DragAction

Used in `Graphics.UI.Gtk.Genearl.Drag.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

Bounded DragAction |
Enum DragAction |
Eq DragAction |
Show DragAction |
Flags DragAction |

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 `Graphics.UI.Gtk.Gdk.Drag.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 `Graphics.UI.Gtk.Gdk.Drag.dragGetData` on behalf of the widget. Whether or not the drop is successful, GTK+ will call `Graphics.UI.Gtk.Gdk.Drag.dragFinish`. If the action was a move, then if the drag was successful, then `True` will be passed for the delete parameter to `Graphics.UI.Gtk.Gdk.Drag.dragFinish`
- `DestDefaultAll`: If set, specifies that all default actions should be taken.

Constructors

DestDefaultMotion |
DestDefaultHighlight |
DestDefaultDrop |
DestDefaultAll |

Instances

Bounded DestDefaults |

Enum DestDefaults

Gives an indication why a drag operation failed. The value can by obtained by connecting to the `dragFailed` signal.

- `DragResultSuccess`: The drag operation was successful
- `DragResultNoTarget`: No suitable drag target
- `DragResultUserCancelled`: The user cancelled the drag operation
- `DragResultTimeoutExpired`: The drag operation timed out
- `DragResultGrabBroken`: The pointer or keyboard grab used for the drag operation was broken
- `DragResultError`: The drag operation failed due to some unspecified error

Eq DestDefaults |
Show DestDefaults |
Flags DestDefaults |

data DragProtocol

Used in `Graphics.UI.Gtk.Gdk.Drag.DragContext` to indicate the protocol according to which DND is done.

Constructors

DragProtoMotif |
DragProtoXdnd |
DragProtoRootwin |
DragProtoNone |
DragProtoWin32Dropfiles |
DragProtoOle2 |
DragProtoLocal |

Instances

Bounded DragProtocol |
Enum DragProtocol |
Eq DragProtocol |
Show DragProtocol |

data DragResult

Constructors

DragResultSuccess |
DragResultNoTarget |
DragResultUserCancelled |
DragResultTimeoutExpired |
DragResultGrabBroken |
DragResultError |

Instances

Bounded DragResult |
Enum DragResult |
Eq DragResult |
Show DragResult |

castToDragContext :: GObjectClass obj => obj -> DragContext

gTypeDragContext :: GType

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.

- The `DestDefaults` flags specify what actions Gtk should take on behalf of a widget for drops onto that widget. The given actions and any targets set through `dragDestSetTargetList` only are used if `DestDefaultMotion` or `DestDefaultDrop` are given.
- Things become more complicated when you try to preview the dragged data, as described in the documentation for `dragMotion`. The default behaviors described by flags make some assumptions, that can conflict with your own signal handlers. For instance `DestDefaultDrop` causes invocations of `dragStatus` in the handler of `dragMotion`, and invocations of `dragFinish` in `dragDataReceived`. Especially the latter is dramatic, when your own `dragMotion` handler calls `dragGetData` to inspect the dragged data.

dragDestSetProxy

Arguments

:: 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 `Graphics.UI.Gtk.General.Selection.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 `Graphics.UI.Gtk.General.Selection.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 `Graphics.UI.Gtk.General.Selection.targetListAddTextTargets` and `dragSourceSetTargetList`.

dragStatus :: DragContext -> Maybe DragAction -> TimeStamp -> IO ()

Visualises the actions offered by the drag source.

- This function is called by the drag destination in response to `dragMotion` called by the drag source. The passed-in action is indicated where `Nothing` will show that the drop is not allowed.

dragFinish

Arguments

:: 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

Arguments

:: (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

Arguments

:: (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

Arguments

:: 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

Arguments

:: 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

Arguments

:: 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

Arguments

:: 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`.

- Since Gtk 2.4.

dragSourceGetTargetList :: WidgetClass widget => widget -> IO (Maybe TargetList)

Gets the list of targets this widget can provide for drag-and-drop.

- Since Gtk 2.4.

dragSourceAddTextTargets :: WidgetClass widget => widget -> IO ()

Add the text targets supported by `Graphics.UI.Gtk.General.Selection.Selection` to the target list of the drag source. The targets are added with `info = 0`. If you need another value, use `Graphics.UI.Gtk.General.Selection.targetListAddTextTargets` and `dragSourceSetTargetList`.

- Since Gtk 2.6.

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 `Graphics.UI.Gtk.General.Selection.targetListAddTextTargets` and `dragSourceSetTargetList`.

- Since Gtk 2.6.

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 `Graphics.UI.Gtk.General.Selection.targetListAddTextTargets` and `dragSourceSetTargetList`.

- Since Gtk 2.6.

# 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 `dragDataGet` 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 `Graphics.UI.Gtk.General.Selection.selectionDataSet` and `Graphics.UI.Gtk.General.Selection.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`.

dragFailed :: WidgetClass self => Signal self (DragContext -> DragResult -> IO Bool)

The `dragFailed` signal is emitted on the drag source when a drag has failed. The signal handler may hook custom code to handle a failed DND operation based on the type of error, it returns `True` is the failure has been already handled (not showing the default "drag operation failed" animation), otherwise it returns `False`.

- Available since Gtk+ 2.12.0.

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`.