Drag and Drop: GDK 2 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 ()
GdkDragContext * | gdk_drag_context_new ()
void | gdk_drag_drop ()
void | gdk_drag_find_window ()
void | gdk_drag_find_window_for_screen ()
void | gdk_drag_context_ref ()
GdkDragAction | gdk_drag_context_get_actions ()
GdkDragAction | gdk_drag_context_get_selected_action ()
GdkDragAction | gdk_drag_context_get_suggested_action ()
GList * | gdk_drag_context_list_targets ()
GdkWindow * | gdk_drag_context_get_source_window ()
GdkDragContext * | gdk_drag_begin ()
gboolean | gdk_drag_motion ()
void | gdk_drop_finish ()
GdkNativeWindow | gdk_drag_get_protocol ()
GdkNativeWindow | gdk_drag_get_protocol_for_display ()
void | gdk_drag_context_unref ()
void | gdk_drag_status ()
gboolean | gdk_drag_drop_succeeded ()

## Types and Values

enum | GdkDragProtocol
struct | GdkDragContext
enum | GdkDragAction

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

### gdk_drag_abort ()

    void
    gdk_drag_abort (GdkDragContext *context,
                    guint32 time_);

Aborts a drag without dropping.

This function is called by the drag source.

#### Parameters

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

### gdk_drop_reply ()

    void
    gdk_drop_reply (GdkDragContext *context,
                    gboolean ok,
                    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. |
ok | `TRUE` if the drop is accepted. |
time_ | the timestamp for this operation. |

### gdk_drag_context_new ()

    GdkDragContext *
    gdk_drag_context_new (void);

`gdk_drag_context_new` has been deprecated since version 2.24 and should not be used in newly-written code.

This function is not useful, you always obtain drag contexts by `gdk_drag_begin()` or similar.

Creates a new GdkDragContext.

#### Returns

the newly created GdkDragContext.

### gdk_drag_drop ()

    void
    gdk_drag_drop (GdkDragContext *context,
                   guint32 time_);

Drops on the current destination.

This function is called by the drag source.

#### Parameters

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

### gdk_drag_find_window ()

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

`gdk_drag_find_window` has been deprecated since version 2.24 and should not be used in newly-written code.

Use `gdk_drag_find_window_for_screen()` instead.

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

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

    void
    gdk_drag_context_ref (GdkDragContext *context);

`gdk_drag_context_ref` has been deprecated since version 2.2 and should not be used in newly-written code.

Use `g_object_ref()` instead.

Deprecated function; use `g_object_ref()` instead.

#### Parameters

context | a GdkDragContext. |

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

#### Parameters

context | a GdkDragContext |

#### Returns

the GdkDragAction flags

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_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_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_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_begin ()

    GdkDragContext *
    gdk_drag_begin (GdkWindow *window,
                    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. |
targets | the offered targets, as list of GdkAtoms. | [transfer none][element-type GdkAtom]

#### Returns

a newly created GdkDragContext.

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

`gdk_drag_motion` is deprecated and should not be used in newly-written code.

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

This function is called by the drag source.

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

#### Returns

FIXME

### 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 GtkDragContext. |
success | `TRUE` if the data was successfully received. |
time_ | the timestamp for this operation. |

### gdk_drag_get_protocol ()

    GdkNativeWindow
    gdk_drag_get_protocol (GdkNativeWindow xid,
                           GdkDragProtocol *protocol);

`gdk_drag_get_protocol` has been deprecated since version 2.24 and should not be used in newly-written code.

Use `gdk_drag_get_protocol_for_display()` instead

Finds out the DND protocol supported by a window.

#### Parameters

xid | the windowing system id of the destination window. |
protocol | location where the supported DND protocol is returned. |

#### Returns

the windowing system specific id for the window where the drop should happen. This may be `xid` or the id of a proxy window, or zero if `xid` doesn't support Drag and Drop.

### gdk_drag_get_protocol_for_display ()

    GdkNativeWindow
    gdk_drag_get_protocol_for_display (GdkDisplay *display,
                                       GdkNativeWindow xid,
                                       GdkDragProtocol *protocol);

Finds out the DND protocol supported by a window.

#### Parameters

display | the GdkDisplay where the destination window resides |
xid | the windowing system id of the destination window. |
protocol | location where the supported DND protocol is returned. |

#### Returns

the windowing system id of the window where the drop should happen. This may be `xid` or the id of a proxy window, or zero if `xid` doesn't support Drag and Drop.

Since: 2.2

### gdk_drag_context_unref ()

    void
    gdk_drag_context_unref (GdkDragContext *context);

`gdk_drag_context_unref` has been deprecated since version 2.2 and should not be used in newly-written code.

Use `g_object_unref()` instead.

Deprecated function; use `g_object_unref()` instead.

#### Parameters

context | a GdkDragContext. |

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

## Types and Values

### enum GdkDragProtocol

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

#### Members

GDK_DRAG_PROTO_MOTIF | The Motif DND protocol. |
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_NONE | no protocol. |
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. |

### struct GdkDragContext

    struct GdkDragContext {
      GObject parent_instance;

      GdkDragProtocol GSEAL (protocol);

      gboolean GSEAL (is_source);

      GdkWindow *GSEAL (source_window);
      GdkWindow *GSEAL (dest_window);

      GList *GSEAL (targets);
      GdkDragAction GSEAL (actions);
      GdkDragAction GSEAL (suggested_action);
      GdkDragAction GSEAL (action);

      guint32 GSEAL (start_time);
    };

A GdkDragContext holds information about a drag in progress. It is used on both source and destination sides.

#### Members

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