Drag And Drop: GDK 3 Reference Manual

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

## Functions

GdkAtom | gdk_drag_get_selection ()
void | gdk_drag_abort ()
void | gdk_drop_reply ()
void | gdk_drag_drop ()
void | gdk_drag_drop_done ()
void | gdk_drag_find_window_for_screen ()
GdkDragContext * | gdk_drag_begin ()
GdkDragContext * | gdk_drag_begin_for_device ()
GdkDragContext * | gdk_drag_begin_from_point ()
gboolean | gdk_drag_motion ()
void | gdk_drop_finish ()
void | gdk_drag_status ()
gboolean | gdk_drag_drop_succeeded ()
GdkDragProtocol | gdk_window_get_drag_protocol ()
GdkDragAction | gdk_drag_context_get_actions ()
GdkDragAction | gdk_drag_context_get_suggested_action ()
GdkDragAction | gdk_drag_context_get_selected_action ()
GList * | gdk_drag_context_list_targets ()
GdkDevice * | gdk_drag_context_get_device ()
void | gdk_drag_context_set_device ()
GdkWindow * | gdk_drag_context_get_source_window ()
GdkWindow * | gdk_drag_context_get_dest_window ()
GdkDragProtocol | gdk_drag_context_get_protocol ()
GdkWindow * | gdk_drag_context_get_drag_window ()
void | gdk_drag_context_set_hotspot ()
gboolean | gdk_drag_context_manage_dnd ()

## Signals

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

## Types and Values

| GdkDragContext
enum | GdkDragCancelReason
enum | GdkDragProtocol
enum | GdkDragAction

## Object Hierarchy

        GObject
        ╰── GdkDragContext

## Includes

    #include <gdk/gdk.h>

## Description

These functions provide a low level interface for drag and drop. The X backend of GDK supports both the Xdnd and Motif drag and drop protocols transparently, the Win32 backend supports the WM_DROPFILES protocol.

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

    GdkAtom
    gdk_drag_get_selection (GdkDragContext *context);

Returns the selection atom for the current source window.

#### Parameters

context | a GdkDragContext. |

#### Returns

the selection atom, or `GDK_NONE`.

[transfer none]

### gdk_drag_abort ()

    void
    gdk_drag_abort (GdkDragContext *context,
                    guint32 time_);

Aborts a drag without dropping.

This function is called by the drag source.

This function does not need to be called in managed drag and drop operations. See `gdk_drag_context_manage_dnd()` for more information.

#### Parameters

context | a GdkDragContext |
time_ | the timestamp for this operation |

### gdk_drop_reply ()

    void
    gdk_drop_reply (GdkDragContext *context,
                    gboolean accepted,
                    guint32 time_);

Accepts or rejects a drop.

This function is called by the drag destination in response to a drop initiated by the drag source.

#### Parameters

context | a GdkDragContext |
accepted | `TRUE` if the drop is accepted |
time_ | the timestamp for this operation |

### gdk_drag_drop ()

    void
    gdk_drag_drop (GdkDragContext *context,
                   guint32 time_);

Drops on the current destination.

This function is called by the drag source.

This function does not need to be called in managed drag and drop operations. See `gdk_drag_context_manage_dnd()` for more information.

#### Parameters

context | a GdkDragContext |
time_ | the timestamp for this operation |

