class Gtk::DragSource

Overview

Gtk::DragSource is an event controller to initiate Drag-And-Drop operations.

Gtk::DragSource 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 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 Gtk::Widget#add_controller.

WARNING ⚠️ The following code is in c ⚠️

static void
my_widget_init (MyWidget *self)
{
  Gtk::DragSource *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, Gtk::DragSource has 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.

WARNING ⚠️ The following code is in c ⚠️

static Gdk::ContentProvider *
on_drag_prepare (Gtk::DragSource *source,
                 double         x,
                 double         y,
                 MyWidget      *self)
{
  // This widget supports two types of content: GFile objects
  // and Gdk::Pixbuf objects; GTK will handle the serialization
  // of these types automatically
  GFile *file = my_widget_get_file (self);
  Gdk::Pixbuf *pixbuf = my_widget_get_pixbuf (self);

  return gdk_content_provider_new_union ((Gdk::ContentProvider *[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 Gdk::Drag object has been created, and can be used to set up the drag icon.

WARNING ⚠️ The following code is in c ⚠️

static void
on_drag_begin (Gtk::DragSource *source,
               Gdk::Drag       *drag,
               MyWidget      *self)
{
  // Set the widget as the drag icon
  Gdk::Paintable *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, Gtk::DragSource 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.

Defined in:

lib/gi-crystal/src/auto/gtk-4.0/drag_source.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Gtk::GestureSingle

==(other : self) ==, button : UInt32 button, button=(button : UInt32) : Nil button=, current_button : UInt32 current_button, current_sequence : Gdk::EventSequence | Nil current_sequence, exclusive : Bool exclusive, exclusive=(exclusive : Bool) : Nil exclusive=, exclusive? : Bool exclusive?, hash(hasher) hash, touch_only : Bool touch_only, touch_only=(touch_only : Bool) : Nil touch_only=, touch_only? : Bool touch_only?

Constructor methods inherited from class Gtk::GestureSingle

new
new(*, button : UInt32 | Nil = nil, exclusive : Bool | Nil = nil, n_points : UInt32 | Nil = nil, name : String | Nil = nil, propagation_limit : Gtk::PropagationLimit | Nil = nil, propagation_phase : Gtk::PropagationPhase | Nil = nil, touch_only : Bool | Nil = nil, widget : Gtk::Widget | Nil = nil)
new

Class methods inherited from class Gtk::GestureSingle

g_type : UInt64 g_type

Instance methods inherited from class Gtk::Gesture

==(other : self) ==, begin_signal begin_signal, bounding_box : Gdk::Rectangle bounding_box, bounding_box_center(x : Float64, y : Float64) : Bool bounding_box_center, cancel_signal cancel_signal, device : Gdk::Device | Nil device, end_signal end_signal, group(gesture : Gtk::Gesture) : Nil
group : GLib::List
group
, handles_sequence(sequence : Gdk::EventSequence | Nil) : Bool handles_sequence, hash(hasher) hash, is_active : Bool is_active, is_grouped_with(other : Gtk::Gesture) : Bool is_grouped_with, is_recognized : Bool is_recognized, last_event(sequence : Gdk::EventSequence | Nil) : Gdk::Event | Nil last_event, last_updated_sequence : Gdk::EventSequence | Nil last_updated_sequence, n_points : UInt32 n_points, n_points=(value : UInt32) : UInt32 n_points=, point(sequence : Gdk::EventSequence | Nil) : Bool point, sequence_state(sequence : Gdk::EventSequence) : Gtk::EventSequenceState sequence_state, sequence_state_changed_signal sequence_state_changed_signal, sequences : GLib::List sequences, set_sequence_state(sequence : Gdk::EventSequence, state : Gtk::EventSequenceState) : Bool set_sequence_state, state=(state : Gtk::EventSequenceState) : Bool state=, ungroup : Nil ungroup, update_signal update_signal

Constructor methods inherited from class Gtk::Gesture

new
new(*, n_points : UInt32 | Nil = nil, name : String | Nil = nil, propagation_limit : Gtk::PropagationLimit | Nil = nil, propagation_phase : Gtk::PropagationPhase | Nil = nil, widget : Gtk::Widget | Nil = nil)
new

Class methods inherited from class Gtk::Gesture

g_type : UInt64 g_type

Instance methods inherited from class Gtk::EventController

==(other : self) ==, current_event : Gdk::Event | Nil current_event, current_event_device : Gdk::Device | Nil current_event_device, current_event_state : Gdk::ModifierType current_event_state, current_event_time : UInt32 current_event_time, hash(hasher) hash, name : String | Nil name, name=(value : String) : String
name=(value : Nil) : Nil
name=(name : String | Nil) : Nil
name=
, name? : String | Nil name?, propagation_limit : Gtk::PropagationLimit propagation_limit, propagation_limit=(limit : Gtk::PropagationLimit) : Nil propagation_limit=, propagation_phase : Gtk::PropagationPhase propagation_phase, propagation_phase=(phase : Gtk::PropagationPhase) : Nil propagation_phase=, reset : Nil reset, widget : Gtk::Widget widget

Constructor methods inherited from class Gtk::EventController

new
new(*, name : String | Nil = nil, propagation_limit : Gtk::PropagationLimit | Nil = nil, propagation_phase : Gtk::PropagationPhase | Nil = nil, widget : Gtk::Widget | Nil = nil)
new

Class methods inherited from class Gtk::EventController

g_type : UInt64 g_type

Instance methods inherited from class GObject::Object

==(other : self) ==, bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void) | Nil data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, hash(hasher) hash, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void) | Nil qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void) | Nil) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void) | Nil steal_data, steal_qdata(quark : UInt32) : Pointer(Void) | Nil steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, new(pointer : Pointer(Void), transfer : GICrystal::Transfer)
new
new
, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

cast?(obj : GObject::Object) : self | Nil cast?, compat_control(what : UInt64, data : Pointer(Void) | Nil) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Macros inherited from class GObject::Object

previous_vfunc(*args) previous_vfunc, previous_vfunc!(*args) previous_vfunc!, signal(signature) signal

Constructor Detail

def self.new : self #

Creates a new Gtk::DragSource object.


[View source]
def self.new(*, actions : Gdk::DragAction | Nil = nil, button : UInt32 | Nil = nil, content : Gdk::ContentProvider | Nil = nil, exclusive : Bool | Nil = nil, n_points : UInt32 | Nil = nil, name : String | Nil = nil, propagation_limit : Gtk::PropagationLimit | Nil = nil, propagation_phase : Gtk::PropagationPhase | Nil = nil, touch_only : Bool | Nil = nil, widget : Gtk::Widget | Nil = nil) #

[View source]

Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


[View source]

Instance Method Detail

def ==(other : self) #
Description copied from class Reference

Returns true if this reference is the same as other. Invokes same?.


def actions : Gdk::DragAction #

Gets the actions that are currently set on the Gtk::DragSource.


[View source]
def actions=(actions : Gdk::DragAction) : Nil #

Sets the actions on the Gtk::DragSource.

During a DND operation, the actions are offered to potential drop targets. If actions include %GDK_ACTION_MOVE, you need to listen to the [signal@Gtk.DragSource::drag-end] signal and handle delete_data being true.

This function can be called before a drag is started, or in a handler for the Gtk::DragSource::#prepare signal.


[View source]
def content : Gdk::ContentProvider | Nil #

Gets the current content provider of a Gtk::DragSource.


[View source]
def content=(content : Gdk::ContentProvider | Nil) : Nil #

Sets a content provider on a Gtk::DragSource.

When the data is requested in the cause of a DND operation, it will be obtained from the content provider.

This function can be called before a drag is started, or in a handler for the Gtk::DragSource::#prepare signal.

You may consider setting the content provider back to nil in a [signal@Gtk.DragSource::drag-end] signal handler.


[View source]
def drag : Gdk::Drag | Nil #

Returns the underlying Gdk::Drag object for an ongoing drag.


[View source]
def drag_begin_signal #

[View source]
def drag_cancel : Nil #

Cancels a currently ongoing drag operation.


[View source]
def drag_cancel_signal #

[View source]
def drag_end_signal #

[View source]
def hash(hasher) #
Description copied from class Reference

See Object#hash(hasher)


def prepare_signal #

[View source]
def set_icon(paintable : Gdk::Paintable | Nil, hot_x : Int32, hot_y : Int32) : Nil #

Sets a paintable to use as icon during DND operations.

The hotspot coordinates determine the point on the icon that gets aligned with the hotspot of the cursor.

If paintable is nil, a default icon is used.

This function can be called before a drag is started, or in a Gtk::DragSource::#prepare or [signal@Gtk.DragSource::drag-begin] signal handler.


[View source]