Drag And Drop

Drag And Drop — Functions for controlling drag and drop handling

Properties

GdkContentProvider * content Read / Write / Construct Only
GdkDevice * device Read / Write / Construct Only
GdkDisplay * display Read
GdkContentFormats * formats Read / Write / Construct Only

Signals

void action-changed Run Last
void cancel Run Last
void dnd-finished Run Last
void drop-performed Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── GdkDragContext

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

void
gdk_drag_drop_done (GdkDragContext *context,
                    gboolean success);

Inform GDK if the drop ended successfully. Passing FALSE for success may trigger a drag cancellation animation.

This function is called by the drag source, and should be the last call before dropping the reference to the context .

The GdkDragContext will only take the first gdk_drag_drop_done() call as effective, if this function is called multiple times, all subsequent calls will be ignored.

Parameters

context

a GdkDragContext

 

success

whether the drag was ultimatively successful

 

gdk_drag_begin ()

GdkDragContext *
gdk_drag_begin (GdkSurface *surface,
                GdkDevice *device,
                GdkContentProvider *content,
                GdkDragAction actions,
                gint dx,
                gint dy);

Starts a drag and creates a new drag context for it.

This function is called by the drag source.

Parameters

surface

the source surface for this drag

 

device

the device that controls this drag

 

content

the offered content.

[transfer none]

actions

the actions supported by this drag

 

dx

the x offset to device 's position where the drag nominally started

 

dy

the y offset to device 's position where the drag nominally started

 

Returns

a newly created GdkDragContext or NULL on error.

[transfer full][nullable]


gdk_drag_context_get_display ()

GdkDisplay *
gdk_drag_context_get_display (GdkDragContext *context);

Gets the GdkDisplay that the drag context was created for.

Parameters

context

a GdkDragContext

 

Returns

a GdkDisplay.

[transfer none]


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.

Parameters

context

a GdkDragContext

 

Returns

the GdkDragAction flags


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


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


gdk_drag_context_get_formats ()

GdkContentFormats *
gdk_drag_context_get_formats (GdkDragContext *context);

Retrieves the formats supported by this context.

Parameters

context

a GdkDragContext

 

Returns

a GdkContentFormats.

[transfer none]


gdk_drag_context_get_device ()

GdkDevice *
gdk_drag_context_get_device (GdkDragContext *context);

Returns the GdkDevice associated to the drag context.

Parameters

context

a GdkDragContext

 

Returns

The GdkDevice associated to context .

[transfer none]


gdk_drag_context_get_drag_surface ()

GdkSurface *
gdk_drag_context_get_drag_surface (GdkDragContext *context);

Returns the surface on which the drag icon should be rendered during the drag operation. Note that the surface may not be available until the drag operation has begun. GDK will move the surface in accordance with the ongoing drag operation. The surface is owned by context and will be destroyed when the drag operation is over.

Parameters

context

a GdkDragContext

 

Returns

the drag surface, or NULL.

[nullable][transfer none]


gdk_drag_context_set_hotspot ()

void
gdk_drag_context_set_hotspot (GdkDragContext *context,
                              gint hot_x,
                              gint hot_y);

Sets the position of the drag surface that will be kept under the cursor hotspot. Initially, the hotspot is at the top left corner of the drag surface.

Parameters

context

a GdkDragContext

 

hot_x

x coordinate of the drag surface hotspot

 

hot_y

y coordinate of the drag surface hotspot

 

gdk_drag_action_is_unique ()

gboolean
gdk_drag_action_is_unique (GdkDragAction action);

Checks if action represents a single action or if it includes multiple flags that can be selected from.

When action is 0 - ie no action was given, TRUE is returned.

Parameters

action

a GdkDragAction

 

Returns

TRUE if exactly one action was given

Types and Values

GdkDragContext

typedef struct _GdkDragContext GdkDragContext;

The GdkDragContext struct contains only private fields and should not be accessed directly.


enum GdkDragCancelReason

Used in GdkDragContext to the reason of a cancelled DND operation.

Members

GDK_DRAG_CANCEL_NO_TARGET

There is no suitable drop target.

 

GDK_DRAG_CANCEL_USER_CANCELLED

Drag cancelled by the user

 

GDK_DRAG_CANCEL_ERROR

Unspecified error.

 

enum GdkDragAction

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

Members

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_ASK

Ask the user what to do with the data.

 

GDK_ACTION_ALL

#define GDK_ACTION_ALL (GDK_ACTION_COPY | GDK_ACTION_MOVE | GDK_ACTION_LINK)

Defines all possible DND actions. This can be used in gdk_drop_status() messages when any drop can be accepted or a more specific drop method is not yet known.

Property Details

The “content” property

  “content”                  GdkContentProvider *

The GdkContentProvider or NULL if the context is not a source-side context.

Flags: Read / Write / Construct Only


The “device” property

  “device”                   GdkDevice *

The GdkDevice that is performing the drag.

Flags: Read / Write / Construct Only


The “display” property

  “display”                  GdkDisplay *

The GdkDisplay that the drag context belongs to.

Flags: Read


The “formats” property

  “formats”                  GdkContentFormats *

The possible formats that the context can provide its data in.

Flags: Read / Write / Construct Only

Signal Details

The “action-changed” signal

void
user_function (GdkDragContext *context,
               GdkDragAction   action,
               gpointer        user_data)

A new action is being chosen for the drag and drop operation.

Parameters

context

The object on which the signal is emitted

 

action

The action currently chosen

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “cancel” signal

void
user_function (GdkDragContext     *context,
               GdkDragCancelReason reason,
               gpointer            user_data)

The drag and drop operation was cancelled.

Parameters

context

The object on which the signal is emitted

 

reason

The reason the context was cancelled

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “dnd-finished” signal

void
user_function (GdkDragContext *context,
               gpointer        user_data)

The drag and drop operation was finished, the drag destination finished reading all data. The drag source can now free all miscellaneous data.

Parameters

context

The object on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “drop-performed” signal

void
user_function (GdkDragContext *context,
               gpointer        user_data)

The drag and drop operation was performed on an accepting client.

Parameters

context

The object on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last