## Drag And Drop Drag And Drop — Functions for controlling drag and drop handling |

## Functions

void | gdk_drag_drop_done ()
GdkDrag * | gdk_drag_begin ()
GdkDisplay * | gdk_drag_get_display ()
GdkContentProvider * | gdk_drag_get_content ()
GdkDragAction | gdk_drag_get_actions ()
GdkDragAction | gdk_drag_get_selected_action ()
GdkContentFormats * | gdk_drag_get_formats ()
GdkDevice * | gdk_drag_get_device ()
GdkSurface * | gdk_drag_get_surface ()
GdkSurface * | gdk_drag_get_drag_surface ()
void | gdk_drag_set_hotspot ()
gboolean | gdk_drag_action_is_unique ()
gboolean | gdk_drag_surface_present ()
GdkDisplay * | gdk_drop_get_display ()
GdkDevice * | gdk_drop_get_device ()
GdkSurface * | gdk_drop_get_surface ()
GdkContentFormats * | gdk_drop_get_formats ()
GdkDragAction | gdk_drop_get_actions ()
GdkDrag * | gdk_drop_get_drag ()
void | gdk_drop_status ()
void | gdk_drop_finish ()
void | gdk_drop_read_async ()
GInputStream * | gdk_drop_read_finish ()
void | gdk_drop_read_value_async ()
const GValue * | gdk_drop_read_value_finish ()

## Properties

GdkDragAction | actions | Read / Write
GdkContentProvider * | content | Read / Write / Construct Only
GdkDevice * | device | Read / Write / Construct Only
GdkDisplay * | display | Read
GdkContentFormats * | formats | Read / Write / Construct Only
GdkDragAction | selected-action | Read / Write
GdkSurface * | surface | Read / Write / Construct Only
GdkDragAction | actions | Read / Write / Construct Only
GdkDevice * | device | Read / Write / Construct Only
GdkDisplay * | display | Read
GdkDrag * | drag | Read / Write / Construct Only
GdkContentFormats * | formats | Read / Write / Construct Only
GdkSurface * | surface | Read / Write / Construct Only

## Signals

void | cancel | Run Last
void | dnd-finished | Run Last
void | drop-performed | Run Last

## Types and Values

| GdkDrag
| GdkDrop
enum | GdkDragCancelReason
enum | GdkDragAction
#define | GDK_ACTION_ALL
| GdkDragSurface
| GdkDragSurfaceInterface

## Object Hierarchy

        GInterface
        ╰── GdkDragSurface
        GObject
        ├── GdkDrag
        ╰── GdkDrop

## Prerequisites

GdkDragSurface requires GdkSurface.

## Includes

    #include <gdk/gdk.h>

## Description

These functions provide a low-level interface for drag and drop.

The GdkDrag object represents the source side of an ongoing DND operation. It is created when a drag is started, and stays alive for duration of the DND operation. After a drag has been started with `gdk_drag_begin()`, the caller gets informed about the status of the ongoing drag operation with signals on the GdkDrag object.

The GdkDrop object represents the target side of an ongoing DND operation. Possible drop sites get informed about the status of the ongoing drag operation with events of type `GDK_DRAG_ENTER`, `GDK_DRAG_LEAVE`, `GDK_DRAG_MOTION` and `GDK_DROP_START`. The GdkDrop object can be obtained from these GdkEvents using `gdk_dnd_event_get_drop()`.

The actual data transfer is initiated from the target side via an async read, using one of the GdkDrop functions for this purpose: `gdk_drop_read_async()` or `gdk_drop_read_value_async()`.

GTK provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK applications. See the Drag and Drop section of the GTK documentation for more information.

## Functions

### gdk_drag_drop_done ()

    void
    gdk_drag_drop_done (GdkDrag *drag,
                        gboolean success);

Inform GDK if the drop ended successfully. Passing `FALSE` for `success` may trigger a drag cancellation animation.

