Top |
Functions
GtkDragSource * | gtk_drag_source_new () |
void | gtk_drag_source_set_content () |
GdkContentProvider * | gtk_drag_source_get_content () |
void | gtk_drag_source_set_actions () |
GdkDragAction | gtk_drag_source_get_actions () |
void | gtk_drag_source_set_icon () |
void | gtk_drag_source_drag_cancel () |
GdkDrag * | gtk_drag_source_get_drag () |
gboolean | gtk_drag_check_threshold () |
Signals
void | drag-begin | Run Last |
gboolean | drag-cancel | Run Last |
void | drag-end | Run Last |
GdkContentProvider* | prepare | Run Last |
Object Hierarchy
GObject ╰── GtkEventController ╰── GtkGesture ╰── GtkGestureSingle ╰── GtkDragSource
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()
.
1 2 3 4 5 6 7 8 9 10 |
static void my_widget_init (MyWidget *self) { GtkDragSource *drag_source = gtk_drag_source_new (); g_signal_connect (drag_source, "prepare", G_CALLBACK (on_drag_prepare), self); g_signal_connect (drag_source, "drag-begin", G_CALLBACK (on_drag_begin), self); gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (drag_source)); } |
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
static GdkContentProvider * on_drag_prepare (GtkDragSource *source, double x, double y, MyWidget *self) { // This widget supports two types of content: GFile objects // and GdkPixbuf objects; GTK will handle the serialization // of these types automatically GFile *file = my_widget_get_file (self); GdkPixbuf *pixbuf = my_widget_get_pixbuf (self); return gdk_content_provider_new_union ((GdkContentProvider *[2]) { gdk_content_provider_new_typed (G_TYPE_FILE, file), gdk_content_provider_new_typed (GDK_TYPE_PIXBUF, pixbuf), }, 2); } |
The ::drag-begin signal is emitted after the GdkDrag object has been created, and can be used to set up the drag icon.
1 2 3 4 5 6 7 8 9 10 |
static void on_drag_begin (GtkDragSource *source, GtkDrag *drag, MyWidget *self) { // Set the widget as the drag icon GdkPaintable *paintable = gtk_widget_paintable_new (GTK_WIDGET (self)); gtk_drag_source_set_icon (source, paintable, 0, 0); g_object_unref (paintable); } |
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.
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.
gtk_drag_source_get_content ()
GdkContentProvider *
gtk_drag_source_get_content (GtkDragSource *source
);
Gets the current content provider of a GtkDragSource.
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.
gtk_drag_source_get_actions ()
GdkDragAction
gtk_drag_source_get_actions (GtkDragSource *source
);
Gets the actions that are currently set on the GtkDragSource.
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 |
||
paintable |
the GdkPaintable to use as icon, or |
[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.
gtk_drag_source_get_drag ()
GdkDrag *
gtk_drag_source_get_drag (GtkDragSource *source
);
Returns the underlying GdkDrag object for an ongoing drag.
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]
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. |
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 |
|
|
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. |
Flags: Run Last