Gtk.DragSource¶

Subclasses:: None

Methods¶

Inherited:: Gtk.GestureSingle (8), Gtk.Gesture (17), Gtk.EventController (13), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`drag_cancel` ()
	`get_actions` ()
	`get_content` ()
	`get_drag` ()
	`set_actions` (actions)
	`set_content` (content)
	`set_icon` (paintable, hot_x, hot_y)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Inherited:: Gtk.GestureSingle (3), Gtk.Gesture (1), Gtk.EventController (4)

Name	Type	Flags	Short Description
`actions`	`Gdk.DragAction`	r/w/en
`content`	`Gdk.ContentProvider`	r/w/en

Signals¶

Inherited:: Gtk.Gesture (5), GObject.Object (1)

Name	Short Description
`drag-begin`	Emitted on the drag source when a drag is started.
`drag-cancel`	Emitted on the drag source when a drag has failed.
`drag-end`	Emitted on the drag source when a drag is finished.
`prepare`	Emitted when a drag is about to be initiated.

Fields¶

Inherited:: Gtk.Gesture (5), GObject.Object (1)

Class Details¶

class Gtk.DragSource(**kwargs)¶

Bases:: Gtk.GestureSingle
Abstract:: No
Structure:: Gtk.DragSourceClass

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 [class`Gdk`.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 [method`Gtk`.Widget.add_controller].

```c static void my_widget_init (MyWidget *self) { Gtk.DragSource *drag_source = Gtk.DragSource.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 [signal`Gtk`.DragSource::prepare] and [signal`Gtk`.DragSource::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.

```c static Gdk.ContentProvider * on_drag_prepare (Gtk.DragSource *source, double x, double y, MyWidget *self) { // This widget supports two types of content: Gio.File objects // and GdkPixbuf.Pixbuf objects; GTK will handle the serialization // of these types automatically Gio.File *file = my_widget_get_file (self); GdkPixbuf.Pixbuf *pixbuf = my_widget_get_pixbuf (self);

return Gdk.ContentProvider.new_union ((Gdk.ContentProvider *[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.

``c 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.DragAction.MOVE, you need to listen for the [signal`Gtk`.DragSource::drag-end] signal and delete the data after it has been transferred.

classmethod new()[source]¶

Returns:: the new GtkDragSource
Return type:: Gtk.DragSource

Creates a new GtkDragSource object.

drag_cancel()[source]¶: Cancels a currently ongoing drag operation.

get_actions()[source]¶

Returns:: the actions set on self
Return type:: Gdk.DragAction

Gets the actions that are currently set on the GtkDragSource.

get_content()[source]¶

Returns:: the GdkContentProvider of self
Return type:: Gdk.ContentProvider or None

Gets the current content provider of a GtkDragSource.

get_drag()[source]¶

Returns:: the GdkDrag of the current drag operation
Return type:: Gdk.Drag or None

Returns the underlying GdkDrag object for an ongoing drag.

set_actions(actions)[source]¶

Parameters:: actions (Gdk.DragAction) – the actions to offer

Sets the actions on the GtkDragSource.

During a DND operation, the actions are offered to potential drop targets. If actions include Gdk.DragAction.MOVE, you need to listen to the [signal`Gtk`.DragSource::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 [signal`Gtk`.DragSource::prepare] signal.

set_content(content)[source]¶

Parameters:: content (Gdk.ContentProvider or None) – a GdkContentProvider

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 [signal`Gtk`.DragSource::prepare] signal.

You may consider setting the content provider back to None in a [signal`Gtk`.DragSource::drag-end] signal handler.

set_icon(paintable, hot_x, hot_y)[source]¶

Parameters:

paintable (Gdk.Paintable or None) – the GdkPaintable to use as icon
hot_x (int) – the hotspot X coordinate on the icon
hot_y (int) – the hotspot Y coordinate on the icon

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 None, a default icon is used.

This function can be called before a drag is started, or in a [signal`Gtk`.DragSource::prepare] or [signal`Gtk`.DragSource::drag-begin] signal handler.

Signal Details¶

Gtk.DragSource.signals.drag_begin(drag_source, drag)¶

Signal Name:

drag-begin

Flags:

RUN_LAST

Parameters:

drag_source (Gtk.DragSource) – The object which received the signal
drag (Gdk.Drag) – the GdkDrag object

Emitted on the drag source when a drag is started.

It can be used to e.g. set a custom drag icon with [method`Gtk`.DragSource.set_icon].

Gtk.DragSource.signals.drag_cancel(drag_source, drag, reason)¶

Signal Name:

drag-cancel

Flags:

RUN_LAST

Parameters:

drag_source (Gtk.DragSource) – The object which received the signal
drag (Gdk.Drag) – the GdkDrag object
reason (Gdk.DragCancelReason) – information on why the drag failed

Returns:

True if the failed drag operation has been already handled

Return type:

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.

Gtk.DragSource.signals.drag_end(drag_source, drag, delete_data)¶

Signal Name:

drag-end

Flags:

RUN_LAST

Parameters:

drag_source (Gtk.DragSource) – The object which received the signal
drag (Gdk.Drag) – the GdkDrag object
delete_data (bool) – True if the drag was performing Gdk.DragAction.MOVE, and the data should be deleted

Emitted on the drag source when a drag is finished.

A typical reason to connect to this signal is to undo things done in [signal`Gtk`.DragSource::prepare] or [signal`Gtk`.DragSource::drag-begin] handlers.

Gtk.DragSource.signals.prepare(drag_source, x, y)¶

Signal Name:

prepare

Flags:

RUN_LAST

Parameters:

drag_source (Gtk.DragSource) – The object which received the signal
x (float) – the X coordinate of the drag starting point
y (float) – the Y coordinate of the drag starting point

Returns:

a GdkContentProvider

Return type:

Gdk.ContentProvider or 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 the [property`Gtk`.DragSource:content] property, so if you set up that property ahead of time, you don’t need to connect to this signal.

Property Details¶

Gtk.DragSource.props.actions¶

Name:: actions
Type:: Gdk.DragAction
Default Value:: Gdk.DragAction.COPY
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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

Note that you must handle the [signal`Gtk`.DragSource::drag-end] signal if the actions include Gdk.DragAction.MOVE.

Gtk.DragSource.props.content¶

Name:: content
Type:: Gdk.ContentProvider
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The data that is offered by drag operations from this source.