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.