GDK 3 Reference Manual: Drag And Drop

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

## Synopsis

    #include <gdk/gdk.h>

                        GdkDragContext;
    GdkAtom             gdk_drag_get_selection              (GdkDragContext *context);
    void                gdk_drag_abort                      (GdkDragContext *context,
                                                             guint32 time_);
    void                gdk_drop_reply                      (GdkDragContext *context,
                                                             gboolean accepted,
                                                             guint32 time_);
    void                gdk_drag_drop                       (GdkDragContext *context,
                                                             guint32 time_);
    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);
    GdkDragContext *    gdk_drag_begin                      (GdkWindow *window,
                                                             GList *targets);
    GdkDragContext *    gdk_drag_begin_for_device           (GdkWindow *window,
                                                             GdkDevice *device,
                                                             GList *targets);
    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_);
    void                gdk_drop_finish                     (GdkDragContext *context,
                                                             gboolean success,
                                                             guint32 time_);
    enum                GdkDragProtocol;
    enum                GdkDragAction;
    void                gdk_drag_status                     (GdkDragContext *context,
                                                             GdkDragAction action,
                                                             guint32 time_);
    gboolean            gdk_drag_drop_succeeded             (GdkDragContext *context);
    GdkDragProtocol     gdk_window_get_drag_protocol        (GdkWindow *window,
                                                             GdkWindow **target);
    GdkDragAction       gdk_drag_context_get_actions        (GdkDragContext *context);
    GdkDragAction       gdk_drag_context_get_suggested_action
                                                            (GdkDragContext *context);
    GdkDragAction       gdk_drag_context_get_selected_action
                                                            (GdkDragContext *context);
    GList *             gdk_drag_context_list_targets       (GdkDragContext *context);
    GdkDevice *         gdk_drag_context_get_device         (GdkDragContext *context);
    void                gdk_drag_context_set_device         (GdkDragContext *context,
                                                             GdkDevice *device);
    GdkWindow *         gdk_drag_context_get_source_window  (GdkDragContext *context);
    GdkWindow *         gdk_drag_context_get_dest_window    (GdkDragContext *context);
    GdkDragProtocol     gdk_drag_context_get_protocol       (GdkDragContext *context);

## Object Hierarchy

      GObject
       +----GdkDragContext

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

## Details

### GdkDragContext

    typedef struct _GdkDragContext GdkDragContext;

### gdk_drag_get_selection ()

    GdkAtom             gdk_drag_get_selection              (GdkDragContext *context);

Returns the selection atom for the current source window.

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

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

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

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

### 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()`.

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

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

`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_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.

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

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

### enum GdkDragProtocol

    typedef enum {
      GDK_DRAG_PROTO_NONE = 0,
      GDK_DRAG_PROTO_MOTIF,
      GDK_DRAG_PROTO_XDND,
      GDK_DRAG_PROTO_ROOTWIN,
      GDK_DRAG_PROTO_WIN32_DROPFILES,
      GDK_DRAG_PROTO_OLE2,
      GDK_DRAG_PROTO_LOCAL
    } GdkDragProtocol;

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

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

### enum GdkDragAction

    typedef enum {
      GDK_ACTION_DEFAULT = 1 << 0,
      GDK_ACTION_COPY    = 1 << 1,
      GDK_ACTION_MOVE    = 1 << 2,
      GDK_ACTION_LINK    = 1 << 3,
      GDK_ACTION_PRIVATE = 1 << 4,
      GDK_ACTION_ASK     = 1 << 5
    } GdkDragAction;

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

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

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

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

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

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

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

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

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

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

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

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

`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 windw for the DND operation.

`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 thats used by this context.

`context` : | a GdkDragContext
Returns : | the drag protocol

Since 3.0