gtk4/org.gtkkn.bindings.gtk/DragSource

DragSource

open class DragSource(pointer: <Error class: unknown class><<Error class: unknown class>>) : GestureSingle

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.

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

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 signal@Gtk.DragSource::drag-end signal and delete the data after it has been transferred.

Constructors

DragSource

constructor()

Creates a new GtkDragSource object.

constructor(pointer: <Error class: unknown class><<Error class: unknown class>>)

Types

Companion

object Companion

Properties

actions

open var actions: <Error class: unknown class>

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

button

open var button: <Error class: unknown class>

Mouse button number to listen to, or 0 to listen for any button.

content

open var content: <Error class: unknown class>?

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

exclusive

open var exclusive: Boolean

Whether the gesture is exclusive.

gtkDragSourcePointer

val gtkDragSourcePointer: <Error class: unknown class><<Error class: unknown class>>

gtkEventControllerPointer

val gtkEventControllerPointer: <Error class: unknown class><<Error class: unknown class>>

gtkGesturePointer

val gtkGesturePointer: <Error class: unknown class><<Error class: unknown class>>

gtkGestureSinglePointer

val gtkGestureSinglePointer: <Error class: unknown class><<Error class: unknown class>>

name

open var name: String?

The name for this controller, typically used for debugging purposes.

propagationLimit

open var propagationLimit: PropagationLimit

The limit for which events this controller will handle.

propagationPhase

open var propagationPhase: PropagationPhase

The propagation phase at which this controller will handle events.

touchOnly

open var touchOnly: Boolean

Whether the gesture handles only touch events.

widget

open val widget: Widget?

The widget receiving the GdkEvents that the controller will handle.

Functions

connectBegin

fun connectBegin(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (<Error class: unknown class>?) -> Unit): <Error class: unknown class>

Emitted when the gesture is recognized.

connectCancel

fun connectCancel(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (<Error class: unknown class>?) -> Unit): <Error class: unknown class>

Emitted whenever a sequence is cancelled.

connectDragBegin

fun connectDragBegin(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (<Error class: unknown class>) -> Unit): <Error class: unknown class>

Emitted on the drag source when a drag is started.

connectDragCancel

fun connectDragCancel(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (<Error class: unknown class>, <Error class: unknown class>) -> Boolean): <Error class: unknown class>

Emitted on the drag source when a drag has failed.

connectDragEnd

fun connectDragEnd(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (<Error class: unknown class>, deleteData: Boolean) -> Unit): <Error class: unknown class>

Emitted on the drag source when a drag is finished.

connectEnd

fun connectEnd(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (<Error class: unknown class>?) -> Unit): <Error class: unknown class>

Emitted when @gesture either stopped recognizing the event sequences as something to be handled, or the number of touch sequences became higher or lower than property@Gtk.Gesture:n-points.

connectPrepare

fun connectPrepare(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (<Error class: unknown class>, <Error class: unknown class>) -> <Error class: unknown class>?): <Error class: unknown class>

Emitted when a drag is about to be initiated.

connectSequenceStateChanged

fun connectSequenceStateChanged(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (<Error class: unknown class>?, state: EventSequenceState) -> Unit): <Error class: unknown class>

Emitted whenever a sequence state changes.

connectUpdate

fun connectUpdate(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (<Error class: unknown class>?) -> Unit): <Error class: unknown class>

Emitted whenever an event is handled while the gesture is recognized.

dragCancel

open fun dragCancel()

Cancels a currently ongoing drag operation.

getBoundingBox

open fun getBoundingBox(rect: <Error class: unknown class>): Boolean

If there are touch sequences being currently handled by @gesture, returns true and fills in @rect with the bounding box containing all active touches.

getCurrentButton

open fun getCurrentButton(): <Error class: unknown class>

Returns the button number currently interacting with @gesture, or 0 if there is none.

getCurrentEvent

open fun getCurrentEvent(): <Error class: unknown class>?

Returns the event that is currently being handled by the controller.

getCurrentEventDevice

open fun getCurrentEventDevice(): <Error class: unknown class>?

Returns the device of the event that is currently being handled by the controller.

getCurrentEventState

open fun getCurrentEventState(): <Error class: unknown class>

Returns the modifier state of the event that is currently being handled by the controller.