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

Contents

- Exported types
- Methods
  - getActions
  - getCurrentDrop
  - getDrop
  - getFormats
  - getGtypes
  - getPreload
  - getValue
  - new
  - reject
  - setActions
  - setGtypes
  - setPreload
- Properties
  - actions
  - currentDrop
  - drop
  - formats
  - preload
  - value
- Signals
  - accept
  - drop
  - enter
  - leave
  - motion

Description

An event controller to receive Drag-and-Drop operations.

The most basic way to use a `GtkDropTarget` to receive drops on a widget is to create it via `dropTargetNew`, passing in the `GType` of the data you want to receive and connect to the DropTarget::drop signal to receive the data:

### c code

    static gboolean
    on_drop (GtkDropTarget *target,
             const GValue  *value,
             double         x,
             double         y,
             gpointer       data)
    {
      MyWidget *self = data;

      // Call the appropriate setter depending on the type of data
      // that we received
      if (G_VALUE_HOLDS (value, G_TYPE_FILE))
        my_widget_set_file (self, g_value_get_object (value));
      else if (G_VALUE_HOLDS (value, GDK_TYPE_PIXBUF))
        my_widget_set_pixbuf (self, g_value_get_object (value));
      else
        return FALSE;

      return TRUE;
    }

    static void
    my_widget_init (MyWidget *self)
    {
      GtkDropTarget *target =
        gtk_drop_target_new (G_TYPE_INVALID, GDK_ACTION_COPY);

      // This widget accepts two types of drop types: GFile objects
      // and GdkPixbuf objects
      gtk_drop_target_set_gtypes (target, (GType [2]) {
        G_TYPE_FILE,
        GDK_TYPE_PIXBUF,
      }, 2);

      g_signal_connect (target, "drop", G_CALLBACK (on_drop), self);
      gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (target));
    }

`GtkDropTarget` supports more options, such as:

- rejecting potential drops via the DropTarget::accept signal and the `dropTargetReject` function to let other drop targets handle the drop
- tracking an ongoing drag operation before the drop via the DropTarget::enter, DropTarget::motion and DropTarget::leave signals
- configuring how to receive data by setting the DropTarget:preload property and listening for its availability via the DropTarget:value property

However, `GtkDropTarget` is ultimately modeled in a synchronous way and only supports data transferred via `GType`. If you want full control over an ongoing drop, the `DropTargetAsync` object gives you this ability.

While a pointer is dragged over the drop target's widget and the drop has not been rejected, that widget will receive the `StateFlagsDropActive` state, which can be used to style the widget.

If you are not interested in receiving the drop, but just want to update UI state during a Drag-and-Drop operation (e.g. switching tabs), you can use `DropControllerMotion`.

Synopsis

