[PATCH v2] protocol: Add DnD actions
Carlos Garnacho
carlosg at gnome.org
Wed Apr 8 07:27:09 PDT 2015
These 2 requests have been added:
- wl_data_source.notify_actions request: Notifies the compositor of the
available actions on the data source.
- wl_data_offer.notify_actions request: Notifies the compositor of the
available actions on the destination side, plus the preferred action.
Out of the data from these requests, the compositor can determine the action
both parts agree on (and optionally let the user play a role through eg.
keyboard modifiers). The chosen option will be notified to both parties
through the following three requests:
- wl_data_source.action
- wl_data_offer.source_actions
- wl_data_offer.action
Compared to the XDND protocol, there is one notable change: XDND lets the
source suggest an action, whereas wl_data_device lets the destination
prefer a given action. The difference is subtle here, it comes off as
convenience because it is the drag destination which receives the motion
events (unlike in X) and can perform action updates.
The drag destination seems also in a better position to update the
preferred action based on things like the data being transferred, the
place being dropped, and whether the drag is client-local.
Additionally, the wl_data_source.drop_performed and finished events will
notify the source of the different termination phases of the DnD operation.
Roughly based on previous work by Giulio Camuffo <giuliocamuffo at gmail.com>
Changes since v1:
- Added wl_data_offer.source_actions to let know of the actions offered
by a data source.
- Renamed wl_data_source.finished to "drag_finished" for clarity
- Improved wording as suggested by Bryce
Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
---
protocol/wayland.xml | 113 ++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 107 insertions(+), 6 deletions(-)
diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index f52677f..ebe9061 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -408,7 +408,7 @@
</interface>
- <interface name="wl_data_offer" version="1">
+ <interface name="wl_data_offer" version="3">
<description summary="offer to transfer data">
A wl_data_offer represents a piece of data offered for transfer
by another client (the source client). It is used by the
@@ -461,9 +461,47 @@
<arg name="mime_type" type="string"/>
</event>
+
+ <!-- Version 3 additions -->
+
+ <event name="source_actions" since="3">
+ <description summary="notify the source-side available actions">
+ This event indicates the actions offered by the data source.
+ source. This event will be sent right after data_device.enter,
+ or anytime the source changes its offered actions.
+ </description>
+ <arg name="source_actions" type="uint"/>
+ </event>
+
+ <event name="action" since="3">
+ <description summary="notify the selected action">
+ This event indicates the action selected by the compositor from the
+ offered set of actions. The action will be determined after matching
+ the options offered by the source side (through data_source.set_actions)
+ and the destination side (through data_offer.notify_actions).
+
+ This event can be emitted multiple times during the lifetime of a
+ data_offer, the most recent action received is always the valid one.
+ </description>
+ <arg name="dnd_action" type="uint"/>
+ </event>
+
+ <request name="notify_actions" since="3">
+ <description summary="the data has been dropped">
+ Sets the actions that the client supports for this operation. This
+ request may trigger a data_offer.action event if the compositor needs
+ changing the selected option after the destination-side change.
+
+ Compositors wishing to allow interoperability between data_device v3
+ and earlier versions should automatically enable on behalf of the older
+ client the "copy" action as the single/preferred action.
+ </description>
+ <arg name="dnd_actions" type="uint"/>
+ <arg name="preferred_action" type="uint"/>
+ </request>
</interface>
- <interface name="wl_data_source" version="1">
+ <interface name="wl_data_source" version="3">
<description summary="offer to transfer data">
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 +548,65 @@
<event name="cancelled">
<description summary="selection was cancelled">
- This data source has been replaced by another data source.
- The client should clean up and destroy this 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 drop operation finished, but the drop destination did not accept any
+ of the mimetypes offered through data_source.target.
+ - The drop operation finished, but the drop destination did not select any
+ action present in the mask offered through data_source.action.
+
+ The client should clean up and destroy this data source.
</description>
</event>
+ <!-- Version 3 additions -->
+
+ <event name="action" since="3">
+ <description summary="notify the selected action">
+ This event indicates the action selected by the compositor from the
+ offered set of actions. The action will be determined after matching the
+ options offered by the source side (through data_source.set_actions) and
+ the destination side (through data_offer.notify_actions).
+
+ This event can be emitted multiple times during the lifetime of a
+ data_offer, the most recent action received is always the valid one.
+ </description>
+ <arg name="dnd_action" type="uint"/>
+ </event>
+
+ <request name="notify_actions" since="3">
+ <description summary="notify the available actions">
+ Sets the actions the source client supports for this operation. This
+ request may trigger a data_source.action event if the compositor needs
+ to change the selected option after the source-side change.
+
+ Compositors wishing to allow interoperability between data_device v3
+ and earlier versions should automatically enable on behalf of the older
+ client the "copy" action as the single action.
+ </description>
+ <arg name="dnd_actions" type="uint"/>
+ </request>
+
+ <event name="drop_performed" since="3">
+ <description summary="the drag and drop operation physically finished">
+ The user dropped this data onto an accepting destination. Note that
+ the data_source will be used further in the future (either immediately,
+ or in a delayed manner on "ask" actions) and should not be destroyed
+ here.
+ </description>
+ </event>
+
+ <event name="drag_finished" since="3">
+ <description summary="the drag and drop operation finished">
+ The drop destination finished requesting data from this data_source.
+ The client should clean up and destroy this data source.
+ </description>
+ </event>
</interface>
- <interface name="wl_data_device" version="2">
+ <interface name="wl_data_device" version="3">
<description summary="data transfer device">
There is one wl_data_device per seat which can be obtained
from the global wl_data_device_manager singleton.
@@ -659,7 +748,7 @@
</request>
</interface>
- <interface name="wl_data_device_manager" version="2">
+ <interface name="wl_data_device_manager" version="3">
<description summary="data transfer interface">
The wl_data_device_manager is a singleton global object that
provides access to inter-client data transfer mechanisms such as
@@ -682,6 +771,18 @@
<arg name="id" type="new_id" interface="wl_data_device"/>
<arg name="seat" type="object" interface="wl_seat"/>
</request>
+
+ <!-- Version 3 additions -->
+
+ <enum name="dnd_action" since="3">
+ <description summary="drag and drop actions">
+ This is a bitmask of the available/preferred actions in a drag and drop
+ operation.
+ </description>
+ <entry name="copy" value="1"/>
+ <entry name="move" value="2"/>
+ <entry name="ask" value="4"/>
+ </enum>
</interface>
<interface name="wl_shell" version="1">
--
2.3.5
More information about the wayland-devel
mailing list