GtkDragSource

GtkDragSource — Event controller to initiate DND operations

Properties

GdkDragAction actions Read / Write
GdkContentProvider * content Read / Write

Signals

void drag-begin Run Last
gboolean drag-cancel Run Last
void drag-end Run Last
GdkContentProvider* prepare Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── GtkEventController
        ╰── GtkGesture
            ╰── GtkGestureSingle
                ╰── GtkDragSource

Includes

#include <gtk/gtk.h>

Description

GtkDragSource is an auxiliary object that is used to initiate Drag-And-Drop operations. It can be set up with the necessary ingredients for a DND operation ahead of time. This includes the source for the data that is being transferred, in the form of a GdkContentProvider, the desired action, and the icon to use during the drag operation. After setting it up, the drag source must be added to a widget as an event controller, using gtk_widget_add_controller().

Setting up the content provider and icon ahead of time only makes sense when the data does not change. More commonly, you will want to set them up just in time. To do so, GtkDragSource has “prepare” and “drag-begin” signals. The ::prepare signal is emitted before a drag is started, and can be used to set the content provider and actions that the drag should be started with. The ::drag-begin signal is emitted after the GdkDrag object has been created, and can be used to set up the drag icon.

During the DND operation, GtkDragSource emits signals that can be used to obtain updates about the status of the operation, but it is not normally necessary to connect to any signals, except for one case: when the supported actions include GDK_ACTION_MOVE, you need to listen for the “drag-end” signal and delete the data after it has been transferred.

Functions

gtk_drag_source_new ()

GtkDragSource *
gtk_drag_source_new (void);

Creates a new GtkDragSource object.

Returns

the new GtkDragSource

gtk_drag_source_set_content ()

void
gtk_drag_source_set_content (GtkDragSource *source,
                             GdkContentProvider *content);

Sets a content provider on a GtkDragSource.

When the data is requested in the cause of a DND operation, it will be obtained from the content provider.

This function can be called before a drag is started, or in a handler for the “prepare” signal.

You may consider setting the content provider back to NULL in a “drag-end” signal handler.

Parameters

source

a GtkDragSource

content

a GdkContentProvider, or NULL.

[nullable]

gtk_drag_source_get_content ()

GdkContentProvider *
gtk_drag_source_get_content (GtkDragSource *source);

Gets the current content provider of a GtkDragSource.

Parameters

source

a GtkDragSource

Returns

the GdkContentProvider of source .

[nullable][transfer none]

gtk_drag_source_set_actions ()

void
gtk_drag_source_set_actions (GtkDragSource *source,
                             GdkDragAction actions);

Sets the actions on the GtkDragSource.

During a DND operation, the actions are offered to potential drop targets. If actions include GDK_ACTION_MOVE, you need to listen to the “drag-end” signal and handle delete_data being TRUE.

This function can be called before a drag is started, or in a handler for the “prepare” signal.

Parameters

source

a GtkDragSource

actions

the actions to offer

gtk_drag_source_get_actions ()

GdkDragAction
gtk_drag_source_get_actions (GtkDragSource *source);

Gets the actions that are currently set on the GtkDragSource.

Parameters

source

a GtkDragSource

Returns

the actions set on source

gtk_drag_source_set_icon ()

void
gtk_drag_source_set_icon (GtkDragSource *source,
                          GdkPaintable *paintable,
                          int hot_x,
                          int hot_y);

Sets a paintable to use as icon during DND operations.

The hotspot coordinates determine the point on the icon that gets aligned with the hotspot of the cursor.

If paintable is NULL, a default icon is used.

This function can be called before a drag is started, or in a “prepare” or “drag-begin” signal handler.

Parameters

source

a GtkDragSource

paintable

the GdkPaintable to use as icon, or NULL.

[nullable]

hot_x

the hotspot X coordinate on the icon

hot_y

the hotspot Y coordinate on the icon

gtk_drag_source_drag_cancel ()

