[PATCH] protocol: Add DnD actions

[Carlos Garnacho]

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 two requests:

- wl_data_source.action
- 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>
---
 protocol/wayland.xml | 97 +++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 92 insertions(+), 5 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 2a49805..110804e 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,37 @@
 
       <arg name="mime_type" type="string"/>
     </event>
+
+    <!-- Version 3 additions -->
+
+    <event name="action" since="3">
+      <description summary="notify the selected action">
+	This event notifies the offer of the action selected by the compositor.
+        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 stay compatible with earlier data_device versions
+	should set the "copy" action by default.
+      </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 +538,61 @@
 
     <event name="cancelled">
       <description summary="selection was cancelled">
-	This data source has been replaced by another data source.
+	This data source has been replaced by another data source, or
+	the drop operation finished, but resulted on no mimetype requested
+	through data_source.target or no action notified 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 notifies the data_source of the action selected by the
+        compositor. 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
+        changing the selected option after the source-side change.
+
+	Clients are recommended to hardcode the "ask" action, so they can honor
+	this action as the preferred by the destination side.
+
+	Compositors wishing to stay compatible with earlier data_device versions
+	should set the "copy" action by default.
+      </description>
+      <arg name="dnd_actions" type="uint"/>
+    </request>
+
+    <event name="drop_performed">
+      <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="finished">
+      <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 +734,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 +757,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.1.0