gi-gtk4-4.0.12: Gtk 4.x bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.DragSource

Contents

- Exported types
- Methods
  - dragCancel
  - getActions
  - getContent
  - getDrag
  - new
  - setActions
  - setContent
  - setIcon
- Properties
  - actions
  - content
- Signals
  - dragBegin
  - dragCancel
  - dragEnd
  - prepare

Description

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.

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.

Constructors

DragSource (ManagedPtr DragSource) |

#### Instances

Instances details

Eq DragSource Source # |
Instance details Defined in GI.Gtk.Objects.DragSource Methods (==) :: DragSource -> DragSource -> Bool Source # (/=) :: DragSource -> DragSource -> Bool Source #
GObject DragSource Source # |
Instance details Defined in GI.Gtk.Objects.DragSource
ManagedPtrNewtype DragSource Source # |
Instance details Defined in GI.Gtk.Objects.DragSource Methods toManagedPtr :: DragSource -> ManagedPtr DragSource Source #
TypedObject DragSource Source # |
Instance details Defined in GI.Gtk.Objects.DragSource Methods glibType :: IO GType Source #
HasParentTypes DragSource Source # |
Instance details Defined in GI.Gtk.Objects.DragSource
IsGValue (Maybe DragSource) Source # | Convert `DragSource` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.DragSource Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe DragSource -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe DragSource) Source #
type ParentTypes DragSource Source # |
Instance details Defined in GI.Gtk.Objects.DragSource type ParentTypes DragSource = '[GestureSingle, Gesture, EventController, Object]

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

Instances details

(GObject o, IsDescendantOf DragSource o) => IsDragSource o Source # |
Instance details 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

Expand

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

Arguments

:: (HasCallStack, MonadIO m, IsDragSource a) |
=> a | `source`: a `GtkDragSource`
-> m () |

Cancels a currently ongoing drag operation.

## getActions

dragSourceGetActions Source #

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

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

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

Arguments

:: (HasCallStack, MonadIO m) |
=> m DragSource | Returns: the new `GtkDragSource`

Creates a new `GtkDragSource` object.

## setActions

dragSourceSetActions Source #

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

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

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

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

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

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

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