Description

Gnome::Gtk4::DragSource is an event controller to initiate Drag-And-Drop operations.

Gnome::Gtk4::DragSource 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 Gnome::Gdk4::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() in class Gnome::Gtk4::Widget.

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, Gnome::Gtk4::DragSource 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 Gnome::Gdk4::Drag object has been created, and can be used to set up the drag icon.

During the DND operation, Gnome::Gtk4::DragSource 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.

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-dragsource

Creates a new Gnome::Gtk4::DragSource object.

method new-dragsource ( --> Gnome::Gtk4::DragSource \)

Methods

drag-cancel

Cancels a currently ongoing drag operation.

method drag-cancel ( )

get-actions

Gets the actions that are currently set on the Gnome::Gtk4::DragSource.

method get-actions (--> UInt )

Return value; the actions set on $source.

get-content

Gets the current content provider of a Gnome::Gtk4::DragSource.

method get-content (--> N-Object )

Return value; the Gnome::Gdk4::ContentProvider of $source.

get-drag

Returns the underlying Gnome::Gdk4::Drag object for an ongoing drag.

method get-drag (--> N-Object )

Return value; the Gnome::Gdk4::Drag of the current drag operation.

set-actions

Sets the actions on the Gnome::Gtk4::DragSource.

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.

method set-actions ( UInt $actions )

• $actions; the actions to offer.

set-content

Sets a content provider on a Gnome::Gtk4::DragSource.

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 undefined in a drag-end signal handler.

method set-content ( N-Object() $content )

• $content; a Gnome::Gdk4::ContentProvider.

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

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

method set-icon ( N-Object() $paintable, Int() $hot-x, Int() $hot-y )

• $paintable; the Gnome::Gdk4::R-Paintable to use as icon.

• $hot-x; the hotspot X coordinate on the icon.

• $hot-y; the hotspot Y coordinate on the icon.

Signals

drag-begin

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().

method handler (
   $drag,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::DragSource :$_widget,
  *C<user>-options
)

• $drag; the Gnome::Gdk4::Drag object.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::DragSource object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

drag-cancel

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.

method handler (
   $drag,
   $reason,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::DragSource :$_widget,
  *C<user>-options
  --> gboolean
)

• $drag; the Gnome::Gdk4::Drag object.

• $reason; information on why the drag failed.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::DragSource object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value; True if the failed drag operation has been already handled

drag-end

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.

method handler (
   $drag,
  gboolean $delete-data,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::DragSource :$_widget,
  *C<user>-options
)

• $drag; the Gnome::Gdk4::Drag object.

• $delete-data; True if the drag was performing GDK_ACTION_MOVE, and the data should be deleted.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::DragSource object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

prepare

Emitted when a drag is about to be initiated.

It returns the Gnome::Gdk4::ContentProvider 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.

method handler (
  gdouble $x,
  gdouble $y,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::DragSource :$_widget,
  *C<user>-options
)

• $x; the X coordinate of the drag starting point.

• $y; the Y coordinate of the drag starting point.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::DragSource object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.