This function is called by the drag source, and should be the last call before dropping the reference to the `drag` .

The GdkDrag will only take the first `gdk_drag_drop_done()` call as effective, if this function is called multiple times, all subsequent calls will be ignored.

#### Parameters

drag | a GdkDrag |
success | whether the drag was ultimatively successful |

### gdk_drag_begin ()

    GdkDrag *
    gdk_drag_begin (GdkSurface *surface,
                    GdkDevice *device,
                    GdkContentProvider *content,
                    GdkDragAction actions,
                    double dx,
                    double dy);

Starts a drag and creates a new drag context for it.

This function is called by the drag source. After this call, you probably want to set up the drag icon using the surface returned by `gdk_drag_get_drag_surface()`.

This function returns a reference to the GdkDrag object, but GTK keeps its own reference as well, as long as the DND operation is going on.

Note: if `actions` include `GDK_ACTION_MOVE`, you need to listen for the “dnd-finished” signal and delete the data at the source if `gdk_drag_get_selected_action()` returns `GDK_ACTION_MOVE`.

#### Parameters

surface | the source surface for this drag |
device | the device that controls this drag |
content | the offered content. | [transfer none]
actions | the actions supported by this drag |
dx | the x offset to `device` 's position where the drag nominally started |
dy | the y offset to `device` 's position where the drag nominally started |

#### Returns

a newly created GdkDrag or `NULL` on error.

[transfer full][nullable]

### gdk_drag_get_display ()

    GdkDisplay *
    gdk_drag_get_display (GdkDrag *drag);

Gets the GdkDisplay that the drag object was created for.

#### Parameters

drag | a GdkDrag |

#### Returns

a GdkDisplay.

[transfer none]

### gdk_drag_get_content ()

    GdkContentProvider *
    gdk_drag_get_content (GdkDrag *drag);

Returns the GdkContentProvider associated to the GdkDrag object.

#### Parameters

drag | a GdkDrag |

#### Returns

The GdkContentProvider associated to `drag` .

[transfer none]

### gdk_drag_get_actions ()

    GdkDragAction
    gdk_drag_get_actions (GdkDrag *drag);

Determines the bitmask of possible actions proposed by the source.

#### Parameters

drag | a GdkDrag |

#### Returns

the GdkDragAction flags

### gdk_drag_get_selected_action ()

    GdkDragAction
    gdk_drag_get_selected_action (GdkDrag *drag);

Determines the action chosen by the drag destination.

#### Parameters

drag | a GdkDrag |

#### Returns

a GdkDragAction value

### gdk_drag_get_formats ()

    GdkContentFormats *
    gdk_drag_get_formats (GdkDrag *drag);

Retrieves the formats supported by this GdkDrag object.

#### Parameters

drag | a GdkDrag |

#### Returns

a GdkContentFormats.

[transfer none]

### gdk_drag_get_device ()

    GdkDevice *
    gdk_drag_get_device (GdkDrag *drag);

Returns the GdkDevice associated to the GdkDrag object.

#### Parameters

drag | a GdkDrag |

#### Returns

The GdkDevice associated to `drag` .

[transfer none]

### gdk_drag_get_surface ()

    GdkSurface *
    gdk_drag_get_surface (GdkDrag *drag);

Returns the GdkSurface where the drag originates.

#### Parameters

drag | a GdkDrag |

#### Returns

The GdkSurface where the drag originates.

[transfer none]

### gdk_drag_get_drag_surface ()

    GdkSurface *
    gdk_drag_get_drag_surface (GdkDrag *drag);

Returns the surface on which the drag icon should be rendered during the drag operation. Note that the surface may not be available until the drag operation has begun. GDK will move the surface in accordance with the ongoing drag operation. The surface is owned by `drag` and will be destroyed when the drag operation is over.

#### Parameters

drag | a GdkDrag |

#### Returns

