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: (x: Double, y: Double) -> <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.

getActions

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

Gets the actions that are currently set on the GtkDragSource.

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.

getButton

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

Returns the button number @gesture listens for.

getContent

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

Gets the current content provider of a GtkDragSource.

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.

getCurrentEventTime

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

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

getCurrentSequence

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

Returns the event sequence currently interacting with @gesture.

getDevice

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

Returns the logical GdkDevice that is currently operating on @gesture.

getDrag

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

Returns the underlying GdkDrag object for an ongoing drag.

getExclusive

open fun getExclusive(): Boolean

Gets whether a gesture is exclusive.

getGroup

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

Returns all gestures in the group of @gesture

getLastEvent

open fun getLastEvent(sequence: <Error class: unknown class>? = null): <Error class: unknown class>?

Returns the last event that was processed for @sequence.

getLastUpdatedSequence

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

Returns the GdkEventSequence that was last updated on @gesture.

getName

open fun getName(): String?

Gets the name of @controller.

getPropagationLimit

open fun getPropagationLimit(): PropagationLimit

Gets the propagation limit of the event controller.

getPropagationPhase

open fun getPropagationPhase(): PropagationPhase

Gets the propagation phase at which @controller handles events.

getSequences

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

Returns the list of GdkEventSequences currently being interpreted by @gesture.

getSequenceState

open fun getSequenceState(sequence: <Error class: unknown class>): EventSequenceState

Returns the @sequence state, as seen by @gesture.

getTouchOnly

open fun getTouchOnly(): Boolean

Returns true if the gesture is only triggered by touch events.

getWidget

open fun getWidget(): Widget?

Returns the GtkWidget this controller relates to.

group

open fun group(gesture: Gesture)

Adds @gesture to the same group than @group_gesture.

handlesSequence

open fun handlesSequence(sequence: <Error class: unknown class>? = null): Boolean

Returns true if @gesture is currently handling events corresponding to @sequence.

isActive

open fun isActive(): Boolean

Returns true if the gesture is currently active.

isGroupedWith

open fun isGroupedWith(other: Gesture): Boolean

Returns true if both gestures pertain to the same group.

isRecognized

open fun isRecognized(): Boolean

Returns true if the gesture is currently recognized.

reset

open fun reset()

Resets the @controller to a clean state.

setActions

open fun setActions(actions: <Error class: unknown class>)

Sets the actions on the GtkDragSource.

setButton

open fun setButton(button: <Error class: unknown class>)

Sets the button number @gesture listens to.

setContent

open fun setContent(content: <Error class: unknown class>? = null)

Sets a content provider on a GtkDragSource.

setExclusive

open fun setExclusive(exclusive: Boolean)

Sets whether @gesture is exclusive.

setIcon

open fun setIcon(paintable: <Error class: unknown class>? = null, hotX: Int, hotY: Int)

Sets a paintable to use as icon during DND operations.

setName

open fun setName(name: String? = null)

Sets a name on the controller that can be used for debugging.

setPropagationLimit

open fun setPropagationLimit(limit: PropagationLimit)

Sets the event propagation limit on the event controller.

setPropagationPhase

open fun setPropagationPhase(phase: PropagationPhase)

Sets the propagation phase at which a controller handles events.

setSequenceState

open fun setSequenceState(sequence: <Error class: unknown class>, state: EventSequenceState): Boolean

Sets the state of @sequence in @gesture.

setState

open fun setState(state: EventSequenceState): Boolean

Sets the state of all sequences that @gesture is currently interacting with.

setStaticName

open fun setStaticName(name: String? = null)

Sets a name on the controller that can be used for debugging.

setTouchOnly

open fun setTouchOnly(touchOnly: Boolean)

Sets whether to handle only touch events.

ungroup

open fun ungroup()

Separates @gesture into an isolated group.