Gtk.DragSource
Description: Reference for Gtk.DragSource

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

#### Ancestors

- GtkGestureSingle
- GtkGesture
- GtkEventController
- GObject

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

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

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

##### Signals inherited from GObject (1)

###### GObject.Object::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

#### Class structure

    struct GtkDragSourceClass {
      /* no available fields */
    }