DragSource
Superclasses: GestureSingle
, Gesture
, EventController
, Object
GtkDragSource
is an event controller to initiate Drag-And-Drop operations.
GtkDragSource
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 ContentProvider
, 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
add_controller
.
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.
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.
static void
on_drag_begin (GtkDragSource *source,
GdkDrag *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.
Constructors
- class DragSource
- classmethod new() DragSource
Creates a new
GtkDragSource
object.
Methods
- class DragSource
-
- get_actions() DragAction
Gets the actions that are currently set on the
GtkDragSource
.
- get_content() ContentProvider | None
Gets the current content provider of a
GtkDragSource
.
- set_actions(actions: DragAction) None
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 thedrag_end
signal and handledelete_data
beingTrue
.This function can be called before a drag is started, or in a handler for the
prepare
signal.- Parameters:
actions – the actions to offer
- set_content(content: ContentProvider | None = None) None
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
None
in adrag_end
signal handler.- Parameters:
content – a
GdkContentProvider
- set_icon(paintable: Paintable | None, hot_x: int, hot_y: int) None
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
isNone
, a default icon is used.This function can be called before a drag is started, or in a
prepare
ordrag_begin
signal handler.- Parameters:
paintable – the
GdkPaintable
to use as iconhot_x – the hotspot X coordinate on the icon
hot_y – the hotspot Y coordinate on the icon
Properties
- class DragSource
- props.actions: DragAction
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
.
- props.content: ContentProvider
The data that is offered by drag operations from this source.
Signals
- class DragSource.signals
- drag_begin(drag: Drag) None
Emitted on the drag source when a drag is started.
It can be used to e.g. set a custom drag icon with
set_icon
.- Parameters:
drag – the
GdkDrag
object
- drag_cancel(drag: Drag, reason: DragCancelReason) bool
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:
drag – the
GdkDrag
objectreason – information on why the drag failed
- drag_end(drag: Drag, delete_data: bool) None
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
ordrag_begin
handlers.- Parameters:
drag – the
GdkDrag
objectdelete_data –
True
if the drag was performing%GDK_ACTION_MOVE
, and the data should be deleted
- prepare(x: float, y: float) ContentProvider | None
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 thecontent
property, so if you set up that property ahead of time, you don’t need to connect to this signal.- Parameters:
x – the X coordinate of the drag starting point
y – the Y coordinate of the drag starting point