:right-sidebar: True Drop =================================================================== .. currentmodule:: gi.repository.Gdk .. class:: Drop(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` The ``GdkDrop`` object represents the target of an ongoing DND operation. Possible drop sites get informed about the status of the ongoing drag operation with events of type :const:`~gi.repository.Gdk.EventType.DRAG_ENTER`, :const:`~gi.repository.Gdk.EventType.DRAG_LEAVE`, :const:`~gi.repository.Gdk.EventType.DRAG_MOTION` and :const:`~gi.repository.Gdk.EventType.DROP_START`. The ``GdkDrop`` object can be obtained from these :obj:`~gi.repository.Gdk.Event` types using :obj:`~gi.repository.Gdk.DNDEvent.get_drop`\. The actual data transfer is initiated from the target side via an async read, using one of the ``GdkDrop`` methods for this purpose: :obj:`~gi.repository.Gdk.Drop.read_async` or :obj:`~gi.repository.Gdk.Drop.read_value_async`\. GTK provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK applications. See the "Drag and Drop" section of the GTK documentation for more information. Methods ------- .. rst-class:: interim-class .. class:: Drop :no-index: .. method:: finish(action: ~gi.repository.Gdk.DragAction) -> None Ends the drag operation after a drop. The ``action`` must be a single action selected from the actions available via :obj:`~gi.repository.Gdk.Drop.get_actions`\. :param action: the action performed by the destination or 0 if the drop failed .. method:: get_actions() -> ~gi.repository.Gdk.DragAction Returns the possible actions for this ``GdkDrop``\. If this value contains multiple actions - i.e. :obj:`~gi.repository.Gdk.DragAction.is_unique` returns :const:`False` for the result - :obj:`~gi.repository.Gdk.Drop.finish` must choose the action to use when accepting the drop. This will only happen if you passed :const:`~gi.repository.Gdk.DragAction.ASK` as one of the possible actions in :obj:`~gi.repository.Gdk.Drop.status`\. :const:`~gi.repository.Gdk.DragAction.ASK` itself will not be included in the actions returned by this function. This value may change over the lifetime of the :obj:`~gi.repository.Gdk.Drop` both as a response to source side actions as well as to calls to :obj:`~gi.repository.Gdk.Drop.status` or :obj:`~gi.repository.Gdk.Drop.finish`\. The source side will not change this value anymore once a drop has started. .. method:: get_device() -> ~gi.repository.Gdk.Device Returns the ``GdkDevice`` performing the drop. .. method:: get_display() -> ~gi.repository.Gdk.Display Gets the ``GdkDisplay`` that ``self`` was created for. .. method:: get_drag() -> ~gi.repository.Gdk.Drag | None If this is an in-app drag-and-drop operation, returns the ``GdkDrag`` that corresponds to this drop. If it is not, :const:`None` is returned. .. method:: get_formats() -> ~gi.repository.Gdk.ContentFormats Returns the ``GdkContentFormats`` that the drop offers the data to be read in. .. method:: get_surface() -> ~gi.repository.Gdk.Surface Returns the ``GdkSurface`` performing the drop. .. method:: read_async(mime_types: list[str], io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously read the dropped data from a ``GdkDrop`` in a format that complies with one of the mime types. :param mime_types: pointer to an array of mime types :param io_priority: the I/O priority for the read operation :param cancellable: optional ``GCancellable`` object :param callback: a ``GAsyncReadyCallback`` to call when the request is satisfied :param user_data: the data to pass to ``callback`` .. method:: read_finish(result: ~gi.repository.Gio.AsyncResult) -> ~typing.Tuple[~gi.repository.Gio.InputStream | None, str] Finishes an async drop read operation. Note that you must not use blocking read calls on the returned stream in the GTK thread, since some platforms might require communication with GTK to complete the data transfer. You can use async APIs such as :func:`~gi.repository.Gio.InputStream.read_bytes_async`. See :obj:`~gi.repository.Gdk.Drop.read_async`\. :param result: a ``GAsyncResult`` .. method:: read_value_async(type: ~gobject.GType, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously request the drag operation's contents converted to the given ``type``\. For local drag-and-drop operations that are available in the given ``GType``\, the value will be copied directly. Otherwise, GDK will try to use :obj:`~gi.repository.Gdk.content_deserialize_async` to convert the data. :param type: a ``GType`` to read :param io_priority: the I/O priority of the request. :param cancellable: optional ``GCancellable`` object, :const:`None` to ignore. :param callback: callback to call when the request is satisfied :param user_data: the data to pass to callback function .. method:: read_value_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GObject.Value Finishes an async drop read. See :obj:`~gi.repository.Gdk.Drop.read_value_async`\. :param result: a ``GAsyncResult`` .. method:: status(actions: ~gi.repository.Gdk.DragAction, preferred: ~gi.repository.Gdk.DragAction) -> None Selects all actions that are potentially supported by the destination. When calling this function, do not restrict the passed in actions to the ones provided by :obj:`~gi.repository.Gdk.Drop.get_actions`\. Those actions may change in the future, even depending on the actions you provide here. The ``preferred`` action is a hint to the drag-and-drop mechanism about which action to use when multiple actions are possible. This function should be called by drag destinations in response to :const:`~gi.repository.Gdk.EventType.DRAG_ENTER` or :const:`~gi.repository.Gdk.EventType.DRAG_MOTION` events. If the destination does not yet know the exact actions it supports, it should set any possible actions first and then later call this function again. :param actions: Supported actions of the destination, or 0 to indicate that a drop will not be accepted :param preferred: A unique action that's a member of ``actions`` indicating the preferred action Properties ---------- .. rst-class:: interim-class .. class:: Drop :no-index: .. attribute:: props.actions :type: ~gi.repository.Gdk.DragAction The type of the None singleton. .. attribute:: props.device :type: ~gi.repository.Gdk.Device The type of the None singleton. .. attribute:: props.display :type: ~gi.repository.Gdk.Display The type of the None singleton. .. attribute:: props.drag :type: ~gi.repository.Gdk.Drag The type of the None singleton. .. attribute:: props.formats :type: ~gi.repository.Gdk.ContentFormats The type of the None singleton. .. attribute:: props.surface :type: ~gi.repository.Gdk.Surface The type of the None singleton.