- newtype DropTarget = DropTarget (ManagedPtr DropTarget)
- class (GObject o, IsDescendantOf DropTarget o) => IsDropTarget o
- toDropTarget :: (MonadIO m, IsDropTarget o) => o -> m DropTarget
- dropTargetGetActions :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> m [DragAction]
- dropTargetGetCurrentDrop :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> m (Maybe Drop)
- dropTargetGetDrop :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> m (Maybe Drop)
- dropTargetGetFormats :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> m (Maybe ContentFormats)
- dropTargetGetGtypes :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> m (Maybe [GType])
- dropTargetGetPreload :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> m Bool
- dropTargetGetValue :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> m (Maybe GValue)
- dropTargetNew :: (HasCallStack, MonadIO m) => GType -> [DragAction] -> m DropTarget
- dropTargetReject :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> m ()
- dropTargetSetActions :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> [DragAction] -> m ()
- dropTargetSetGtypes :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> Maybe [GType] -> m ()
- dropTargetSetPreload :: (HasCallStack, MonadIO m, IsDropTarget a) => a -> Bool -> m ()
- constructDropTargetActions :: (IsDropTarget o, MonadIO m) => [DragAction] -> m (GValueConstruct o)
- getDropTargetActions :: (MonadIO m, IsDropTarget o) => o -> m [DragAction]
- setDropTargetActions :: (MonadIO m, IsDropTarget o) => o -> [DragAction] -> m ()
- getDropTargetCurrentDrop :: (MonadIO m, IsDropTarget o) => o -> m (Maybe Drop)
- getDropTargetDrop :: (MonadIO m, IsDropTarget o) => o -> m (Maybe Drop)
- constructDropTargetFormats :: (IsDropTarget o, MonadIO m) => ContentFormats -> m (GValueConstruct o)
- getDropTargetFormats :: (MonadIO m, IsDropTarget o) => o -> m (Maybe ContentFormats)
- constructDropTargetPreload :: (IsDropTarget o, MonadIO m) => Bool -> m (GValueConstruct o)
- getDropTargetPreload :: (MonadIO m, IsDropTarget o) => o -> m Bool
- setDropTargetPreload :: (MonadIO m, IsDropTarget o) => o -> Bool -> m ()
- getDropTargetValue :: (MonadIO m, IsDropTarget o) => o -> m (Maybe GValue)
- type DropTargetAcceptCallback = Drop -> IO Bool
- afterDropTargetAccept :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetAcceptCallback) -> m SignalHandlerId
- onDropTargetAccept :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetAcceptCallback) -> m SignalHandlerId
- type DropTargetDropCallback = GValue -> Double -> Double -> IO Bool
- afterDropTargetDrop :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetDropCallback) -> m SignalHandlerId
- onDropTargetDrop :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetDropCallback) -> m SignalHandlerId
- type DropTargetEnterCallback = Double -> Double -> IO [DragAction]
- afterDropTargetEnter :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetEnterCallback) -> m SignalHandlerId
- onDropTargetEnter :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetEnterCallback) -> m SignalHandlerId
- type DropTargetLeaveCallback = IO ()
- afterDropTargetLeave :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetLeaveCallback) -> m SignalHandlerId
- onDropTargetLeave :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetLeaveCallback) -> m SignalHandlerId
- type DropTargetMotionCallback = Double -> Double -> IO [DragAction]
- afterDropTargetMotion :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetMotionCallback) -> m SignalHandlerId
- onDropTargetMotion :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetMotionCallback) -> m SignalHandlerId

# Exported types

newtype DropTarget Source #

Memory-managed wrapper type.

Constructors

DropTarget (ManagedPtr DropTarget) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf DropTarget o) => IsDropTarget o Source #

Type class for types which can be safely cast to `DropTarget`, for instance with `toDropTarget`.

#### Instances

Instances details

(GObject o, IsDescendantOf DropTarget o) => IsDropTarget o Source # |
Instance details Defined in GI.Gtk.Objects.DropTarget

toDropTarget :: (MonadIO m, IsDropTarget o) => o -> m DropTarget Source #

Cast to `DropTarget`, 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, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, reject, reset, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getActions, getCurrentDrop, getCurrentEvent, getCurrentEventDevice, getCurrentEventState, getCurrentEventTime, getData, getDrop, getFormats, getGtypes, getName, getPreload, getPropagationLimit, getPropagationPhase, getProperty, getQdata, getValue, getWidget.

#### Setters

setActions, setData, setDataFull, setGtypes, setName, setPreload, setPropagationLimit, setPropagationPhase, setProperty, setStaticName.

## getActions

dropTargetGetActions Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> m [DragAction] | Returns: the actions that this drop target supports

Gets the actions that this drop target supports.

## getCurrentDrop

dropTargetGetCurrentDrop Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> m (Maybe Drop) | Returns: The current drop

Gets the currently handled drop operation.

If no drop operation is going on, `Nothing` is returned.

Since: 4.4

## getDrop

dropTargetGetDrop Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> m (Maybe Drop) | Returns: The current drop

Deprecated: (Since version 4.4)Use `dropTargetGetCurrentDrop` instead

Gets the currently handled drop operation.

If no drop operation is going on, `Nothing` is returned.

## getFormats

dropTargetGetFormats Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> m (Maybe ContentFormats) | Returns: the supported data formats

Gets the data formats that this drop target accepts.

If the result is `Nothing`, all formats are expected to be supported.

## getGtypes

dropTargetGetGtypes Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> m (Maybe [GType]) | Returns: the `G_TYPE_INVALID`-terminated array of types included in formats

Gets the list of supported `GType`s that can be dropped on the target.

If no types have been set, `NULL` will be returned.

## getPreload

dropTargetGetPreload Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> m Bool | Returns: `True` if drop data should be preloaded

