diff --git a/protocol/wayland.xml b/protocol/wayland.xml index 8a621904..7330b6f6 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -408,7 +408,7 @@ - + A wl_data_offer represents a piece of data offered for transfer by another client (the source client). It is used by the @@ -418,12 +418,27 @@ data directly from the source client. + + + + Indicate that the client can accept the given mime type, or NULL for not accepted. - Used for feedback during drag-and-drop. + For objects of version 2 or older, this request is used by the + client to give feedback whether the client can receive the given + mime type, or NULL if none is accepted; the feedback does not + determine whether the drag-and-drop operation succeeds or not. + + For objects of version 3 or newer, this request determines the + final result of the drag-and-drop operation. If the end result + is that no mime types were accepted, the drag-and-drop operation + will be cancelled and the corresponding drag source will receive + wl_data_source.cancelled. Clients may still use this event in + conjunction with wl_data_source.action for feedback. @@ -442,6 +457,11 @@ The receiving client reads from the read end of the pipe until EOF and then closes its end, at which point the transfer is complete. + + This request may happen multiple times for different mimetypes, + both before and after wl_data_device.drop. Drag-and-drop destination + clients may preemptively fetch data or examine it more closely to + determine acceptance. @@ -461,9 +481,26 @@ + + + + + + Notifies the compositor that the drag destination successfully + finished the drag-and-drop operation. + + Upon receiving this request, the compositor will emit + wl_data_source.dnd_finished on the drag source client. + + It is a client error to perform other requests than + wl_data_offer.destroy after this one. It is also an error to perform + this request after a NULL mime type has been set in + wl_data_offer.accept. + + - + The wl_data_source object is the source side of a wl_data_offer. It is created by the source client in a data transfer and @@ -510,14 +547,52 @@ - This data source has been replaced by another data source. + This data source is no longer valid. There are several reasons why + this could happen: + + - The data source has been replaced by another data source. + - The drag-and-drop operation was performed, but the drop destination + did not accept any of the mimetypes offered through + wl_data_source.target. + - The drag-and-drop operation was performed but didn't happen over a + surface. + - The compositor cancelled the drag-and-drop operation (e.g. compositor + dependent timeouts to avoid stale drag-and-drop transfers). + The client should clean up and destroy this data source. + + For objects of version 2 or older, wl_data_source.cancelled will + only be emitted if the data source was replaced by another data + source. + + + + + The user performed the drop action. This event does not indicate + acceptance, wl_data_source.cancelled may still be emitted afterwards + if the drop destination does not accept any mimetype. + + However, this event might however not be received if the compositor + cancelled the drag-and-drop operation before this event could happen. + + Note that the data_source may still be used in the future and should + not be destroyed here. + + + + + + The drop destination finished interoperating with this data + source, so the client is now free to destroy this data source and + free all associated data. + + - + There is one wl_data_device per seat which can be obtained from the global wl_data_device_manager singleton. @@ -659,7 +734,7 @@ - + The wl_data_device_manager is a singleton global object that provides access to inter-client data transfer mechanisms such as