GI.Gtk.Objects.DragSource

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,
               GdkDrag       *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.

Exported types

newtype DragSource

Memory-managed wrapper type.

Constructors

DragSource (ManagedPtr DragSource)

Instances

Eq DragSource

Defined in GI.Gtk.Objects.DragSource

Methods

(==) :: DragSource -> DragSource -> Bool

(/=) :: DragSource -> DragSource -> Bool

GObject DragSource

Defined in GI.Gtk.Objects.DragSource

ManagedPtrNewtype DragSource

Defined in GI.Gtk.Objects.DragSource

Methods

toManagedPtr :: DragSource -> ManagedPtr DragSource

TypedObject DragSource

Defined in GI.Gtk.Objects.DragSource

Methods

glibType :: IO GType

HasParentTypes DragSource

Defined in GI.Gtk.Objects.DragSource

IsGValue (Maybe DragSource)

Convert DragSource to and from GValue. See toGValue and fromGValue.

Defined in GI.Gtk.Objects.DragSource

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe DragSource -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe DragSource)

type ParentTypes DragSource

Defined in GI.Gtk.Objects.DragSource

type ParentTypes DragSource = '[GestureSingle, Gesture, EventController, Object]

class (GObject o, IsDescendantOf DragSource o) => IsDragSource o

Type class for types which can be safely cast to DragSource, for instance with toDragSource.

Instances

(GObject o, IsDescendantOf DragSource o) => IsDragSource o

Defined in GI.Gtk.Objects.DragSource

toDragSource :: (MonadIO m, IsDragSource o) => o -> m DragSource

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, setStaticName, setTouchOnly.

dragCancel

dragSourceDragCancel

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a)

=> a

source: a GtkDragSource

-> m ()

Cancels a currently ongoing drag operation.

getActions

dragSourceGetActions

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a)

=> a

source: a GtkDragSource

-> m [DragAction]

Returns: the actions set on source

Gets the actions that are currently set on the GtkDragSource.

getContent

dragSourceGetContent

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a)

=> a

source: a GtkDragSource

-> m (Maybe ContentProvider)

Returns: the GdkContentProvider of source

Gets the current content provider of a GtkDragSource.

getDrag

dragSourceGetDrag

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a)

=> a

source: a GtkDragSource

-> m (Maybe Drag)

Returns: the GdkDrag of the current drag operation

Returns the underlying GdkDrag object for an ongoing drag.

new

dragSourceNew

Arguments

:: (HasCallStack, MonadIO m)

=> m DragSource

Returns: the new GtkDragSource

Creates a new GtkDragSource object.

setActions

dragSourceSetActions

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a)

=> a

source: a GtkDragSource

-> [DragAction]

actions: the actions to offer

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

dragSourceSetContent

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a, IsContentProvider b)

=> a

source: a GtkDragSource

-> Maybe b

content: a GdkContentProvider

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

dragSourceSetIcon

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a, IsPaintable b)

=> a

source: a GtkDragSource

-> Maybe b

paintable: the GdkPaintable to use as icon

-> Int32

hotX: the hotspot X coordinate on the icon

-> Int32

hotY: the hotspot Y coordinate on the icon

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

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]

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

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

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)

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)

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

Set the value of the “content” property. When overloading is enabled, this is equivalent to

set dragSource [ #content := value ]

Signals

dragBegin

type DragSourceDragBeginCallback

Arguments

 = Drag

drag: the GdkDrag object

-> IO ()

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

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

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

Arguments

 = Drag

drag: the GdkDrag object

-> DragCancelReason

reason: information on why the drag failed

-> IO Bool

Returns: True if the failed drag operation has been already handled

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

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

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

Arguments

 = Drag

drag: the GdkDrag object

-> Bool

deleteData: True if the drag was performing DragActionMove, and the data should be deleted

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

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

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

Arguments

 = Double

x: the X coordinate of the drag starting point

-> Double

y: the Y coordinate of the drag starting point

-> IO (Maybe ContentProvider)

Returns: a GdkContentProvider

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

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

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