Gets whether data should be preloaded on hover.

## getValue

dropTargetGetValue Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> m (Maybe GValue) | Returns: The current drop data

Gets the current drop data, as a `GValue`.

## new

dropTargetNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GType | `type`: The supported type or `G_TYPE_INVALID`
-> [DragAction] | `actions`: the supported actions
-> m DropTarget | Returns: the new `GtkDropTarget`

Creates a new `GtkDropTarget` object.

If the drop target should support more than 1 type, pass `G_TYPE_INVALID` for `type` and then call `dropTargetSetGtypes`.

## reject

dropTargetReject Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> m () |

Rejects the ongoing drop operation.

If no drop operation is ongoing, i.e when DropTarget:currentDrop is `Nothing`, this function does nothing.

This function should be used when delaying the decision on whether to accept a drag or not until after reading the data.

## setActions

dropTargetSetActions Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> [DragAction] | `actions`: the supported actions
-> m () |

Sets the actions that this drop target supports.

## setGtypes

dropTargetSetGtypes Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> Maybe [GType] | `types`: all supported `GType`s that can be dropped on the target
-> m () |

Sets the supported `GType`s for this drop target.

## setPreload

dropTargetSetPreload Source #

Arguments

:: (HasCallStack, MonadIO m, IsDropTarget a) |
=> a | `self`: a `GtkDropTarget`
-> Bool | `preload`: `True` to preload drop data
-> m () |

Sets whether data should be preloaded on hover.

# Properties

## actions

The `GdkDragActions` that this drop target supports.