void
gtk_drag_source_drag_cancel (GtkDragSource *source);

Cancels a currently ongoing drag operation.

Parameters

source

a GtkDragSource

gtk_drag_source_get_drag ()

GdkDrag *
gtk_drag_source_get_drag (GtkDragSource *source);

Returns the underlying GdkDrag object for an ongoing drag.

Parameters

source

a GtkDragSource

Returns

the GdkDrag of the current drag operation, or NULL.

[nullable][transfer none]

gtk_drag_check_threshold ()

gboolean
gtk_drag_check_threshold (GtkWidget *widget,
                          int start_x,
                          int start_y,
                          int current_x,
                          int current_y);

Checks to see if a mouse drag starting at (start_x , start_y ) and ending at (current_x , current_y ) has passed the GTK drag threshold, and thus should trigger the beginning of a drag-and-drop operation.

[method]

Parameters

widget

a GtkWidget

start_x

X coordinate of start of drag

start_y

Y coordinate of start of drag

current_x

current X coordinate

current_y

current Y coordinate

Returns

TRUE if the drag threshold has been passed.

Types and Values

GtkDragSource

typedef struct _GtkDragSource GtkDragSource;

Property Details

The “actions” property

  “actions”                  GdkDragAction

The actions that are supported by drag operations from the source.

Note that you must handle the “drag-end” signal if the actions include GDK_ACTION_MOVE.

Owner: GtkDragSource

Flags: Read / Write

Default value: GDK_ACTION_COPY

The “content” property

  “content”                  GdkContentProvider *

The data that is offered by drag operations from this source, in the form of a GdkContentProvider.

Owner: GtkDragSource

Flags: Read / Write

Signal Details

The “drag-begin” signal

void
user_function (GtkDragSource *source,
               GdkDrag       *drag,
               gpointer       user_data)

The ::drag-begin signal is emitted on the drag source when a drag is started. It can be used to e.g. set a custom drag icon with gtk_drag_source_set_icon().

Parameters

source

the GtkDragSource

drag

the GdkDrag object

user_data

user data set when the signal handler was connected.

Flags: Run Last

The “drag-cancel” signal

gboolean
user_function (GtkDragSource      *source,
               GdkDrag            *drag,
               GdkDragCancelReason reason,
               gpointer            user_data)

The ::drag-cancel signal is emitted on the drag source when a drag has failed. The signal handler may handle a failed drag operation based on the type of error. It should return TRUE if the failure has been handled and the default "drag operation failed" animation should not be shown.

Parameters

source

the GtkDragSource

drag

the GdkDrag object

reason

information on why the drag failed

user_data

user data set when the signal handler was connected.

Returns

TRUE if the failed drag operation has been already handled

Flags: Run Last

The “drag-end” signal

void
user_function (GtkDragSource *source,
               GdkDrag       *drag,
               gboolean       delete_data,
               gpointer       user_data)

The ::drag-end signal is emitted on the drag source when a drag is finished. A typical reason to connect to this signal is to undo things done in “prepare” or “drag-begin”.

Parameters

source

the GtkDragSource

drag

the GdkDrag object

delete_data

TRUE if the drag was performing GDK_ACTION_MOVE, and the data should be deleted

user_data

user data set when the signal handler was connected.

Flags: Run Last

The “prepare” signal

GdkContentProvider*
user_function (GtkDragSource *source,
               double         x,
               double         y,
               gpointer       user_data)

The ::prepare signal is emitted when a drag is about to be initiated. It returns the * GdkContentProvider to use for the drag that is about to start. The default handler for this signal returns the value of the “content” property, so if you set up that property ahead of time, you don't need to connect to this signal.

Parameters

source

the GtkDragSource

x

the X coordinate of the drag starting point

y

the Y coordinate fo the drag starting point

user_data

user data set when the signal handler was connected.

Returns

a GdkContentProvider, or NULL.

[transfer full][nullable]

Flags: Run Last

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk4/4.0/GtkDragSource.html