GI.Gtk.Objects.DragSource

GtkDragSource is an auxiliary object that is used to initiate Drag-And-Drop operations. It 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.

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, DragSource has prepare and 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. The dragBegin signal is emitted after the Drag object has been created, and can be used to set up the drag icon.

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

IsGValue DragSource

Convert DragSource to and from GValue with toGValue and fromGValue.

Defined in GI.Gtk.Objects.DragSource

Methods

toGValue :: DragSource -> IO GValue

fromGValue :: GValue -> IO 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

GObject DragSource

Defined in GI.Gtk.Objects.DragSource

HasParentTypes DragSource

Defined in GI.Gtk.Objects.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

Overloaded methods

dragCancel

dragSourceDragCancel

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a)

=> a

source: a DragSource

-> m ()

Cancels a currently ongoing drag operation.

getActions

dragSourceGetActions

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a)

=> a

source: a DragSource

-> m [DragAction]

Returns: the actions set on source

Gets the actions that are currently set on the DragSource.

getContent

dragSourceGetContent

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a)

=> a

source: a DragSource

-> m ContentProvider

Returns: the ContentProvider of source

Gets the current content provider of a DragSource.

getDrag

dragSourceGetDrag

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a)

=> a

source: a DragSource

-> m (Maybe Drag)

Returns: the Drag of the current drag operation, or Nothing

Returns the underlying Drag object for an ongoing drag.

new

dragSourceNew

Arguments

:: (HasCallStack, MonadIO m)

=> m DragSource

Returns: the new DragSource

Creates a new DragSource object.

setActions

dragSourceSetActions

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a)

=> a

source: a DragSource

-> [DragAction]

actions: the actions to offer

-> m ()

Sets the actions on the DragSource.

During a DND operation, the actions are offered to potential drop targets. If actions include DragActionMove, you need to listen to the dragEnd signal and handle deleteData being True.

This function can be called before a drag is started, or in a handler for the prepare signal.

setContent

dragSourceSetContent

Arguments

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

=> a

source: a DragSource

-> Maybe b

content: a ContentProvider, or Nothing

-> m ()

Sets a content provider on a DragSource.

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 prepare signal.

You may consider setting the content provider back to Nothing in a dragEnd signal handler.

setIcon

dragSourceSetIcon

Arguments

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

=> a

source: a DragSource

-> Maybe b

paintable: the Paintable to use as icon, or Nothing

-> 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 prepare or dragBegin signal handler.

Properties

actions

The actions that are supported by drag operations from the source.

Note that you must handle the 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, in the form of a ContentProvider.

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 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 C_DragSourceDragBeginCallback = Ptr () -> Ptr Drag -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type DragSourceDragBeginCallback

Arguments

 = Drag

drag: the Drag object

-> IO ()

The dragBegin signal is 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 -> 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

genClosure_DragSourceDragBegin :: MonadIO m => DragSourceDragBeginCallback -> m (GClosure C_DragSourceDragBeginCallback)

Wrap the callback into a GClosure.

mk_DragSourceDragBeginCallback :: C_DragSourceDragBeginCallback -> IO (FunPtr C_DragSourceDragBeginCallback)

Generate a function pointer callable from C code, from a C_DragSourceDragBeginCallback.

noDragSourceDragBeginCallback :: Maybe DragSourceDragBeginCallback

A convenience synonym for Nothing :: Maybe DragSourceDragBeginCallback.

onDragSourceDragBegin :: (IsDragSource a, MonadIO m) => 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

wrap_DragSourceDragBeginCallback :: DragSourceDragBeginCallback -> C_DragSourceDragBeginCallback

Wrap a DragSourceDragBeginCallback into a C_DragSourceDragBeginCallback.

dragCancel

type C_DragSourceDragCancelCallback = Ptr () -> Ptr Drag -> CUInt -> Ptr () -> IO CInt

Type for the callback on the (unwrapped) C side.

type DragSourceDragCancelCallback

Arguments

 = Drag

drag: the Drag object

-> DragCancelReason

reason: information on why the drag failed

-> IO Bool

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

The dragCancel signal is 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 -> 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

genClosure_DragSourceDragCancel :: MonadIO m => DragSourceDragCancelCallback -> m (GClosure C_DragSourceDragCancelCallback)

Wrap the callback into a GClosure.

mk_DragSourceDragCancelCallback :: C_DragSourceDragCancelCallback -> IO (FunPtr C_DragSourceDragCancelCallback)

Generate a function pointer callable from C code, from a C_DragSourceDragCancelCallback.

noDragSourceDragCancelCallback :: Maybe DragSourceDragCancelCallback

A convenience synonym for Nothing :: Maybe DragSourceDragCancelCallback.

onDragSourceDragCancel :: (IsDragSource a, MonadIO m) => 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

wrap_DragSourceDragCancelCallback :: DragSourceDragCancelCallback -> C_DragSourceDragCancelCallback

Wrap a DragSourceDragCancelCallback into a C_DragSourceDragCancelCallback.

dragEnd

type C_DragSourceDragEndCallback = Ptr () -> Ptr Drag -> CInt -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type DragSourceDragEndCallback

Arguments

 = Drag

drag: the Drag object

-> Bool

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

-> 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 prepare or dragBegin.

afterDragSourceDragEnd :: (IsDragSource a, MonadIO m) => 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

genClosure_DragSourceDragEnd :: MonadIO m => DragSourceDragEndCallback -> m (GClosure C_DragSourceDragEndCallback)

Wrap the callback into a GClosure.

mk_DragSourceDragEndCallback :: C_DragSourceDragEndCallback -> IO (FunPtr C_DragSourceDragEndCallback)

Generate a function pointer callable from C code, from a C_DragSourceDragEndCallback.

noDragSourceDragEndCallback :: Maybe DragSourceDragEndCallback

A convenience synonym for Nothing :: Maybe DragSourceDragEndCallback.

onDragSourceDragEnd :: (IsDragSource a, MonadIO m) => 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

wrap_DragSourceDragEndCallback :: DragSourceDragEndCallback -> C_DragSourceDragEndCallback

Wrap a DragSourceDragEndCallback into a C_DragSourceDragEndCallback.

prepare

type C_DragSourcePrepareCallback = Ptr () -> CDouble -> CDouble -> Ptr () -> IO (Ptr ContentProvider)

Type for the callback on the (unwrapped) C side.

type DragSourcePrepareCallback

Arguments

 = Double

x: the X coordinate of the drag starting point

-> Double

y: the Y coordinate fo the drag starting point

-> IO (Maybe ContentProvider)

Returns: a ContentProvider, or Nothing

The prepare signal is emitted when a drag is about to be initiated. It returns the * ContentProvider 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 -> 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

genClosure_DragSourcePrepare :: MonadIO m => DragSourcePrepareCallback -> m (GClosure C_DragSourcePrepareCallback)

Wrap the callback into a GClosure.

mk_DragSourcePrepareCallback :: C_DragSourcePrepareCallback -> IO (FunPtr C_DragSourcePrepareCallback)

Generate a function pointer callable from C code, from a C_DragSourcePrepareCallback.

noDragSourcePrepareCallback :: Maybe DragSourcePrepareCallback

A convenience synonym for Nothing :: Maybe DragSourcePrepareCallback.

onDragSourcePrepare :: (IsDragSource a, MonadIO m) => 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

wrap_DragSourcePrepareCallback :: DragSourcePrepareCallback -> C_DragSourcePrepareCallback

Wrap a DragSourcePrepareCallback into a C_DragSourcePrepareCallback.