the drag surface, or `NULL`.

[nullable][transfer none]

### gdk_drag_set_hotspot ()

    void
    gdk_drag_set_hotspot (GdkDrag *drag,
                          int hot_x,
                          int hot_y);

Sets the position of the drag surface that will be kept under the cursor hotspot. Initially, the hotspot is at the top left corner of the drag surface.

#### Parameters

drag | a GdkDrag |
hot_x | x coordinate of the drag surface hotspot |
hot_y | y coordinate of the drag surface hotspot |

### gdk_drag_action_is_unique ()

    gboolean
    gdk_drag_action_is_unique (GdkDragAction action);

Checks if `action` represents a single action or if it includes multiple flags that can be selected from.

When `action` is 0 - ie no action was given, `TRUE` is returned.

#### Parameters

action | a GdkDragAction |

#### Returns

`TRUE` if exactly one action was given

### gdk_drag_surface_present ()

    gboolean
    gdk_drag_surface_present (GdkDragSurface *drag_surface,
                              int width,
                              int height);

Present `drag_surface` .

#### Parameters

drag_surface | the GdkDragSurface to show |
width | the unconstrained drag_surface width to layout |
height | the unconstrained drag_surface height to layout |

#### Returns

`FALSE` if it failed to be presented, otherwise `TRUE`.

### gdk_drop_get_display ()

    GdkDisplay *
    gdk_drop_get_display (GdkDrop *self);

Gets the GdkDisplay that `self` was created for.

#### Parameters

self | a GdkDrop |

#### Returns

a GdkDisplay.

[transfer none]

### gdk_drop_get_device ()

    GdkDevice *
    gdk_drop_get_device (GdkDrop *self);

Returns the GdkDevice performing the drop.

#### Parameters

self | a GdkDrop |

#### Returns

The GdkDevice performing the drop.

[transfer none]

### gdk_drop_get_surface ()

    GdkSurface *
    gdk_drop_get_surface (GdkDrop *self);

Returns the GdkSurface performing the drop.

#### Parameters

self | a GdkDrop |

#### Returns

The GdkSurface performing the drop.

[transfer none]

### gdk_drop_get_formats ()

    GdkContentFormats *
    gdk_drop_get_formats (GdkDrop *self);

Returns the GdkContentFormats that the drop offers the data to be read in.

#### Parameters

self | a GdkDrop |

#### Returns

The possible GdkContentFormats.

[transfer none]

### gdk_drop_get_actions ()

    GdkDragAction
    gdk_drop_get_actions (GdkDrop *self);

Returns the possible actions for this GdkDrop. If this value contains multiple actions - ie `gdk_drag_action_is_unique()` returns `FALSE` for the result - `gdk_drop_finish()` must choose the action to use when accepting the drop. This will only happen if you passed `GDK_ACTION_ASK` as one of the possible actions in `gdk_drop_status()`. `GDK_ACTION_ASK` itself will not be included in the actions returned by this function.

This value may change over the lifetime of the GdkDrop both as a response to source side actions as well as to calls to `gdk_drop_status()` or `gdk_drop_finish()`. The source side will not change this value anymore once a drop has started.

#### Parameters

self | a GdkDrop |

#### Returns

The possible GdkDragActions

### gdk_drop_get_drag ()

    GdkDrag *
    gdk_drop_get_drag (GdkDrop *self);

If this is an in-app drag-and-drop operation, returns the GdkDrag that corresponds to this drop.

If it is not, `NULL` is returned.

#### Parameters

self | a GdkDrop |

#### Returns

the corresponding GdkDrag.

[transfer none][nullable]

### gdk_drop_status ()

    void
    gdk_drop_status (GdkDrop *self,
                     GdkDragAction actions,
                     GdkDragAction preferred);

Selects all actions that are potentially supported by the destination.

When calling this function, do not restrict the passed in actions to the ones provided by `gdk_drop_get_actions()`. Those actions may change in the future, even depending on the actions you provide here.

