Drop#

class Drop(**properties: Any)#

Superclasses: 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 GDK_DRAG_ENTER, GDK_DRAG_LEAVE, GDK_DRAG_MOTION and GDK_DROP_START. The GdkDrop object can be obtained from these Event types using 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: read_async or 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#

class Drop
finish(action: DragAction) → None#

Ends the drag operation after a drop.

The action must be a single action selected from the actions available via get_actions.

Parameters:

action – the action performed by the destination or GDK_ACTION_NONE if the drop failed

get_actions() → DragAction#

Returns the possible actions for this GdkDrop.

If this value contains multiple actions - i.e. is_unique returns false for the result - finish must choose the action to use when accepting the drop. This will only happen if you passed GDK_ACTION_ASK as one of the possible actions in status. GDK_ACTION_ASK itself will not be included in the actions returned by this function.

This value may change over the lifetime of the Drop both as a response to source side actions as well as to calls to status or finish. The source side will not change this value anymore once a drop has started.

get_device() → Device#

Returns the GdkDevice performing the drop.

get_display() → Display#

Gets the GdkDisplay that self was created for.

get_drag() → Drag | None#

If this is an in-app drag-and-drop operation, returns the GdkDrag that corresponds to this drop.

If it is not, NULL is returned.

get_formats() → ContentFormats#

Returns the GdkContentFormats that the drop offers the data to be read in.

get_surface() → Surface#

Returns the GdkSurface performing the drop.

async read_async(self, mime_types: list[str], io_priority: int) → tuple[InputStream | None, str]#

This is the awaitable version of read_async().

Parameters:

  • mime_types – pointer to an array of mime types

  • io_priority – the I/O priority for the read operation

read_async(mime_types: list[str], io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

Asynchronously read the dropped data from a GdkDrop in a format that complies with one of the mime types.

Parameters:

  • mime_types – pointer to an array of mime types

  • io_priority – the I/O priority for the read operation

  • cancellable – optional GCancellable object

  • callback – a GAsyncReadyCallback to call when the request is satisfied

  • user_data – the data to pass to callback

read_finish(result: AsyncResult) → tuple[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 read_bytes_async().

See read_async.

Parameters:

result – a GAsyncResult

async read_value_async(self, type: GType, io_priority: int) → Value#

This is the awaitable version of read_value_async().

Parameters:

  • type – a GType to read

  • io_priority – the I/O priority of the request.

read_value_async(type: GType, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: 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 content_deserialize_async to convert the data.

Parameters:

  • type – a GType to read

  • io_priority – the I/O priority of the request.

  • cancellable – optional GCancellable object, None to ignore.

  • callback – callback to call when the request is satisfied

  • user_data – the data to pass to callback function

read_value_finish(result: AsyncResult) → Value#

Finishes an async drop read.

See read_value_async.

Parameters:

result – a GAsyncResult

status(actions: DragAction, preferred: 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 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 GDK_DRAG_ENTER or GDK_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.

Parameters:

  • actions – Supported actions of the destination, or GDK_ACTION_NONE to indicate that a drop will not be accepted

  • preferred – A unique action that’s a member of actions indicating the preferred action

Properties#

class Drop
props.actions: DragAction#

The possible actions for this drop

props.device: Device#

The GdkDevice performing the drop

props.display: Display#

The GdkDisplay that the drop belongs to.

props.drag: Drag#

The GdkDrag that initiated this drop

props.formats: ContentFormats#

The possible formats that the drop can provide its data in.

props.surface: Surface#

The GdkSurface the drop happens on