:right-sidebar: True DragSource =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: DragSource(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.GestureSingle`, :class:`~gi.repository.Gtk.Gesture`, :class:`~gi.repository.Gtk.EventController`, :class:`~gi.repository.GObject.Object` ``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 :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.Widget.add_controller`\. .. code-block:: c :dedent: 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 :obj:`~gi.repository.Gtk.DragSource.signals.prepare` and :obj:`~gi.repository.Gtk.DragSource.signals.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. .. code-block:: c :dedent: 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. .. code-block:: c :dedent: 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 :obj:`~gi.repository.Gtk.DragSource.signals.drag_end` signal and delete the data after it has been transferred. Constructors ------------ .. rst-class:: interim-class .. class:: DragSource :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.DragSource Creates a new ``GtkDragSource`` object. Methods ------- .. rst-class:: interim-class .. class:: DragSource :no-index: .. method:: drag_cancel() -> None Cancels a currently ongoing drag operation. .. method:: get_actions() -> ~gi.repository.Gdk.DragAction Gets the actions that are currently set on the ``GtkDragSource``\. .. method:: get_content() -> ~gi.repository.Gdk.ContentProvider | None Gets the current content provider of a ``GtkDragSource``\. .. method:: get_drag() -> ~gi.repository.Gdk.Drag | None Returns the underlying ``GdkDrag`` object for an ongoing drag. .. method:: set_actions(actions: ~gi.repository.Gdk.DragAction) -> None Sets the actions on the ``GtkDragSource``\. During a DND operation, the actions are offered to potential drop targets. If ``actions`` include %GDK_ACTION_MOVE, you need to listen to the :obj:`~gi.repository.Gtk.DragSource.signals.drag_end` signal and handle ``delete_data`` being :const:`True`. This function can be called before a drag is started, or in a handler for the :obj:`~gi.repository.Gtk.DragSource.signals.prepare` signal. :param actions: the actions to offer .. method:: set_content(content: ~gi.repository.Gdk.ContentProvider | None = None) -> None Sets a content provider on a ``GtkDragSource``\. 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 :obj:`~gi.repository.Gtk.DragSource.signals.prepare` signal. You may consider setting the content provider back to :const:`None` in a :obj:`~gi.repository.Gtk.DragSource.signals.drag_end` signal handler. :param content: a ``GdkContentProvider`` .. method:: set_icon(paintable: ~gi.repository.Gdk.Paintable | None, hot_x: int, hot_y: int) -> None 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 :const:`None`, a default icon is used. This function can be called before a drag is started, or in a :obj:`~gi.repository.Gtk.DragSource.signals.prepare` or :obj:`~gi.repository.Gtk.DragSource.signals.drag_begin` signal handler. :param paintable: the ``GdkPaintable`` to use as icon :param hot_x: the hotspot X coordinate on the icon :param hot_y: the hotspot Y coordinate on the icon Properties ---------- .. rst-class:: interim-class .. class:: DragSource :no-index: .. attribute:: props.actions :type: ~gi.repository.Gdk.DragAction The type of the None singleton. .. attribute:: props.content :type: ~gi.repository.Gdk.ContentProvider The type of the None singleton. Signals ------- .. rst-class:: interim-class .. class:: DragSource.signals :no-index: .. method:: drag_begin(drag: ~gi.repository.Gdk.Drag) -> None The type of the None singleton. :param drag: the ``GdkDrag`` object .. method:: drag_cancel(drag: ~gi.repository.Gdk.Drag, reason: ~gi.repository.Gdk.DragCancelReason) -> bool The type of the None singleton. :param drag: the ``GdkDrag`` object :param reason: information on why the drag failed .. method:: drag_end(drag: ~gi.repository.Gdk.Drag, delete_data: bool) -> None The type of the None singleton. :param drag: the ``GdkDrag`` object :param delete_data: :const:`True` if the drag was performing %GDK_ACTION_MOVE, and the data should be deleted .. method:: prepare(x: float, y: float) -> ~gi.repository.Gdk.ContentProvider | None The type of the None singleton. :param x: the X coordinate of the drag starting point :param y: the Y coordinate of the drag starting point