### gdk_drag_drop_done ()

    void
    gdk_drag_drop_done (GdkDragContext *context,
                        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 `context` .

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

context | a GdkDragContext |
success | whether the drag was ultimatively successful |

Since: 3.20

### gdk_drag_find_window_for_screen ()

    void
    gdk_drag_find_window_for_screen (GdkDragContext *context,
                                     GdkWindow *drag_window,
                                     GdkScreen *screen,
                                     gint x_root,
                                     gint y_root,
                                     GdkWindow **dest_window,
                                     GdkDragProtocol *protocol);

Finds the destination window and DND protocol to use at the given pointer position.

This function is called by the drag source to obtain the `dest_window` and `protocol` parameters for `gdk_drag_motion()`.

#### Parameters

context | a GdkDragContext |
drag_window | a window which may be at the pointer position, but should be ignored, since it is put up by the drag source as an icon |
screen | the screen where the destination window is sought |
x_root | the x position of the pointer in root coordinates |
y_root | the y position of the pointer in root coordinates |
dest_window | location to store the destination window in. | [out]
protocol | location to store the DND protocol in. | [out]

Since: 2.2

### gdk_drag_begin ()

    GdkDragContext *
    gdk_drag_begin (GdkWindow *window,
                    GList *targets);

Starts a drag and creates a new drag context for it. This function assumes that the drag is controlled by the client pointer device, use `gdk_drag_begin_for_device()` to begin a drag with a different device.

This function is called by the drag source.

#### Parameters

window | the source window for this drag. |
targets | the offered targets, as list of GdkAtoms. | [transfer none][element-type GdkAtom]

#### Returns

a newly created GdkDragContext.

[transfer full]

### gdk_drag_begin_for_device ()

    GdkDragContext *
    gdk_drag_begin_for_device (GdkWindow *window,
                               GdkDevice *device,
                               GList *targets);

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

This function is called by the drag source.

#### Parameters

window | the source window for this drag |
device | the device that controls this drag |
targets | the offered targets, as list of GdkAtoms. | [transfer none][element-type GdkAtom]

#### Returns

a newly created GdkDragContext.

[transfer full]

### gdk_drag_begin_from_point ()

    GdkDragContext *
    gdk_drag_begin_from_point (GdkWindow *window,
                               GdkDevice *device,
                               GList *targets,
                               gint x_root,
                               gint y_root);

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

This function is called by the drag source.

#### Parameters

window | the source window for this drag |
device | the device that controls this drag |
targets | the offered targets, as list of GdkAtoms. | [transfer none][element-type GdkAtom]
x_root | the x coordinate where the drag nominally started |
y_root | the y coordinate where the drag nominally started |

#### Returns

a newly created GdkDragContext.

[transfer full]

Since: 3.20

### gdk_drag_motion ()

    gboolean
    gdk_drag_motion (GdkDragContext *context,
                     GdkWindow *dest_window,
                     GdkDragProtocol protocol,
                     gint x_root,
                     gint y_root,
                     GdkDragAction suggested_action,
                     GdkDragAction possible_actions,
                     guint32 time_);

Updates the drag context when the pointer moves or the set of actions changes.

This function is called by the drag source.

This function does not need to be called in managed drag and drop operations. See `gdk_drag_context_manage_dnd()` for more information.

#### Parameters

context | a GdkDragContext |
dest_window | the new destination window, obtained by `gdk_drag_find_window()` |
protocol | the DND protocol in use, obtained by `gdk_drag_find_window()` |
x_root | the x position of the pointer in root coordinates |
y_root | the y position of the pointer in root coordinates |
suggested_action | the suggested action |
possible_actions | the possible actions |
time_ | the timestamp for this operation |

### gdk_drop_finish ()

    void
    gdk_drop_finish (GdkDragContext *context,
                     gboolean success,
                     guint32 time_);

Ends the drag operation after a drop.

This function is called by the drag destination.

#### Parameters

context | a GdkDragContext |
success | `TRUE` if the data was successfully received |
time_ | the timestamp for this operation |

### gdk_drag_status ()

    void
    gdk_drag_status (GdkDragContext *context,
                     GdkDragAction action,
                     guint32 time_);

Selects one of the actions offered by the drag source.

This function is called by the drag destination in response to `gdk_drag_motion()` called by the drag source.

#### Parameters

context | a GdkDragContext |
action | the selected action which will be taken when a drop happens, or 0 to indicate that a drop will not be accepted |
time_ | the timestamp for this operation |

### gdk_drag_drop_succeeded ()

    gboolean
    gdk_drag_drop_succeeded (GdkDragContext *context);

Returns whether the dropped data has been successfully transferred. This function is intended to be used while handling a `GDK_DROP_FINISHED` event, its return value is meaningless at other times.

#### Parameters

context | a GdkDragContext |

#### Returns

`TRUE` if the drop was successful.

Since: 2.6

### gdk_window_get_drag_protocol ()

    GdkDragProtocol
    gdk_window_get_drag_protocol (GdkWindow *window,
                                  GdkWindow **target);

Finds out the DND protocol supported by a window.

#### Parameters

window | the destination window |
target | location of the window where the drop should happen. This may be `window` or a proxy window, or `NULL` if `window` does not support Drag and Drop. | [out][allow-none][transfer full]

#### Returns

the supported DND protocol.

Since: 3.0

### gdk_drag_context_get_actions ()

    GdkDragAction
    gdk_drag_context_get_actions (GdkDragContext *context);

Determines the bitmask of actions proposed by the source if `gdk_drag_context_get_suggested_action()` returns `GDK_ACTION_ASK`.

#### Parameters

context | a GdkDragContext |

#### Returns

the GdkDragAction flags

Since: 2.22

### gdk_drag_context_get_suggested_action ()

    GdkDragAction
    gdk_drag_context_get_suggested_action (GdkDragContext *context);

Determines the suggested drag action of the context.

#### Parameters

context | a GdkDragContext |

#### Returns

a GdkDragAction value

Since: 2.22

### gdk_drag_context_get_selected_action ()

    GdkDragAction
    gdk_drag_context_get_selected_action (GdkDragContext *context);

Determines the action chosen by the drag destination.

#### Parameters

context | a GdkDragContext |

#### Returns

a GdkDragAction value

Since: 2.22

### gdk_drag_context_list_targets ()

    GList *
    gdk_drag_context_list_targets (GdkDragContext *context);

Retrieves the list of targets of the context.

#### Parameters

context | a GdkDragContext |

#### Returns

a GList of targets.

[transfer none][element-type GdkAtom]

Since: 2.22

### gdk_drag_context_get_device ()

    GdkDevice *
    gdk_drag_context_get_device (GdkDragContext *context);

Returns the GdkDevice associated to the drag context.

#### Parameters

context | a GdkDragContext |

#### Returns

The GdkDevice associated to `context` .

[transfer none]

### gdk_drag_context_set_device ()

    void
    gdk_drag_context_set_device (GdkDragContext *context,
                                 GdkDevice *device);

Associates a GdkDevice to `context` , so all Drag and Drop events for `context` are emitted as if they came from this device.

#### Parameters

context | a GdkDragContext |
device | a GdkDevice |

### gdk_drag_context_get_source_window ()

    GdkWindow *
    gdk_drag_context_get_source_window (GdkDragContext *context);

Returns the GdkWindow where the DND operation started.

#### Parameters

context | a GdkDragContext |

#### Returns

a GdkWindow.

[transfer none]

Since: 2.22

### gdk_drag_context_get_dest_window ()

    GdkWindow *
    gdk_drag_context_get_dest_window (GdkDragContext *context);

Returns the destination window for the DND operation.

#### Parameters

context | a GdkDragContext |

#### Returns

a GdkWindow.

[transfer none]

Since: 3.0

### gdk_drag_context_get_protocol ()

    GdkDragProtocol
    gdk_drag_context_get_protocol (GdkDragContext *context);

Returns the drag protocol that is used by this context.

#### Parameters

context | a GdkDragContext |

#### Returns

the drag protocol

Since: 3.0

### gdk_drag_context_get_drag_window ()

    GdkWindow *
    gdk_drag_context_get_drag_window (GdkDragContext *context);

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

#### Parameters

context | a GdkDragContext |

#### Returns

the drag window, or `NULL`.

[nullable][transfer none]

Since: 3.20

### gdk_drag_context_set_hotspot ()

    void
    gdk_drag_context_set_hotspot (GdkDragContext *context,
                                  gint hot_x,
                                  gint hot_y);

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

#### Parameters

context | a GdkDragContext |
hot_x | x coordinate of the drag window hotspot |
hot_y | y coordinate of the drag window hotspot |

Since: 3.20

### gdk_drag_context_manage_dnd ()

    gboolean
    gdk_drag_context_manage_dnd (GdkDragContext *context,
                                 GdkWindow *ipc_window,
                                 GdkDragAction actions);

Requests the drag and drop operation to be managed by `context` . When a drag and drop operation becomes managed, the GdkDragContext will internally handle all input and source-side GdkEventDND events as required by the windowing system.

Once the drag and drop operation is managed, the drag context will emit the following signals:

- The “action-changed” signal whenever the final action to be performed by the drag and drop operation changes.

- The “drop-performed” signal after the user performs the drag and drop gesture (typically by releasing the mouse button).

- The “dnd-finished” signal after the drag and drop operation concludes (after all GdkSelection transfers happen).

- The “cancel” signal if the drag and drop operation is finished but doesn't happen over an accepting destination, or is cancelled through other means.

#### Parameters

context | a GdkDragContext |
ipc_window | Window to use for IPC messaging/events |
actions | the actions supported by the drag source |

#### Returns

TRUE if the drag and drop operation is managed.

Since: 3.20

## Types and Values

### GdkDragContext

    typedef struct _GdkDragContext GdkDragContext;

### enum GdkDragCancelReason

Used in GdkDragContext 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. |

Since: 3.20

### enum GdkDragProtocol

Used in GdkDragContext to indicate the protocol according to which DND is done.

#### Members

GDK_DRAG_PROTO_NONE | no protocol. |
GDK_DRAG_PROTO_MOTIF | The Motif DND protocol. No longer supported |
GDK_DRAG_PROTO_XDND | The Xdnd protocol. |
GDK_DRAG_PROTO_ROOTWIN | An extension to the Xdnd protocol for unclaimed root window drops. |
GDK_DRAG_PROTO_WIN32_DROPFILES | The simple WM_DROPFILES protocol. |
GDK_DRAG_PROTO_OLE2 | The complex OLE2 DND protocol (not implemented). |
GDK_DRAG_PROTO_LOCAL | Intra-application DND. |
GDK_DRAG_PROTO_WAYLAND | Wayland DND protocol. |

### enum GdkDragAction

Used in GdkDragContext to indicate what the destination should do with the dropped data.

#### Members

GDK_ACTION_DEFAULT | Means nothing, and should not be used. |
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. |
GDK_ACTION_PRIVATE | Special action which tells the source that the destination will do something that the source doesn’t understand. |
GDK_ACTION_ASK | Ask the user what to do with the data. |

## Signal Details

### The `“action-changed”` signal

    void
    user_function (GdkDragContext *context,
                   GdkDragAction   action,
                   gpointer        user_data)

A new action is being chosen for the drag and drop operation.

This signal will only be emitted if the GdkDragContext manages the drag and drop operation. See `gdk_drag_context_manage_dnd()` for more information.

#### Parameters

context | The object on which the signal is emitted |
action | The action currently chosen |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.20

### The `“cancel”` signal

    void
    user_function (GdkDragContext     *context,
                   GdkDragCancelReason reason,
                   gpointer            user_data)

The drag and drop operation was cancelled.

This signal will only be emitted if the GdkDragContext manages the drag and drop operation. See `gdk_drag_context_manage_dnd()` for more information.

#### Parameters

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

Flags: Run Last

Since: 3.20

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

    void
    user_function (GdkDragContext *context,
                   gpointer        user_data)

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

This signal will only be emitted if the GdkDragContext manages the drag and drop operation. See `gdk_drag_context_manage_dnd()` for more information.

#### Parameters

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

Flags: Run Last

Since: 3.20

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

    void
    user_function (GdkDragContext *context,
                   int             time,
                   gpointer        user_data)

The drag and drop operation was performed on an accepting client.

This signal will only be emitted if the GdkDragContext manages the drag and drop operation. See `gdk_drag_context_manage_dnd()` for more information.

#### Parameters

context | The object on which the signal is emitted |
time | the time at which the drop happened. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.20