:right-sidebar: True DropTarget =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: DropTarget(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.EventController`, :class:`~gi.repository.GObject.Object` ``GtkDropTarget`` is an event controller to receive Drag-and-Drop operations. The most basic way to use a ``GtkDropTarget`` to receive drops on a widget is to create it via :obj:`~gi.repository.Gtk.DropTarget.new`\, passing in the ``GType`` of the data you want to receive and connect to the :obj:`~gi.repository.Gtk.DropTarget.signals.drop` signal to receive the data: .. code-block:: c :dedent: static gboolean on_drop (GtkDropTarget *target, const GValue *value, double x, double y, gpointer data) { MyWidget *self = data; // Call the appropriate setter depending on the type of data // that we received if (G_VALUE_HOLDS (value, G_TYPE_FILE)) my_widget_set_file (self, g_value_get_object (value)); else if (G_VALUE_HOLDS (value, GDK_TYPE_PIXBUF)) my_widget_set_pixbuf (self, g_value_get_object (value)); else return FALSE; return TRUE; } static void my_widget_init (MyWidget *self) { GtkDropTarget *target = gtk_drop_target_new (G_TYPE_INVALID, GDK_ACTION_COPY); // This widget accepts two types of drop types: GFile objects // and GdkPixbuf objects gtk_drop_target_set_gtypes (target, (GType [2]) { G_TYPE_FILE, GDK_TYPE_PIXBUF, }, 2); g_signal_connect (target, "drop", G_CALLBACK (on_drop), self); gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (target)); } ``GtkDropTarget`` supports more options, such as: - rejecting potential drops via the :obj:`~gi.repository.Gtk.DropTarget.signals.accept` signal and the :obj:`~gi.repository.Gtk.DropTarget.reject` function to let other drop targets handle the drop - tracking an ongoing drag operation before the drop via the :obj:`~gi.repository.Gtk.DropTarget.signals.enter`\, :obj:`~gi.repository.Gtk.DropTarget.signals.motion` and :obj:`~gi.repository.Gtk.DropTarget.signals.leave` signals - configuring how to receive data by setting the :obj:`~gi.repository.Gtk.DropTarget.props.preload` property and listening for its availability via the :obj:`~gi.repository.Gtk.DropTarget.props.value` property However, ``GtkDropTarget`` is ultimately modeled in a synchronous way and only supports data transferred via ``GType``\. If you want full control over an ongoing drop, the :obj:`~gi.repository.Gtk.DropTargetAsync` object gives you this ability. While a pointer is dragged over the drop target's widget and the drop has not been rejected, that widget will receive the :const:`~gi.repository.Gtk.StateFlags.DROP_ACTIVE` state, which can be used to style the widget. If you are not interested in receiving the drop, but just want to update UI state during a Drag-and-Drop operation (e.g. switching tabs), you can use :obj:`~gi.repository.Gtk.DropControllerMotion`\. Constructors ------------ .. rst-class:: interim-class .. class:: DropTarget :no-index: .. classmethod:: new(type: ~gobject.GType, actions: ~gi.repository.Gdk.DragAction) -> ~gi.repository.Gtk.DropTarget Creates a new ``GtkDropTarget`` object. If the drop target should support more than 1 type, pass ``Invalid`` for ``type`` and then call :obj:`~gi.repository.Gtk.DropTarget.set_gtypes`\. :param type: The supported type or ``Invalid`` :param actions: the supported actions Methods ------- .. rst-class:: interim-class .. class:: DropTarget :no-index: .. method:: get_actions() -> ~gi.repository.Gdk.DragAction Gets the actions that this drop target supports. .. method:: get_current_drop() -> ~gi.repository.Gdk.Drop | None Gets the currently handled drop operation. If no drop operation is going on, :const:`None` is returned. .. versionadded:: 4.4 .. method:: get_drop() -> ~gi.repository.Gdk.Drop | None Gets the currently handled drop operation. If no drop operation is going on, :const:`None` is returned. .. deprecated:: 4.4 Use :obj:`~gi.repository.Gtk.DropTarget.get_current_drop` instead .. method:: get_formats() -> ~gi.repository.Gdk.ContentFormats | None Gets the data formats that this drop target accepts. If the result is :const:`None`, all formats are expected to be supported. .. method:: get_gtypes() -> list[~gobject.GType] | None Gets the list of supported ``GType``\s that can be dropped on the target. If no types have been set, ``NULL`` will be returned. .. method:: get_preload() -> bool Gets whether data should be preloaded on hover. .. method:: get_value() -> ~gi.repository.GObject.Value | None Gets the current drop data, as a ``GValue``\. .. method:: reject() -> None Rejects the ongoing drop operation. If no drop operation is ongoing, i.e when :obj:`~gi.repository.Gtk.DropTarget.props.current_drop` is :const:`None`, this function does nothing. This function should be used when delaying the decision on whether to accept a drag or not until after reading the data. .. method:: set_actions(actions: ~gi.repository.Gdk.DragAction) -> None Sets the actions that this drop target supports. :param actions: the supported actions .. method:: set_gtypes(types: list[~gobject.GType] | None = None) -> None Sets the supported ``GType``\s for this drop target. :param types: all supported ``GType``\s that can be dropped on the target .. method:: set_preload(preload: bool) -> None Sets whether data should be preloaded on hover. :param preload: :const:`True` to preload drop data Properties ---------- .. rst-class:: interim-class .. class:: DropTarget :no-index: .. attribute:: props.actions :type: ~gi.repository.Gdk.DragAction The type of the None singleton. .. attribute:: props.current_drop :type: ~gi.repository.Gdk.Drop The type of the None singleton. .. versionadded:: 4.4 .. attribute:: props.drop :type: ~gi.repository.Gdk.Drop The type of the None singleton. .. deprecated:: 4.4 Use :obj:`~gi.repository.Gtk.DropTarget.props.current_drop` instead .. attribute:: props.formats :type: ~gi.repository.Gdk.ContentFormats The type of the None singleton. .. attribute:: props.preload :type: bool The type of the None singleton. .. attribute:: props.value :type: ~gi.repository.GObject.Value The type of the None singleton. Signals ------- .. rst-class:: interim-class .. class:: DropTarget.signals :no-index: .. method:: accept(drop: ~gi.repository.Gdk.Drop) -> bool The type of the None singleton. :param drop: the ``GdkDrop`` .. method:: drop(value: ~gi.repository.GObject.Value, x: float, y: float) -> bool The type of the None singleton. :param value: the ``GValue`` being dropped :param x: the x coordinate of the current pointer position :param y: the y coordinate of the current pointer position .. method:: enter(x: float, y: float) -> ~gi.repository.Gdk.DragAction The type of the None singleton. :param x: the x coordinate of the current pointer position :param y: the y coordinate of the current pointer position .. method:: leave() -> None The type of the None singleton. .. method:: motion(x: float, y: float) -> ~gi.repository.Gdk.DragAction The type of the None singleton. :param x: the x coordinate of the current pointer position :param y: the y coordinate of the current pointer position