Drag And Drop

Drag And Drop — Functions for controlling drag and drop handling

Functions

Properties

GdkDragAction actions Read / Write
GdkContentProvider * content Read / Write / Construct Only
GdkDevice * device Read / Write / Construct Only
GdkDisplay * display Read
GdkContentFormats * formats Read / Write / Construct Only
GdkDragAction selected-action Read / Write
GdkSurface * surface Read / Write / Construct Only
GdkDragAction actions Read / Write / Construct Only
GdkDevice * device Read / Write / Construct Only
GdkDisplay * display Read
GdkDrag * drag Read / Write / Construct Only
GdkContentFormats * formats Read / Write / Construct Only
GdkSurface * surface Read / Write / Construct Only

Signals

Types and Values

Object Hierarchy

    GObject
    ├── GdkDrag
    ╰── GdkDrop

Includes

#include <gdk/gdk.h>

Description

These functions provide a low level interface for drag and drop.

The GdkDrag object represents the source side of an ongoing DND operation. It is created when a drag is started, and stays alive for duration of the DND operation.

The GdkDrop object represents the target side of an ongoing DND operation.

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 (GdkDrag *drag,
                    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 drag .

The GdkDrag 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

drag

a GdkDrag

 

success

whether the drag was ultimatively successful

 

gdk_drag_begin ()

GdkDrag *
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 GdkDrag or NULL on error.

[transfer full][nullable]

gdk_drag_get_display ()

GdkDisplay *
gdk_drag_get_display (GdkDrag *drag);

Gets the GdkDisplay that the drag object was created for.

Parameters

drag

a GdkDrag

 

Returns

a GdkDisplay.

[transfer none]

gdk_drag_get_actions ()

GdkDragAction
gdk_drag_get_actions (GdkDrag *drag);

Determines the bitmask of possible actions proposed by the source.

Parameters

drag

a GdkDrag

 

Returns

the GdkDragAction flags

gdk_drag_get_selected_action ()

GdkDragAction
gdk_drag_get_selected_action (GdkDrag *drag);

Determines the action chosen by the drag destination.

Parameters

drag

a GdkDrag

 

Returns

a GdkDragAction value

gdk_drag_get_formats ()

GdkContentFormats *
gdk_drag_get_formats (GdkDrag *drag);

Retrieves the formats supported by this GdkDrag object.

Parameters

drag

a GdkDrag

 

Returns

a GdkContentFormats.

[transfer none]

gdk_drag_get_device ()

GdkDevice *
gdk_drag_get_device (GdkDrag *drag);

Returns the GdkDevice associated to the GdkDrag object.

Parameters

drag

a GdkDrag

 

Returns

The GdkDevice associated to drag .

[transfer none]

gdk_drag_get_drag_surface ()

GdkSurface *
gdk_drag_get_drag_surface (GdkDrag *drag);

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 drag and will be destroyed when the drag operation is over.

Parameters

drag

a GdkDrag

 

Returns

the drag surface, or NULL.

[nullable][transfer none]

gdk_drag_set_hotspot ()

void
gdk_drag_set_hotspot (GdkDrag *drag,
                      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

drag

a GdkDrag

 

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

gdk_drop_get_display ()

GdkDisplay *
gdk_drop_get_display (GdkDrop *self);

Gets the GdkDisplay that self was created for.

Parameters

self

a GdkDrop

 

Returns

a GdkDisplay.

[transfer none]

gdk_drop_get_device ()

GdkDevice *
gdk_drop_get_device (GdkDrop *self);

Returns the GdkDevice performing the drop.

Parameters

self

a GdkDrop

 

Returns

The GdkDevice performing the drop.

[transfer none]

gdk_drop_get_surface ()

GdkSurface *
gdk_drop_get_surface (GdkDrop *self);

Returns the GdkSurface performing the drop.

Parameters

self

a GdkDrop

 

Returns

The GdkSurface performing the drop.

[transfer none]

gdk_drop_get_formats ()

GdkContentFormats *
gdk_drop_get_formats (GdkDrop *self);

Returns the GdkContentFormats that the drop offers the data to be read in.

Parameters

self

a GdkDrop

 

Returns

The possible GdkContentFormats.

[transfer none]

gdk_drop_get_actions ()

GdkDragAction
gdk_drop_get_actions (GdkDrop *self);

Returns the possible actions for this GdkDrop. If this value contains multiple actions - ie gdk_drag_action_is_unique() returns FALSE for the result - gdk_drag_finish() must choose the action to use when accepting the drop.

This value may change over the lifetime of the GdkDrop both as a response to source side actions as well as to calls to gdk_drop_status() or gdk_drag_finish(). The source side will not change this value anymore once a drop has started.

Parameters

self

a GdkDrop

 

Returns

The possible GdkDragActions

gdk_drop_get_drag ()

GdkDrag *
gdk_drop_get_drag (GdkDrop *self);

If this is an in-app drag-and-drop operation, returns the GdkDrag that corresponds to this drop.

If it is not, NULL is returned.

Parameters

self

a GdkDrop

 

Returns

the corresponding GdkDrag.

[transfer none][nullable]

gdk_drop_status ()

void
gdk_drop_status (GdkDrop *self,
                 GdkDragAction actions);

Selects all actions that are potentially supported by the destination.

When calling this function, do not restrict the passed in actions to the ones provided by gdk_drop_get_actions(). Those actions may change in the future, even depending on the actions you provide here.

This function should be called by drag destinations in response to GDK_DRAG_ENTER or GDK_DRAG_MOTION events. If the destination does not yet know the exact actions it supports, it should set any possible actions first and then later call this function again.

Parameters

self

a GdkDrop

 

actions

Supported actions of the destination, or 0 to indicate that a drop will not be accepted

 

gdk_drop_finish ()

void
gdk_drop_finish (GdkDrop *self,
                 GdkDragAction action);

Ends the drag operation after a drop.

The action must be a single action selected from the actions available via gdk_drop_get_actions().

Parameters

self

a GdkDrop

 

action

the action performed by the destination or 0 if the drop failed

 

gdk_drop_read_async ()

void
gdk_drop_read_async (GdkDrop *self,
                     const char **mime_types,
                     int io_priority,
                     GCancellable *cancellable,
                     GAsyncReadyCallback callback,
                     gpointer user_data);

Asynchronously read the dropped data from a GdkDrop in a format that complies with one of the mime types.

Parameters

self

a GdkDrop

 

mime_types

pointer to an array of mime types.

[array zero-terminated=1][element-type utf8]

io_priority

the io priority for the read operation

 

cancellable

optional GCancellable object, NULL to ignore.

[allow-none]

callback

a GAsyncReadyCallback to call when the request is satisfied.

[scope async]

user_data

the data to pass to callback .

[closure]

gdk_drop_read_finish ()

GInputStream *
gdk_drop_read_finish (GdkDrop *self,
                      GAsyncResult *result,
                      const char **out_mime_type,
                      GError **error);

Finishes an async drop read operation, see gdk_drop_read_async().

Parameters

self

a GdkDrop

 

result

a GAsyncResult

 

out_mime_type

return location for the used mime type.

[out][type utf8]

error

location to store error information on failure, or NULL.

[allow-none]

Returns

the GInputStream, or NULL.

[nullable][transfer full]

gdk_drop_read_value_async ()

void
gdk_drop_read_value_async (GdkDrop *self,
                           GType type,
                           int io_priority,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Asynchronously request the drag operation's contents converted to the given type . When the operation is finished callback will be called. You can then call gdk_drop_read_value_finish() to get the resulting GValue.

For local drag'n'drop operations that are available in the given GType, the value will be copied directly. Otherwise, GDK will try to use gdk_content_deserialize_async() to convert the data.

Parameters

self

a GdkDrop

 

type

a GType to read

 

io_priority

the I/O priority of the request.

 

cancellable

optional GCancellable object, NULL to ignore.

[nullable]

callback

callback to call when the request is satisfied.

[scope async]

user_data

the data to pass to callback function.

[closure]

gdk_drop_read_value_finish ()

const GValue *
gdk_drop_read_value_finish (GdkDrop *self,
                            GAsyncResult *result,
                            GError **error);

Finishes an async drop read started with gdk_drop_read_value_async().

Parameters

self

a GdkDrop

 

result

a GAsyncResult

 

error

a GError location to store the error occurring, or NULL to ignore.

 

Returns

a GValue containing the result.

[transfer none]

gdk_drop_read_text_async ()

void
gdk_drop_read_text_async (GdkDrop *self,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Asynchronously request the drag operation's contents converted to a string. When the operation is finished callback will be called. You can then call gdk_drop_read_text_finish() to get the result.

This is a simple wrapper around gdk_drop_read_value_async(). Use that function or gdk_drop_read_async() directly if you need more control over the operation.

Parameters

self

a GdkDrop

 

cancellable

optional GCancellable object, NULL to ignore.

[nullable]

callback

callback to call when the request is satisfied.

[scope async]

user_data

the data to pass to callback function.

[closure]

gdk_drop_read_text_finish ()

char *
gdk_drop_read_text_finish (GdkDrop *self,
                           GAsyncResult *result,
                           GError **error);

Finishes an asynchronous read started with gdk_drop_read_text_async().

Parameters

self

a GdkDrop

 

result

a GAsyncResult

 

error

a GError location to store the error occurring, or NULL to ignore.

 

Returns

a new string or NULL on error.

[transfer full][nullable]

Types and Values

GdkDrag

typedef struct _GdkDrag GdkDrag;

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

GdkDrop

typedef struct _GdkDrop GdkDrop;

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

enum GdkDragCancelReason

Used in GdkDrag 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 GdkDrag 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 “actions” property

  “actions”                  GdkDragAction

The possible actions.

Owner: GdkDrag

Flags: Read / Write

The “content” property

  “content”                  GdkContentProvider *

The GdkContentProvider.

Owner: GdkDrag

Flags: Read / Write / Construct Only

The “device” property

  “device”                   GdkDevice *

The GdkDevice that is performing the drag.

Owner: GdkDrag

Flags: Read / Write / Construct Only

The “display” property

  “display”                  GdkDisplay *

The GdkDisplay that the drag belongs to.

Owner: GdkDrag

Flags: Read

The “formats” property

  “formats”                  GdkContentFormats *

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

Owner: GdkDrag

Flags: Read / Write / Construct Only

The “selected-action” property

  “selected-action”          GdkDragAction

The currently selected action.

Owner: GdkDrag

Flags: Read / Write

The “surface” property

  “surface”                  GdkSurface *

The surface where the drag originates.

Owner: GdkDrag

Flags: Read / Write / Construct Only

The “actions” property

  “actions”                  GdkDragAction

The possible actions for this drop

Owner: GdkDrop

Flags: Read / Write / Construct Only

Default value: GDK_ACTION_COPY | GDK_ACTION_MOVE | GDK_ACTION_LINK

The “device” property

  “device”                   GdkDevice *

The GdkDevice performing the drop

Owner: GdkDrop

Flags: Read / Write / Construct Only

The “display” property

  “display”                  GdkDisplay *

The GdkDisplay that the drop belongs to.

Owner: GdkDrop

Flags: Read

The “drag” property

  “drag”                     GdkDrag *

The GdkDrag that initiated this drop

Owner: GdkDrop

Flags: Read / Write / Construct Only

The “formats” property

  “formats”                  GdkContentFormats *

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

Owner: GdkDrop

Flags: Read / Write / Construct Only

The “surface” property

  “surface”                  GdkSurface *

The GdkSurface the drop happens on

Owner: GdkDrop

Flags: Read / Write / Construct Only

Signal Details

The “cancel” signal

void
user_function (GdkDrag            *drag,
               GdkDragCancelReason reason,
               gpointer            user_data)

The drag operation was cancelled.

Parameters

drag

The object on which the signal is emitted

 

reason

The reason the drag was cancelled

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

The “dnd-finished” signal

void
user_function (GdkDrag *drag,
               gpointer user_data)

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

Parameters

drag

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 (GdkDrag *drag,
               gpointer user_data)

The drag operation was performed on an accepting client.

Parameters

drag

The object on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last