Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
GtkDragSource
is an event controller to initiate Drag-And-Drop operations.
GtkDragSource
can be set up with the necessary
ingredients for a DND operation ahead of time. This includes
the source for the data that is being transferred, in the form
of a ContentProvider
, the desired action, and the icon to
use during the drag operation. After setting it up, the drag
source must be added to a widget as an event controller, using
widgetAddController
.
c code
static void my_widget_init (MyWidget *self) { GtkDragSource *drag_source = gtk_drag_source_new (); g_signal_connect (drag_source, "prepare", G_CALLBACK (on_drag_prepare), self); g_signal_connect (drag_source, "drag-begin", G_CALLBACK (on_drag_begin), self); gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (drag_source)); }
Setting up the content provider and icon ahead of time only makes
sense when the data does not change. More commonly, you will want
to set them up just in time. To do so, GtkDragSource
has
DragSource::prepare and DragSource::dragBegin
signals.
The prepare signal is emitted before a drag is started, and can be used to set the content provider and actions that the drag should be started with.
c code
static GdkContentProvider * on_drag_prepare (GtkDragSource *source, double x, double y, MyWidget *self) { // This widget supports two types of content: GFile objects // and GdkPixbuf objects; GTK will handle the serialization // of these types automatically GFile *file = my_widget_get_file (self); GdkPixbuf *pixbuf = my_widget_get_pixbuf (self); return gdk_content_provider_new_union ((GdkContentProvider *[2]) { gdk_content_provider_new_typed (G_TYPE_FILE, file), gdk_content_provider_new_typed (GDK_TYPE_PIXBUF, pixbuf), }, 2); }
The dragBegin signal is emitted after the GdkDrag
object has
been created, and can be used to set up the drag icon.
c code
static void on_drag_begin (GtkDragSource *source, GtkDrag *drag, MyWidget *self) { // Set the widget as the drag icon GdkPaintable *paintable = gtk_widget_paintable_new (GTK_WIDGET (self)); gtk_drag_source_set_icon (source, paintable, 0, 0); g_object_unref (paintable); }
During the DND operation, GtkDragSource
emits signals that
can be used to obtain updates about the status of the operation,
but it is not normally necessary to connect to any signals,
except for one case: when the supported actions include
DragActionMove
, you need to listen for the
DragSource::dragEnd signal and delete the
data after it has been transferred.
Synopsis
- newtype DragSource = DragSource (ManagedPtr DragSource)
- class (GObject o, IsDescendantOf DragSource o) => IsDragSource o
- toDragSource :: (MonadIO m, IsDragSource o) => o -> m DragSource
- dragSourceDragCancel :: (HasCallStack, MonadIO m, IsDragSource a) => a -> m ()
- dragSourceGetActions :: (HasCallStack, MonadIO m, IsDragSource a) => a -> m [DragAction]
- dragSourceGetContent :: (HasCallStack, MonadIO m, IsDragSource a) => a -> m (Maybe ContentProvider)
- dragSourceGetDrag :: (HasCallStack, MonadIO m, IsDragSource a) => a -> m (Maybe Drag)
- dragSourceNew :: (HasCallStack, MonadIO m) => m DragSource
- dragSourceSetActions :: (HasCallStack, MonadIO m, IsDragSource a) => a -> [DragAction] -> m ()
- dragSourceSetContent :: (HasCallStack, MonadIO m, IsDragSource a, IsContentProvider b) => a -> Maybe b -> m ()
- dragSourceSetIcon :: (HasCallStack, MonadIO m, IsDragSource a, IsPaintable b) => a -> Maybe b -> Int32 -> Int32 -> m ()
- constructDragSourceActions :: (IsDragSource o, MonadIO m) => [DragAction] -> m (GValueConstruct o)
- getDragSourceActions :: (MonadIO m, IsDragSource o) => o -> m [DragAction]
- setDragSourceActions :: (MonadIO m, IsDragSource o) => o -> [DragAction] -> m ()
- clearDragSourceContent :: (MonadIO m, IsDragSource o) => o -> m ()
- constructDragSourceContent :: (IsDragSource o, MonadIO m, IsContentProvider a) => a -> m (GValueConstruct o)
- getDragSourceContent :: (MonadIO m, IsDragSource o) => o -> m (Maybe ContentProvider)
- setDragSourceContent :: (MonadIO m, IsDragSource o, IsContentProvider a) => o -> a -> m ()
- type DragSourceDragBeginCallback = Drag -> IO ()
- afterDragSourceDragBegin :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragBeginCallback) -> m SignalHandlerId
- onDragSourceDragBegin :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragBeginCallback) -> m SignalHandlerId
- type DragSourceDragCancelCallback = Drag -> DragCancelReason -> IO Bool
- afterDragSourceDragCancel :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragCancelCallback) -> m SignalHandlerId
- onDragSourceDragCancel :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragCancelCallback) -> m SignalHandlerId
- type DragSourceDragEndCallback = Drag -> Bool -> IO ()
- afterDragSourceDragEnd :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragEndCallback) -> m SignalHandlerId
- onDragSourceDragEnd :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragEndCallback) -> m SignalHandlerId
- type DragSourcePrepareCallback = Double -> Double -> IO (Maybe ContentProvider)
- afterDragSourcePrepare :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourcePrepareCallback) -> m SignalHandlerId
- onDragSourcePrepare :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourcePrepareCallback) -> m SignalHandlerId
Exported types
newtype DragSource Source #
Memory-managed wrapper type.
Instances
Eq DragSource Source # | |
Defined in GI.Gtk.Objects.DragSource (==) :: DragSource -> DragSource -> Bool # (/=) :: DragSource -> DragSource -> Bool # | |
GObject DragSource Source # | |
Defined in GI.Gtk.Objects.DragSource | |
ManagedPtrNewtype DragSource Source # | |
Defined in GI.Gtk.Objects.DragSource | |
TypedObject DragSource Source # | |
Defined in GI.Gtk.Objects.DragSource | |
HasParentTypes DragSource Source # | |
Defined in GI.Gtk.Objects.DragSource | |
IsGValue (Maybe DragSource) Source # | Convert |
Defined in GI.Gtk.Objects.DragSource gvalueGType_ :: IO GType # gvalueSet_ :: Ptr GValue -> Maybe DragSource -> IO () # gvalueGet_ :: Ptr GValue -> IO (Maybe DragSource) # | |
type ParentTypes DragSource Source # | |
Defined in GI.Gtk.Objects.DragSource |
class (GObject o, IsDescendantOf DragSource o) => IsDragSource o Source #
Type class for types which can be safely cast to DragSource
, for instance with toDragSource
.
Instances
(GObject o, IsDescendantOf DragSource o) => IsDragSource o Source # | |
Defined in GI.Gtk.Objects.DragSource |
toDragSource :: (MonadIO m, IsDragSource o) => o -> m DragSource Source #
Cast to DragSource
, for types for which this is known to be safe. For general casts, use castTo
.
Methods
Click to display all available methods, including inherited ones
Methods
bindProperty, bindPropertyFull, dragCancel, forceFloating, freezeNotify, getv, group, handlesSequence, isActive, isFloating, isGroupedWith, isRecognized, notify, notifyByPspec, ref, refSink, reset, runDispose, stealData, stealQdata, thawNotify, ungroup, unref, watchClosure.
Getters
getActions, getBoundingBox, getBoundingBoxCenter, getButton, getContent, getCurrentButton, getCurrentEvent, getCurrentEventDevice, getCurrentEventState, getCurrentEventTime, getCurrentSequence, getData, getDevice, getDrag, getExclusive, getGroup, getLastEvent, getLastUpdatedSequence, getName, getPoint, getPropagationLimit, getPropagationPhase, getProperty, getQdata, getSequenceState, getSequences, getTouchOnly, getWidget.
Setters
setActions, setButton, setContent, setData, setDataFull, setExclusive, setIcon, setName, setPropagationLimit, setPropagationPhase, setProperty, setSequenceState, setState, setTouchOnly.
dragCancel
:: (HasCallStack, MonadIO m, IsDragSource a) | |
=> a |
|
-> m () |
Cancels a currently ongoing drag operation.
getActions
:: (HasCallStack, MonadIO m, IsDragSource a) | |
=> a |
|
-> m [DragAction] | Returns: the actions set on |
Gets the actions that are currently set on the GtkDragSource
.
getContent
:: (HasCallStack, MonadIO m, IsDragSource a) | |
=> a |
|
-> m (Maybe ContentProvider) | Returns: the |
Gets the current content provider of a GtkDragSource
.
getDrag
:: (HasCallStack, MonadIO m, IsDragSource a) | |
=> a |
|
-> m (Maybe Drag) | Returns: the |
Returns the underlying GdkDrag
object for an ongoing drag.
new
:: (HasCallStack, MonadIO m) | |
=> m DragSource | Returns: the new |
Creates a new GtkDragSource
object.
setActions
:: (HasCallStack, MonadIO m, IsDragSource a) | |
=> a |
|
-> [DragAction] |
|
-> m () |
Sets the actions on the GtkDragSource
.
During a DND operation, the actions are offered to potential
drop targets. If actions
include DragActionMove
, you need
to listen to the DragSource::dragEnd signal and
handle deleteData
being True
.
This function can be called before a drag is started, or in a handler for the DragSource::prepare signal.
setContent
:: (HasCallStack, MonadIO m, IsDragSource a, IsContentProvider b) | |
=> a |
|
-> Maybe b |
|
-> m () |
Sets a content provider on a GtkDragSource
.
When the data is requested in the cause of a DND operation, it will be obtained from the content provider.
This function can be called before a drag is started, or in a handler for the DragSource::prepare signal.
You may consider setting the content provider back to
Nothing
in a DragSource::dragEnd signal handler.
setIcon
:: (HasCallStack, MonadIO m, IsDragSource a, IsPaintable b) | |
=> a |
|
-> Maybe b |
|
-> Int32 |
|
-> Int32 |
|
-> m () |
Sets a paintable to use as icon during DND operations.
The hotspot coordinates determine the point on the icon that gets aligned with the hotspot of the cursor.
If paintable
is Nothing
, a default icon is used.
This function can be called before a drag is started, or in a DragSource::prepare or DragSource::dragBegin signal handler.
Properties
actions
The actions that are supported by drag operations from the source.
Note that you must handle the DragSource::dragEnd signal
if the actions include DragActionMove
.
constructDragSourceActions :: (IsDragSource o, MonadIO m) => [DragAction] -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “actions
” property. This is rarely needed directly, but it is used by new
.
getDragSourceActions :: (MonadIO m, IsDragSource o) => o -> m [DragAction] Source #
Get the value of the “actions
” property.
When overloading is enabled, this is equivalent to
get
dragSource #actions
setDragSourceActions :: (MonadIO m, IsDragSource o) => o -> [DragAction] -> m () Source #
Set the value of the “actions
” property.
When overloading is enabled, this is equivalent to
set
dragSource [ #actions:=
value ]
content
The data that is offered by drag operations from this source.
clearDragSourceContent :: (MonadIO m, IsDragSource o) => o -> m () Source #
Set the value of the “content
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#content
constructDragSourceContent :: (IsDragSource o, MonadIO m, IsContentProvider a) => a -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “content
” property. This is rarely needed directly, but it is used by new
.
getDragSourceContent :: (MonadIO m, IsDragSource o) => o -> m (Maybe ContentProvider) Source #
Get the value of the “content
” property.
When overloading is enabled, this is equivalent to
get
dragSource #content
setDragSourceContent :: (MonadIO m, IsDragSource o, IsContentProvider a) => o -> a -> m () Source #
Set the value of the “content
” property.
When overloading is enabled, this is equivalent to
set
dragSource [ #content:=
value ]
Signals
dragBegin
type DragSourceDragBeginCallback Source #
Emitted on the drag source when a drag is started.
It can be used to e.g. set a custom drag icon with
dragSourceSetIcon
.
afterDragSourceDragBegin :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragBeginCallback) -> m SignalHandlerId Source #
Connect a signal handler for the dragBegin signal, to be run after the default handler. When overloading is enabled, this is equivalent to
after
dragSource #dragBegin callback
By default the object invoking the signal is not passed to the callback.
If you need to access it, you can use the implit ?self
parameter.
Note that this requires activating the ImplicitParams
GHC extension.
onDragSourceDragBegin :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragBeginCallback) -> m SignalHandlerId Source #
Connect a signal handler for the dragBegin signal, to be run before the default handler. When overloading is enabled, this is equivalent to
on
dragSource #dragBegin callback
dragCancel
type DragSourceDragCancelCallback Source #
= Drag |
|
-> DragCancelReason |
|
-> IO Bool | Returns: |
Emitted on the drag source when a drag has failed.
The signal handler may handle a failed drag operation based on
the type of error. It should return True
if the failure has been handled
and the default "drag operation failed" animation should not be shown.
afterDragSourceDragCancel :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragCancelCallback) -> m SignalHandlerId Source #
Connect a signal handler for the dragCancel signal, to be run after the default handler. When overloading is enabled, this is equivalent to
after
dragSource #dragCancel callback
By default the object invoking the signal is not passed to the callback.
If you need to access it, you can use the implit ?self
parameter.
Note that this requires activating the ImplicitParams
GHC extension.
onDragSourceDragCancel :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragCancelCallback) -> m SignalHandlerId Source #
Connect a signal handler for the dragCancel signal, to be run before the default handler. When overloading is enabled, this is equivalent to
on
dragSource #dragCancel callback
dragEnd
type DragSourceDragEndCallback Source #
= Drag |
|
-> Bool |
|
-> IO () |
Emitted on the drag source when a drag is finished.
A typical reason to connect to this signal is to undo things done in DragSource::prepare or DragSource::dragBegin handlers.
afterDragSourceDragEnd :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragEndCallback) -> m SignalHandlerId Source #
Connect a signal handler for the dragEnd signal, to be run after the default handler. When overloading is enabled, this is equivalent to
after
dragSource #dragEnd callback
By default the object invoking the signal is not passed to the callback.
If you need to access it, you can use the implit ?self
parameter.
Note that this requires activating the ImplicitParams
GHC extension.
onDragSourceDragEnd :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourceDragEndCallback) -> m SignalHandlerId Source #
Connect a signal handler for the dragEnd signal, to be run before the default handler. When overloading is enabled, this is equivalent to
on
dragSource #dragEnd callback
prepare
type DragSourcePrepareCallback Source #
= Double |
|
-> Double |
|
-> IO (Maybe ContentProvider) | Returns: a |
Emitted when a drag is about to be initiated.
It returns the GdkContentProvider
to use for the drag that is about
to start. The default handler for this signal returns the value of
the DragSource:content property, so if you set up that
property ahead of time, you don't need to connect to this signal.
afterDragSourcePrepare :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourcePrepareCallback) -> m SignalHandlerId Source #
Connect a signal handler for the prepare signal, to be run after the default handler. When overloading is enabled, this is equivalent to
after
dragSource #prepare callback
By default the object invoking the signal is not passed to the callback.
If you need to access it, you can use the implit ?self
parameter.
Note that this requires activating the ImplicitParams
GHC extension.
onDragSourcePrepare :: (IsDragSource a, MonadIO m) => a -> ((?self :: a) => DragSourcePrepareCallback) -> m SignalHandlerId Source #
Connect a signal handler for the prepare signal, to be run before the default handler. When overloading is enabled, this is equivalent to
on
dragSource #prepare callback