Drag and Drop

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_find_window_for_screen     (GdkDragContext *context,
                                                         GdkWindow *drag_window,
                                                         GdkScreen *screen,
                                                         gint x_root,
                                                         gint y_root,
                                                         GdkWindow **dest_window,
                                                         GdkDragProtocol *protocol);
void                gdk_drag_context_ref                (GdkDragContext *context);
GdkDragAction       gdk_drag_context_get_actions        (GdkDragContext *context);
GdkDragAction       gdk_drag_context_get_selected_action
                                                        (GdkDragContext *context);
GdkDragAction       gdk_drag_context_get_suggested_action
                                                        (GdkDragContext *context);
GList *             gdk_drag_context_list_targets       (GdkDragContext *context);
GdkWindow *         gdk_drag_context_get_source_window  (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_);
GdkNativeWindow     gdk_drag_get_protocol               (GdkNativeWindow xid,
                                                         GdkDragProtocol *protocol);
GdkNativeWindow     gdk_drag_get_protocol_for_display   (GdkDisplay *display,
                                                         GdkNativeWindow 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_);
gboolean            gdk_drag_drop_succeeded             (GdkDragContext *context);

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

Warning

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.

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

Warning

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

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

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

Warning

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.

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.

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.

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.

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

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

GdkNativeWindow     gdk_drag_get_protocol               (GdkNativeWindow xid,
                                                         GdkDragProtocol *protocol);

Warning

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.

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.

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


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

context :

a GdkDragContext.

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.

GObject parent_instance;

the parent instance

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