Description

Gnome::Gtk4::DropTarget is an event controller to receive Drag-and-Drop operations.

The most basic way to use a Gnome::Gtk4::DropTarget to receive drops on a widget is to create it via .newdroptarget(), passing in the Gnome::GObject::DropTarget of the data you want to receive and connect to the drop signal to receive the data:

Gnome::Gtk4::DropTarget supports more options, such as:

* rejecting potential drops via the I<accept> signal
  and the C<.reject()> function to let other drop
  targets handle the drop
* tracking an ongoing drag operation before the drop via the
  I<enter>, I<motion> and
  I<leave> signals
* configuring how to receive data by setting the
  I<preload> property and listening for its
  availability via the I<value> property

However, Gnome::Gtk4::DropTarget is ultimately modeled in a synchronous way and only supports data transferred via Gnome::GObject::DropTarget. If you want full control over an ongoing drop, the Gnome::Gtk4::DropTargetAsync object gives you this ability.

While a pointer is dragged over the drop target's widget and the drop has not been rejected, that widget will receive the GTK_STATE_FLAG_DROP_ACTIVE state, which can be used to style the widget.

If you are not interested in receiving the drop, but just want to update UI state during a Drag-and-Drop operation (e.g. switching tabs), you can use Gnome::Gtk4::DropControllerMotion.

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

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

If the drop target should support more than 1 type, pass G_TYPE_INVALID for $type and then call .set-gtypes().

method new-droptarget ( GType $type, UInt $actions --> Gnome::Gtk4::DropTarget \)

• $type; The supported type or G_TYPE_INVALID.

• $actions; the supported actions.

Methods

get-actions

Gets the actions that this drop target supports.

method get-actions (--> UInt )

Return value; the actions that this drop target supports.

get-current-drop

Gets the currently handled drop operation.

If no drop operation is going on, undefined is returned.

method get-current-drop (--> N-Object )

Return value; The current drop.

get-drop

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.4

Gets the currently handled drop operation.

If no drop operation is going on, undefined is returned.

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

Return value; The current drop.

get-formats

Gets the data formats that this drop target accepts.

If the result is undefined, all formats are expected to be supported.

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

Return value; the supported data formats.

get-gtypes This function is not yet available

Gets the list of supported Gnome::GObject::DropTargets that can be dropped on the target.

If no types have been set, undefined will be returned.

method get-gtypes ( Array[gsize] $n-types )

• $n-types; (transfer ownership: full) the number of Gnome::GObject::DropTargets contained in the return value.

get-preload

Gets whether data should be preloaded on hover.

method get-preload (--> Bool )

Return value; True if drop data should be preloaded.

get-value

Gets the current drop data, as a Gnome::GObject::N-Value.

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

Return value; The current drop data.

reject

Rejects the ongoing drop operation.

If no drop operation is ongoing, i.e when current-drop is undefined, this function does nothing.

This function should be used when delaying the decision on whether to accept a drag or not until after reading the data.

method reject ( )

set-actions

Sets the actions that this drop target supports.

method set-actions ( UInt $actions )

• $actions; the supported actions.

set-gtypes This function is not yet available

Sets the supported Gnome::GObject::DropTargets for this drop target.

method set-gtypes ( …, Int() $n-types )

• types; all supported Gnome::GObject::DropTargets that can be dropped on the target. Note that each argument must be specified as a type followed by its value!

• $n-types; number of $types.

set-preload

Sets whether data should be preloaded on hover.

method set-preload ( Bool() $preload )

• $preload; True to preload drop data.

Signals

accept

Emitted on the drop site when a drop operation is about to begin.

If the drop is not accepted, False will be returned and the drop target will ignore the drop. If True is returned, the drop is accepted for now but may be rejected later via a call to .reject() or ultimately by returning False from a drop handler.

The default handler for this signal decides whether to accept the drop based on the formats provided by the $drop.

If the decision whether the drop will be accepted or rejected depends on the data, this function should return True, the preload property should be set and the value should be inspected via the notify:value signal, calling .reject() if required.

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

• $drop; the Gnome::Gdk4::Drop.

• $_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::DropTarget 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 $drop is accepted

drop

Emitted on the drop site when the user drops the data onto the widget.

The signal handler must determine whether the pointer position is in a drop zone or not. If it is not in a drop zone, it returns False and no further processing is necessary.

Otherwise, the handler returns True. In this case, this handler will accept the drop. The handler is responsible for using the given $value and performing the drop operation.

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

• $value; the Gnome::GObject::N-Value being dropped.

• $x; the x coordinate of the current pointer position.

• $y; the y coordinate of the current pointer position.

• $_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::DropTarget 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; whether the drop was accepted at the given pointer position

enter

Emitted on the drop site when the pointer enters the widget.

It can be used to set up custom highlighting.

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

• $x; the x coordinate of the current pointer position.

• $y; the y coordinate of the current pointer position.

• $_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::DropTarget 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.

leave

Emitted on the drop site when the pointer leaves the widget.

Its main purpose it to undo things done in enter.

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

• $_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::DropTarget 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.

motion

Emitted while the pointer is moving over the drop target.

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

• $x; the x coordinate of the current pointer position.

• $y; the y coordinate of the current pointer position.

• $_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::DropTarget 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.