constructDropTargetActions :: (IsDropTarget 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`.

getDropTargetActions :: (MonadIO m, IsDropTarget o) => o -> m [DragAction] Source #

Get the value of the “`actions`” property. When overloading is enabled, this is equivalent to

    get dropTarget #actions

setDropTargetActions :: (MonadIO m, IsDropTarget o) => o -> [DragAction] -> m () Source #

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

    set dropTarget [ #actions := value ]

## currentDrop

The `GdkDrop` that is currently being performed.

Since: 4.4

getDropTargetCurrentDrop :: (MonadIO m, IsDropTarget o) => o -> m (Maybe Drop) Source #

Get the value of the “`current-drop`” property. When overloading is enabled, this is equivalent to

    get dropTarget #currentDrop

## drop

The `GdkDrop` that is currently being performed.

getDropTargetDrop :: (MonadIO m, IsDropTarget o) => o -> m (Maybe Drop) Source #

Get the value of the “`drop`” property. When overloading is enabled, this is equivalent to

    get dropTarget #drop

## formats

The `GdkContentFormats` that determine the supported data formats.

constructDropTargetFormats :: (IsDropTarget o, MonadIO m) => ContentFormats -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`formats`” property. This is rarely needed directly, but it is used by `new`.

getDropTargetFormats :: (MonadIO m, IsDropTarget o) => o -> m (Maybe ContentFormats) Source #

Get the value of the “`formats`” property. When overloading is enabled, this is equivalent to

    get dropTarget #formats

## preload

Whether the drop data should be preloaded when the pointer is only hovering over the widget but has not been released.

Setting this property allows finer grained reaction to an ongoing drop at the cost of loading more data.

The default value for this property is `False` to avoid downloading huge amounts of data by accident.

For example, if somebody drags a full document of gigabytes of text from a text editor across a widget with a preloading drop target, this data will be downloaded, even if the data is ultimately dropped elsewhere.

For a lot of data formats, the amount of data is very small (like `GDK_TYPE_RGBA`), so enabling this property does not hurt at all. And for local-only Drag-and-Drop operations, no data transfer is done, so enabling it there is free.

constructDropTargetPreload :: (IsDropTarget o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`preload`” property. This is rarely needed directly, but it is used by `new`.

getDropTargetPreload :: (MonadIO m, IsDropTarget o) => o -> m Bool Source #

Get the value of the “`preload`” property. When overloading is enabled, this is equivalent to

    get dropTarget #preload

setDropTargetPreload :: (MonadIO m, IsDropTarget o) => o -> Bool -> m () Source #

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

    set dropTarget [ #preload := value ]

## value

The value for this drop operation.

This is `Nothing` if the data has not been loaded yet or no drop operation is going on.

Data may be available before the DropTarget::drop signal gets emitted - for example when the DropTarget:preload property is set. You can use the notify signal to be notified of available data.

getDropTargetValue :: (MonadIO m, IsDropTarget o) => o -> m (Maybe GValue) Source #

Get the value of the “`value`” property. When overloading is enabled, this is equivalent to

    get dropTarget #value

# Signals

## accept

type DropTargetAcceptCallback Source #

Arguments

= Drop | `drop`: the `GdkDrop`
-> IO Bool | Returns: `True` if `drop` is accepted

Emitted on the drop site when a drop operation is about to begin.

If the drop is not accepted, `False` will be returned and the drop target will ignore the drop. If `True` is returned, the drop is accepted for now but may be rejected later via a call to `dropTargetReject` or ultimately by returning `False` from a DropTarget::drop handler.

The default handler for this signal decides whether to accept the drop based on the formats provided by the `drop`.

If the decision whether the drop will be accepted or rejected depends on the data, this function should return `True`, the DropTarget:preload property should be set and the value should be inspected via the notify:value signal, calling `dropTargetReject` if required.

afterDropTargetAccept :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetAcceptCallback) -> m SignalHandlerId Source #

Connect a signal handler for the accept signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after dropTarget #accept 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.

onDropTargetAccept :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetAcceptCallback) -> m SignalHandlerId Source #

Connect a signal handler for the accept signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on dropTarget #accept callback

## drop

type DropTargetDropCallback Source #

Arguments

= GValue | `value`: the `GValue` being dropped
-> Double | `x`: the x coordinate of the current pointer position
-> Double | `y`: the y coordinate of the current pointer position
-> IO Bool | Returns: whether the drop was accepted at the given pointer position

Emitted on the drop site when the user drops the data onto the widget.

The signal handler must determine whether the pointer 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, this handler will accept the drop. The handler is responsible for using the given `value` and performing the drop operation.

afterDropTargetDrop :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetDropCallback) -> m SignalHandlerId Source #

Connect a signal handler for the drop signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after dropTarget #drop 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.

onDropTargetDrop :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetDropCallback) -> m SignalHandlerId Source #

Connect a signal handler for the drop signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on dropTarget #drop callback

## enter

type DropTargetEnterCallback Source #

Arguments

= Double | `x`: the x coordinate of the current pointer position
-> Double | `y`: the y coordinate of the current pointer position
-> IO [DragAction] | Returns: Preferred action for this drag operation or `GDK_ACTION_NONE` if dropping is not supported at the current `x`,`y` location.

Emitted on the drop site when the pointer enters the widget.

It can be used to set up custom highlighting.

afterDropTargetEnter :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetEnterCallback) -> m SignalHandlerId Source #

Connect a signal handler for the enter signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after dropTarget #enter 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.

onDropTargetEnter :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetEnterCallback) -> m SignalHandlerId Source #

Connect a signal handler for the enter signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on dropTarget #enter callback

## leave

type DropTargetLeaveCallback = IO () Source #

Emitted on the drop site when the pointer leaves the widget.

Its main purpose it to undo things done in DropTarget::enter.

afterDropTargetLeave :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetLeaveCallback) -> m SignalHandlerId Source #

Connect a signal handler for the leave signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after dropTarget #leave 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.

onDropTargetLeave :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetLeaveCallback) -> m SignalHandlerId Source #

Connect a signal handler for the leave signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on dropTarget #leave callback

## motion

type DropTargetMotionCallback Source #

Arguments

= Double | `x`: the x coordinate of the current pointer position
-> Double | `y`: the y coordinate of the current pointer position
-> IO [DragAction] | Returns: Preferred action for this drag operation or `GDK_ACTION_NONE` if dropping is not supported at the current `x`,`y` location.

Emitted while the pointer is moving over the drop target.

afterDropTargetMotion :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetMotionCallback) -> m SignalHandlerId Source #

Connect a signal handler for the motion signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after dropTarget #motion 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.

onDropTargetMotion :: (IsDropTarget a, MonadIO m) => a -> ((?self :: a) => DropTargetMotionCallback) -> m SignalHandlerId Source #

Connect a signal handler for the motion signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on dropTarget #motion callback