Class

GtkDragSource

Description [src]

final class Gtk.DragSource : Gtk.GestureSingle {
  /* No available fields */
}

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 GdkContentProvider, 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 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 GtkDragSource::prepare and GtkDragSource::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,
               GtkDrag       *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 GtkDragSource::drag-end signal and delete the data after it has been transferred.

Hierarchy

hierarchy this GtkDragSource ancestor_0 GtkGestureSingle ancestor_0--this ancestor_1 GtkGesture ancestor_1--ancestor_0 ancestor_2 GtkEventController ancestor_2--ancestor_1 ancestor_3 GObject ancestor_3--ancestor_2

Constructors

gtk_drag_source_new

Creates a new GtkDragSource object.

Instance methods

gtk_drag_source_drag_cancel

Cancels a currently ongoing drag operation.

gtk_drag_source_get_actions

Gets the actions that are currently set on the GtkDragSource.

gtk_drag_source_get_content

Gets the current content provider of a GtkDragSource.

gtk_drag_source_get_drag

Returns the underlying GdkDrag object for an ongoing drag.

gtk_drag_source_set_actions

Sets the actions on the GtkDragSource.

gtk_drag_source_set_content

Sets a content provider on a GtkDragSource.

gtk_drag_source_set_icon

Sets a paintable to use as icon during DND operations.

Methods inherited from GtkGestureSingle (8)
gtk_gesture_single_get_button

Returns the button number gesture listens for.

gtk_gesture_single_get_current_button

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

gtk_gesture_single_get_current_sequence

Returns the event sequence currently interacting with gesture.

gtk_gesture_single_get_exclusive

Gets whether a gesture is exclusive.

gtk_gesture_single_get_touch_only

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

gtk_gesture_single_set_button

Sets the button number gesture listens to.

gtk_gesture_single_set_exclusive

Sets whether gesture is exclusive.

gtk_gesture_single_set_touch_only

Sets whether to handle only touch events.

Methods inherited from GtkGesture (17)
gtk_gesture_get_bounding_box

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

gtk_gesture_get_bounding_box_center

If there are touch sequences being currently handled by gesture, returns TRUE and fills in x and y with the center of the bounding box containing all active touches.

gtk_gesture_get_device

Returns the logical GdkDevice that is currently operating on gesture.

gtk_gesture_get_group

Returns all gestures in the group of gesture.

gtk_gesture_get_last_event

Returns the last event that was processed for sequence.

gtk_gesture_get_last_updated_sequence

Returns the GdkEventSequence that was last updated on gesture.

gtk_gesture_get_point

If sequence is currently being interpreted by gesture, returns TRUE and fills in x and y with the last coordinates stored for that event sequence.

gtk_gesture_get_sequence_state

Returns the sequence state, as seen by gesture.

gtk_gesture_get_sequences

Returns the list of GdkEventSequences currently being interpreted by gesture.

gtk_gesture_group

Adds gesture to the same group than group_gesture.

gtk_gesture_handles_sequence

Returns TRUE if gesture is currently handling events corresponding to sequence.

gtk_gesture_is_active

Returns TRUE if the gesture is currently active.

gtk_gesture_is_grouped_with

Returns TRUE if both gestures pertain to the same group.

gtk_gesture_is_recognized

Returns TRUE if the gesture is currently recognized.

gtk_gesture_set_sequence_state

Sets the state of sequence in gesture.

gtk_gesture_set_state

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

gtk_gesture_ungroup

Separates gesture into an isolated group.

Methods inherited from GtkEventController (12)
gtk_event_controller_get_current_event

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

gtk_event_controller_get_current_event_device

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

gtk_event_controller_get_current_event_state

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

gtk_event_controller_get_current_event_time

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

gtk_event_controller_get_name

Gets the name of controller.

gtk_event_controller_get_propagation_limit

Gets the propagation limit of the event controller.

gtk_event_controller_get_propagation_phase

Gets the propagation phase at which controller handles events.

gtk_event_controller_get_widget

Returns the GtkWidget this controller relates to.

gtk_event_controller_reset

Resets the controller to a clean state.

gtk_event_controller_set_name

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

gtk_event_controller_set_propagation_limit

Sets the event propagation limit on the event controller.

gtk_event_controller_set_propagation_phase

Sets the propagation phase at which a controller handles events.

Properties

Gtk.DragSource:actions

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

Gtk.DragSource:content

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

Properties inherited from GtkGestureSingle (3)
Gtk.GestureSingle:button

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

Gtk.GestureSingle:exclusive

Whether the gesture is exclusive.

Gtk.GestureSingle:touch-only

Whether the gesture handles only touch events.

Properties inherited from GtkGesture (1)
Gtk.Gesture:n-points

The number of touch points that trigger recognition on this gesture.

Properties inherited from GtkEventController (4)
Gtk.EventController:name

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

Gtk.EventController:propagation-limit

The limit for which events this controller will handle.

Gtk.EventController:propagation-phase

The propagation phase at which this controller will handle events.

Gtk.EventController:widget

The widget receiving the GdkEvents that the controller will handle.

Signals

Gtk.DragSource::drag-begin

Emitted on the drag source when a drag is started.

Gtk.DragSource::drag-cancel

Emitted on the drag source when a drag has failed.

Gtk.DragSource::drag-end

Emitted on the drag source when a drag is finished.

Gtk.DragSource::prepare

Emitted when a drag is about to be initiated.

Signals inherited from GtkGesture (5)
Gtk.Gesture::begin

Emitted when the gesture is recognized.

Gtk.Gesture::cancel

Emitted whenever a sequence is cancelled.

Gtk.Gesture::end

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 GtkGesture:n-points.

Gtk.Gesture::sequence-state-changed

Emitted whenever a sequence state changes.

Gtk.Gesture::update

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

Class structure

struct GtkDragSourceClass {
  /* no available fields */
}