GDK Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Drag and Drop

## Name

Drag and Drop -- functions for controlling drag and drop handling.

## Synopsis

    #include <gdk/gdk.h>

    GdkAtom     gdk_drag_get_selection          (GdkDragContext *context);
    void        gdk_drag_abort                  (GdkDragContext *context,
                                                 guint32 time);
    void        gdk_drop_reply                  (GdkDragContext *context,
                                                 gboolean ok,
                                                 guint32 time);
    GdkDragContext* gdk_drag_context_new        (void);
    void        gdk_drag_drop                   (GdkDragContext *context,
                                                 guint32 time);
    void        gdk_drag_find_window            (GdkDragContext *context,
                                                 GdkWindow *drag_window,
                                                 gint x_root,
                                                 gint y_root,
                                                 GdkWindow **dest_window,
                                                 GdkDragProtocol *protocol);
    void        gdk_drag_context_ref            (GdkDragContext *context);
    GdkDragContext* gdk_drag_begin              (GdkWindow *window,
                                                 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);
    guint32     gdk_drag_get_protocol           (guint32 xid,
                                                 GdkDragProtocol *protocol);
    guint32     gdk_drag_get_protocol_for_display
                                                (GdkDisplay *display,
                                                 guint32 xid,
                                                 GdkDragProtocol *protocol);
    enum        GdkDragProtocol;
    void        gdk_drag_context_unref          (GdkDragContext *context);
    struct      GdkDragContext;
    enum        GdkDragAction;
    void        gdk_drag_status                 (GdkDragContext *context,
                                                 GdkDragAction action,
                                                 guint32 time);

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

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

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

`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);

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.

`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);

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.
`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.
`protocol` : | location to store the DND protocol in.

### gdk_drag_context_ref ()

    void        gdk_drag_context_ref            (GdkDragContext *context);

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

Deprecated function; use g_object_ref() instead.

`context` : | a GdkDragContext.

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

`window` : | the source window for this drag.
`targets` : | the list of offered targets.
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);

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

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

### gdk_drag_get_protocol ()

    guint32     gdk_drag_get_protocol           (guint32 xid,
                                                 GdkDragProtocol *protocol);

Finds out the DND protocol supported by a window.

`xid` : | the X id of the destination window.
`protocol` : | location where the supported DND protocol is returned.
Returns : | the X id of the window where the drop should happen. This may be `xid` or the X id of a proxy window, or None if `xid` doesn't support Drag and Drop.

### gdk_drag_get_protocol_for_display ()

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

Finds out the DND protocol supported by a window.

`display` : | the GdkDisplay where the destination window resides
`xid` : | the X id of the destination window.
`protocol` : | location where the supported DND protocol is returned.
Returns : | the X id of the window where the drop should happen. This may be `xid` or the X id of a proxy window, or None if `xid` doesn't support Drag and Drop.

### enum GdkDragProtocol

    typedef enum
    {
      GDK_DRAG_PROTO_MOTIF,
      GDK_DRAG_PROTO_XDND,
      GDK_DRAG_PROTO_ROOTWIN,	  /* A root window with nobody claiming
    				   * drags */
      GDK_DRAG_PROTO_NONE,		  /* Not a valid drag window */
      GDK_DRAG_PROTO_WIN32_DROPFILES, /* The simple WM_DROPFILES dnd */
      GDK_DRAG_PROTO_OLE2,		  /* The complex OLE2 dnd (not implemented) */
      GDK_DRAG_PROTO_LOCAL            /* Intra-app */
    } GdkDragProtocol;

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

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

### gdk_drag_context_unref ()

    void        gdk_drag_context_unref          (GdkDragContext *context);

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

Deprecated function; use g_object_unref() instead.

`context` : | a GdkDragContext.

### struct GdkDragContext

    struct GdkDragContext {
      GObject parent_instance;

      /*< public >*/

      GdkDragProtocol protocol;

      gboolean is_source;

      GdkWindow *source_window;
      GdkWindow *dest_window;

      GList *targets;
      GdkDragAction actions;
      GdkDragAction suggested_action;
      GdkDragAction action;

      guint32 start_time;

      /*< private >*/

      gpointer windowing_data;
    };

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

GObject `parent_instance` |
GdkDragProtocol `protocol` | the DND protocol which governs this drag.
gboolean `is_source` | `TRUE` if the context is used on the source side.
GdkWindow *`source_window` | the source of this drag.
GdkWindow *`dest_window` | the destination window of this drag.
GList *`targets` | a list of targets offered by the source.
GdkDragAction `actions` | a bitmask of actions proposed by the source when `suggested_action` is `GDK_ACTION_ASK`.
GdkDragAction `suggested_action` | the action suggested by the source.
GdkDragAction `action` | the action chosen by the destination.
guint32 `start_time` | a timestamp recording the start time of this drag.

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

<<< Previous Page | Home | Up | Next Page >>>
Selections | Properties and Atoms