4.13. Data sharing between clients
The Wayland protocol provides clients a mechanism for sharing data that allows the implementation of copy-paste and drag-and-drop. The client providing the data creates a wl_data_source
object and the clients obtaining the data will see it as wl_data_offer
object. This interface allows the clients to agree on a mutually supported mime type and transfer the data via a file descriptor that is passed through the protocol.
The next section explains the negotiation between data source and data offer objects.
Section 4.13.2, “Data devices” explains how these objects are created and passed to different clients using the
wl_data_device
interface that implements copy-paste and drag-and-drop support.
A client providing data to other clients will create a wl_data_source
object and advertise the mime types for the formats it supports for that data through the wl_data_source.offer
request. On the receiving end, the data offer object will generate one wl_data_offer.offer
event for each supported mime type.
The actual data transfer happens when the receiving client sends a wl_data_offer.receive
request. This request takes a mime type and a file descriptor as arguments. This request will generate a wl_data_source.send
event on the sending client with the same arguments, and the latter client is expected to write its data to the given file descriptor using the chosen mime type.
Data devices glue data sources and offers together. A data device is associated with a wl_seat
and is obtained by the clients using the wl_data_device_manager
factory object, which is also responsible for creating data sources.
Clients are informed of new data offers through the wl_data_device.data_offer
event. After this event is generated the data offer will advertise the available mime types. New data offers are introduced prior to their use for copy-paste or drag-and-drop.
Each data device has a selection data source. Clients create a data source object using the device manager and may set it as the current selection for a given data device. Whenever the current selection changes, the client with keyboard focus receives a wl_data_device.selection
event. This event is also generated on a client immediately before it receives keyboard focus.
The data offer is introduced with wl_data_device.data_offer
event before the selection event.
A drag-and-drop operation is started using the wl_data_device.start_drag
request. This requests causes a pointer grab that will generate enter, motion and leave events on the data device. A data source is supplied as argument to start_drag, and data offers associated with it are supplied to clients surfaces under the pointer in the wl_data_device.enter
event. The data offer is introduced to the client prior to the enter event with the wl_data_device.data_offer
event.
Clients are expected to provide feedback to the data sending client by calling the wl_data_offer.accept
request with a mime type it accepts. If none of the advertised mime types is supported by the receiving client, it should supply NULL to the accept request. The accept request causes the sending client to receive a wl_data_source.target
event with the chosen mime type.
When the drag ends, the receiving client receives a wl_data_device.drop
event at which it is expected to transfer the data using the wl_data_offer.receive
request.