DragSource

class DragSource(**properties: Any)

Superclasses: GestureSingle, Gesture, EventController, Object

Constructors:

DragSource(**properties)
new() -> Gtk.DragSource

Constructors

class DragSource
classmethod new() → DragSource

Creates a new GtkDragSource object.

Methods

class DragSource
drag_cancel() → None

Cancels a currently ongoing drag operation.

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.

get_drag() → Drag | None

Returns the underlying GdkDrag object for an ongoing drag.

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 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:

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 a drag_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 is None, 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:

  • paintable – the GdkPaintable to use as icon

  • hot_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 object

  • reason – 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 or drag_begin handlers.

Parameters:

  • drag – the GdkDrag object

  • delete_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 the content 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