:right-sidebar: True

DropTargetAsync
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: DropTargetAsync(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.EventController`, :class:`~gi.repository.GObject.Object`





``GtkDropTargetAsync`` is an event controller to receive Drag-and-Drop
operations, asynchronously.

It is the more complete but also more complex method of handling drop
operations compared to :obj:`~gi.repository.Gtk.DropTarget`\, and you should only use
it if ``GtkDropTarget`` doesn't provide all the features you need.

To use a ``GtkDropTargetAsync`` to receive drops on a widget, you create
a ``GtkDropTargetAsync`` object, configure which data formats and actions
you support, connect to its signals, and then attach it to the widget
with :obj:`~gi.repository.Gtk.Widget.add_controller`\.

During a drag operation, the first signal that a ``GtkDropTargetAsync``
emits is :obj:`~gi.repository.Gtk.DropTargetAsync.signals.accept`\, which is meant to determine
whether the target is a possible drop site for the ongoing drop. The
default handler for the ::accept signal accepts the drop if it finds
a compatible data format and an action that is supported on both sides.

If it is, and the widget becomes a target, you will receive a
:obj:`~gi.repository.Gtk.DropTargetAsync.signals.drag_enter` signal, followed by
:obj:`~gi.repository.Gtk.DropTargetAsync.signals.drag_motion` signals as the pointer moves,
optionally a :obj:`~gi.repository.Gtk.DropTargetAsync.signals.drop` signal when a drop happens,
and finally a :obj:`~gi.repository.Gtk.DropTargetAsync.signals.drag_leave` signal when the
pointer moves off the widget.

The ::drag-enter and ::drag-motion handler return a ``GdkDragAction``
to update the status of the ongoing operation. The ::drop handler
should decide if it ultimately accepts the drop and if it does, it
should initiate the data transfer and finish the operation by calling
:obj:`~gi.repository.Gdk.Drop.finish`\.

Between the ::drag-enter and ::drag-leave signals the widget is a
current drop target, and will receive the :const:`~gi.repository.Gtk.StateFlags.DROP_ACTIVE`
state, which can be used by themes to style the widget as a drop target.


Constructors
------------

.. rst-class:: interim-class

.. class:: DropTargetAsync
   :no-index:


   .. classmethod:: new(formats: ~gi.repository.Gdk.ContentFormats | None, actions: ~gi.repository.Gdk.DragAction) -> ~gi.repository.Gtk.DropTargetAsync

      Creates a new ``GtkDropTargetAsync`` object.






      :param formats: the supported data formats

      :param actions: the supported actions








Methods
-------

.. rst-class:: interim-class

.. class:: DropTargetAsync
   :no-index:


   .. method:: get_actions() -> ~gi.repository.Gdk.DragAction

      Gets the actions that this drop target supports.









   .. 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:: reject_drop(drop: ~gi.repository.Gdk.Drop) -> None

      Sets the ``drop`` as not accepted on this drag site.

      This function should be used when delaying the decision
      on whether to accept a drag or not until after reading
      the data.






      :param drop: the ``GdkDrop`` of an ongoing drag operation




   .. method:: set_actions(actions: ~gi.repository.Gdk.DragAction) -> None

      Sets the actions that this drop target supports.






      :param actions: the supported actions




   .. method:: set_formats(formats: ~gi.repository.Gdk.ContentFormats | None = None) -> None

      Sets the data formats that this drop target will accept.






      :param formats: the supported data formats or :const:`None` for any format








Properties
----------

.. rst-class:: interim-class

.. class:: DropTargetAsync
   :no-index:
   

   .. attribute:: props.actions
      :type: ~gi.repository.Gdk.DragAction

      The type of the None singleton.







   .. attribute:: props.formats
      :type: ~gi.repository.Gdk.ContentFormats

      The type of the None singleton.











Signals
-------

.. rst-class:: interim-class

.. class:: DropTargetAsync.signals
   :no-index:
   

   .. method:: accept(drop: ~gi.repository.Gdk.Drop) -> bool

      The type of the None singleton.







      :param drop: the ``GdkDrop``




   .. method:: drag_enter(drop: ~gi.repository.Gdk.Drop, x: float, y: float) -> ~gi.repository.Gdk.DragAction

      The type of the None singleton.







      :param drop: the ``GdkDrop``

      :param x: the x coordinate of the current pointer position

      :param y: the y coordinate of the current pointer position




   .. method:: drag_leave(drop: ~gi.repository.Gdk.Drop) -> None

      The type of the None singleton.







      :param drop: the ``GdkDrop``




   .. method:: drag_motion(drop: ~gi.repository.Gdk.Drop, x: float, y: float) -> ~gi.repository.Gdk.DragAction

      The type of the None singleton.







      :param drop: the ``GdkDrop``

      :param x: the x coordinate of the current pointer position

      :param y: the y coordinate of the current pointer position




   .. method:: drop(drop: ~gi.repository.Gdk.Drop, x: float, y: float) -> bool

      The type of the None singleton.







      :param drop: the ``GdkDrop``

      :param x: the x coordinate of the current pointer position

      :param y: the y coordinate of the current pointer position