[PATCH] protocol: Add DnD actions

[Bryce Harrington]

On Mon, Feb 16, 2015 at 04:37:34PM +0100, Carlos Garnacho wrote:
> 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 -->

Watch your spaces and tabs, looks like there's a mix...

> +    <event name="action" since="3">
> +      <description summary="notify the selected action">
> +	This event notifies the offer of the action selected by the compositor.

The phrasing of this first sentence seems cumbersome.  Maybe:

    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 stay compatible with earlier data_device versions
> +	should set the "copy" action by default.

Perhaps do you mean?

    "copy" action *as the* 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 wording here is very confusing.  Also I think you meant "in no"
rather than "on no".

Perhaps try phrasing it, "This data source is no longer valid.  There
are several reasons why this could happen: ..."

>  	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

as above

> +        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.

needs *to change* the

> +
> +	Clients are recommended to hardcode the "ask" action, so they can honor
> +	this action as the preferred by the destination side.

Maybe:

      Clients should always provide the "ask" action as one of the
      available options, so the destination side always knows at least
      one action that will be honored.

> +	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">

Bryce