The `preferred` action is a hint to the drag'n'drop mechanism about which action to use when multiple actions are possible.

This function should be called by drag destinations in response to `GDK_DRAG_ENTER` or `GDK_DRAG_MOTION` events. If the destination does not yet know the exact actions it supports, it should set any possible actions first and then later call this function again.

#### Parameters

self | a GdkDrop |
actions | Supported actions of the destination, or 0 to indicate that a drop will not be accepted |
preferred | A unique action that's a member of `actions` indicating the preferred action. |

### gdk_drop_finish ()

    void
    gdk_drop_finish (GdkDrop *self,
                     GdkDragAction action);

Ends the drag operation after a drop.

The `action` must be a single action selected from the actions available via `gdk_drop_get_actions()`.

#### Parameters

self | a GdkDrop |
action | the action performed by the destination or 0 if the drop failed |

### gdk_drop_read_async ()

    void
    gdk_drop_read_async (GdkDrop *self,
                         const char **mime_types,
                         int io_priority,
                         GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Asynchronously read the dropped data from a GdkDrop in a format that complies with one of the mime types.

#### Parameters

self | a GdkDrop |
mime_types | pointer to an array of mime types. | [array zero-terminated=1][element-type utf8]
io_priority | the io priority for the read operation |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | the data to pass to `callback` . | [closure]

### gdk_drop_read_finish ()

    GInputStream *
    gdk_drop_read_finish (GdkDrop *self,
                          GAsyncResult *result,
                          const char **out_mime_type,
                          GError **error);

Finishes an async drop read operation, see `gdk_drop_read_async()`.

#### Parameters

self | a GdkDrop |
result | a GAsyncResult |
out_mime_type | return location for the used mime type. | [out][type utf8]
error | location to store error information on failure, or `NULL`. | [allow-none]

#### Returns

the GInputStream, or `NULL`.

[nullable][transfer full]

### gdk_drop_read_value_async ()

    void
    gdk_drop_read_value_async (GdkDrop *self,
                               GType type,
                               int io_priority,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Asynchronously request the drag operation's contents converted to the given `type` . When the operation is finished `callback` will be called. You can then call `gdk_drop_read_value_finish()` to get the resulting GValue.

For local drag'n'drop operations that are available in the given GType, the value will be copied directly. Otherwise, GDK will try to use `gdk_content_deserialize_async()` to convert the data.

#### Parameters

self | a GdkDrop |
type | a GType to read |
io_priority | the I/O priority of the request. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | callback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

### gdk_drop_read_value_finish ()

    const GValue *
    gdk_drop_read_value_finish (GdkDrop *self,
                                GAsyncResult *result,
                                GError **error);

Finishes an async drop read started with `gdk_drop_read_value_async()`.

#### Parameters

self | a GdkDrop |
result | a GAsyncResult |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

a GValue containing the result.

[transfer none]

## Types and Values

### GdkDrag

    typedef struct _GdkDrag GdkDrag;

The GdkDrag struct contains only private fields and should not be accessed directly.

### GdkDrop

    typedef struct _GdkDrop GdkDrop;

The GdkDrop struct contains only private fields and should not be accessed directly.

### enum GdkDragCancelReason

Used in GdkDrag to the reason of a cancelled DND operation.

#### Members

GDK_DRAG_CANCEL_NO_TARGET | There is no suitable drop target. |
GDK_DRAG_CANCEL_USER_CANCELLED | Drag cancelled by the user |
GDK_DRAG_CANCEL_ERROR | Unspecified error. |

### enum GdkDragAction

Used in GdkDrop and GdkDrag to indicate the actions that the destination can and should do with the dropped data.

#### Members

GDK_ACTION_COPY | Copy the data. |
GDK_ACTION_MOVE | Move the data, i.e. first copy it, then delete it from the source using the DELETE target of the X selection protocol. |
GDK_ACTION_LINK | Add a link to the data. Note that this is only useful if source and destination agree on what it means, and is not supported on all platforms. |
GDK_ACTION_ASK | Ask the user what to do with the data. |

### GDK_ACTION_ALL

    #define GDK_ACTION_ALL (GDK_ACTION_COPY | GDK_ACTION_MOVE | GDK_ACTION_LINK)

Defines all possible DND actions. This can be used in `gdk_drop_status()` messages when any drop can be accepted or a more specific drop method is not yet known.

### GdkDragSurface

    typedef struct _GdkDragSurface GdkDragSurface;

A GdkDragSurface is an interface implemented by GdkSurfaces used during a DND operation.

### GdkDragSurfaceInterface

    typedef struct {
      GTypeInterface g_iface;

      gboolean (* present) (GdkDragSurface *drag_surface,
                            int             width,
                            int             height);
    } GdkDragSurfaceInterface;

## Property Details

### The `“actions”` property

      “actions”                  GdkDragAction

The possible actions.

Owner: GdkDrag

Flags: Read / Write

### The `“content”` property

      “content”                  GdkContentProvider *

The GdkContentProvider.

Owner: GdkDrag

Flags: Read / Write / Construct Only

### The `“device”` property

      “device”                   GdkDevice *

The GdkDevice that is performing the drag.

Owner: GdkDrag

Flags: Read / Write / Construct Only

### The `“display”` property

      “display”                  GdkDisplay *

The GdkDisplay that the drag belongs to.

Owner: GdkDrag

Flags: Read

### The `“formats”` property

      “formats”                  GdkContentFormats *

The possible formats that the drag can provide its data in.

Owner: GdkDrag

Flags: Read / Write / Construct Only

### The `“selected-action”` property

      “selected-action”          GdkDragAction

The currently selected action.

Owner: GdkDrag

Flags: Read / Write

### The `“surface”` property

      “surface”                  GdkSurface *

The surface where the drag originates.

Owner: GdkDrag

Flags: Read / Write / Construct Only

### The `“actions”` property

      “actions”                  GdkDragAction

The possible actions for this drop

Owner: GdkDrop

Flags: Read / Write / Construct Only

Default value: GDK_ACTION_COPY | GDK_ACTION_MOVE | GDK_ACTION_LINK

### The `“device”` property

      “device”                   GdkDevice *

The GdkDevice performing the drop

Owner: GdkDrop

Flags: Read / Write / Construct Only

### The `“display”` property

      “display”                  GdkDisplay *

The GdkDisplay that the drop belongs to.

Owner: GdkDrop

Flags: Read

### The `“drag”` property

      “drag”                     GdkDrag *

The GdkDrag that initiated this drop

Owner: GdkDrop

Flags: Read / Write / Construct Only

### The `“formats”` property

      “formats”                  GdkContentFormats *

The possible formats that the drop can provide its data in.

Owner: GdkDrop

Flags: Read / Write / Construct Only

### The `“surface”` property

      “surface”                  GdkSurface *

The GdkSurface the drop happens on

Owner: GdkDrop

Flags: Read / Write / Construct Only

## Signal Details

### The `“cancel”` signal

    void
    user_function (GdkDrag            *drag,
                   GdkDragCancelReason reason,
                   gpointer            user_data)

The drag operation was cancelled.

#### Parameters

drag | The object on which the signal is emitted |
reason | The reason the drag was cancelled |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“dnd-finished”` signal

    void
    user_function (GdkDrag *drag,
                   gpointer user_data)

The drag operation was finished, the destination finished reading all data. The drag object can now free all miscellaneous data.

#### Parameters

drag | The object on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“drop-performed”` signal

    void
    user_function (GdkDrag *drag,
                   gpointer user_data)

The drag operation was performed on an accepting client.

#### Parameters

drag | The object on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

Flags: Run Last