Module data_transfer 

Cross-platform abstractions related to data transfer (i.e. clipboard and drag-and-drop).

NOTE: Interacting with the clipboard is currently implemented on Wayland, X11, macOS and Windows.

Quickstart

The API in this module is used for both sending and receiving data. The flow is detailed below, but to quickly get started, the relevant APIs are the following:

Receiving a drag-and-drop operation

• DragEntered - informs a window that a new drag operation has started.
• data_transfer - get metadata about the incoming transfer.
• DataTransfer - metadata about the incoming transfer, in particular the available types
• set_valid_dnd_actions - the application must set at least some actions as valid in order for the drag to be considered accepted.
• fetch_data_transfer - request the actual data, with a specific type, from the data transfer.
• DataTransferReceived - the actual data, with a specific type, has been received.
• TypedData - provides methods to read the actual data

Sending a drag-and-drop operation

• DataTransferSend - the core trait which defines data to be sent
• DataTransferSendBuilder - helper to create a new outgoing data transfer from a set of types and callbacks that supply data of that type
• ActiveEventLoop::start_drag - the application calls this to start a new drag operation
• OutgoingDragDropped/ OutgoingDragCanceled - the application receives this when the user has ended the drag operation, by dropping the data or by canceling the operation respectively

Detailed flow

Receiving a drag-and-drop operation

On all platforms, the process looks something like this:

• A data transfer advertises a set of types which the data can be interpreted as. While the precise implementation depends on platform, there’s a set of types which can be safely transferred between applications on all platforms (see TypeHint).
  • For example, if you copy or drag text from a web page, the browser may advertise the text formatted using HTML, the text formatted as RTF, and the text with all formatting removed simultaneously.
• An application receiving a data transfer chooses one or more types that it understands and requests the data in those formats (in practice, it will usually only request a single format).
• The source application converts the data stored in its memory to the requested format and asynchronously sends it to the target application

On some platforms, the data is sometimes available synchronously, but all platforms have at least some method of sending the data asynchronously and some types of data that may only be sent using the asynchronous interface. Because of this, the API in wingy must be asynchronous.

The flow for a user application that implements drag-and-drop would look something like this:

• The application receives a DragEntered event. This event supplies a DataTransferId which can be used to request information or operations on the dragged data by using methods on Window.
• To make sure that the operating system displays the correct cursor, and that modifier keys will change the selected drag action correctly, the application should call set_valid_dnd_actions. See documentation on that method for details.
• As the drag operation continues, the window will receive DragPosition events.
• At any point during this operation, the receiving application may request either the available types or even the data being transferred. This may be useful in cases where the application wants to preload the data. For example, an image editor may want to display the image on the canvas during the drag operation.
• When the user tries to drop the data onto the window, that window will receive either a DragDropped or DragLeft event if the drag operation was accepted or rejected, respectively. See documentation for set_valid_dnd_actions for details on accepting/rejecting a drag.

Sending a drag-and-drop operation

As the source application cannot interact with the ongoing drag while it is in-flight, this flow is a lot simpler.

• The application creates a DataTransferSend with a set of types and associated data. For most cases, this can be done with DataTransferSendBuilder.
• The application passes this DataTransferSend to ActiveEventLoop::start_drag`. This is also where metadata is set, such as the icon that will be shown during the drag operation.
• When the drag operation completes, the application receives OutgoingDragDropped with the resultant action, or OutgoingDragCanceled, and handles it appropriately. For example, if the drag was successful and the operation is DndAction::Move, then the application would delete the source object, since the data has now been transferred somewhere else.

Structs

DataTransferId

Unique identifier for a data transfer.

DataTransferSendBuilder

Dynamic builder for an implementation of DataTransferSend.

Enums

SendData

Kinds of data that can be sent via a DataTransfer.

TypeHint

The set of types supported cross-platform.

Traits

DataTransfer

Metadata about a data transfer. This does not allow actually receiving data, as that is an asynchronous operation. To fetch the data from the source application, see ActiveEventLoop::fetch_data_transfer.

DataTransferSend

Trait for sending data via a data transfer.

TransferType

The type of a data transfer.

TypedData

Data that has been fetched from a data transfer