[PATCH wayland v4] protocol: Add DnD actions

[Michael Catanzaro]

Reviewed-by: Michael Catanzaro <mcatanzaro at igalia.com>

Nit regarding data_offer.action and data_source.action: "This event can
be emitted multiple times during the drag-and-drop operation, mainly in
response to source side changes (through data_source.set_actions),
destination side changes (through data_offer.set_actions), and as *the*
pointer enters/leaves surfaces."

Nit regarding data_offer.set_actions and data_source.set_actions: "This
request may trigger the emission of data_source.action and
data_offer.action events if the compositor needs *to change* the
selected action."

On Wed, 2015-09-30 at 22:46 +0200, Carlos Garnacho wrote:
> These 2 requests have been added:
> 
> - wl_data_source.set_actions: Notifies the compositor of the
> available
>   actions on the data source.
> - wl_data_offer.set_actions: 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 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
> 
> In addition, the destination side can peek the source side actions
> through
> wl_data_offer.source_actions.
> 
> Compared to the XDND protocol, there's two notable changes:
> 
> - 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.
> 
> - That same source-side preferred action is used in XDND to convey
> the
>   modifier-induced action to the drag destination, which would then
> ack
>   it, or reply with another action that's accepted (or none), this
> makes
>   the XdndPosition/XdndStatus messaging very verbose, and synchronous
>   because the drag source always needs to know the latest
> status/action
>   for every position+action sent.
> 
>   Here it's the compositor which takes care of modifiers and matching
>   available/accepted actions, this allows for the signaling to happen
>   only whenever the actions/modifiers change for real.
> 
> Roughly based on previous work by Giulio Camuffo <
> giuliocamuffo at gmail.com>
> 
> Changes since v3:
> - Splitted from DnD progress notification changes.
> - Further rationales in commit log.
> 
> Changes since v2:
> - Renamed notify_actions to set_actions on both sides, seems more
> consistent
>   with the rest of the protocol.
> - Spelled out better which events may be triggered on the compositor
> side
>   by the requests, the circumstances in which events are emitted, and
>   what are events useful for in clients.
> - Defined a minimal common ground wrt compositor-side action picking
> and
>   keybindings.
> - Acknowledge the possibility of compositor/toolkit defined actions,
> even
>   though none are used at the moment.
> 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 | 125
> +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 125 insertions(+)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 1ee143f..92fcd99 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -461,6 +461,52 @@
>  
>        <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.
> It
> +        will be sent right after data_device.enter, or anytime the
> source
> +        side changes its offered actions through
> data_source.set_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
> after
> +        matching the source/destination side actions. Only one
> action (or
> +        none) will be offered here.
> +
> +        This event can be emitted multiple times during the drag-and
> -drop
> +        operation, mainly in response to source side changes
> (through
> +        data_source.set_actions), destination side changes (through
> +        data_offer.set_actions), and as pointer enters/leaves
> surfaces.
> +
> +        Compositors may also change the selected action on the fly,
> mainly
> +        in response to keyboard modifier changes during the drag-and
> -drop
> +        operation.
> +
> +        The most recent action received is always the valid one.
> +      </description>
> +      <arg name="dnd_action" type="uint"/>
> +    </event>
> +
> +    <request name="set_actions" since="3">
> +      <description summary="set the available/preferred drag-and
> -drop actions">
> +        Sets the actions that the destination side client supports
> for
> +        this operation. This request may trigger the emission of
> +        data_source.action and data_offer.action events if the
> compositor
> +        needs changing the selected action.
> +
> +        This request can be called multiple times throughout the
> +        drag-and-drop operation, typically in response to
> data_device.enter
> +        or data_device.motion events.
> +      </description>
> +      <arg name="dnd_actions" type="uint"/>
> +      <arg name="preferred_action" type="uint"/>
> +    </request>
>    </interface>
>  
>    <interface name="wl_data_source" version="3">
> @@ -517,6 +563,9 @@
>  	- 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 didn't happen over a DnD
> 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>
> @@ -537,8 +586,44 @@
>  	The drop destination finished interoperating with this data
>  	source, the client is now free to destroy this data source
> and
>  	free all associated data.
> +
> +	Clients can also trigger the deletion of source-side data on
> +	"move" drag-and-drop operations.
>        </description>
>      </event>
> +
> +    <event name="action" since="3">
> +      <description summary="notify the selected action">
> +        This event indicates the action selected by the compositor
> after
> +        matching the source/destination side actions. Only one
> action (or
> +        none) will be offered here.
> +
> +        This event can be emitted multiple times during the drag-and
> -drop
> +        operation, mainly in response to source side changes
> (through
> +        data_source.set_actions), destination side changes (through
> +        data_offer.set_actions), and as pointer enters/leaves
> surfaces.
> +
> +        Compositors may also change the selected action on the fly,
> mainly
> +        in response to keyboard modifier changes during the drag-and
> -drop
> +        operation.
> +
> +        The most recent action received is always the valid one.
> +
> +        Clients can trigger cursor surface changes from this point,
> so
> +        they reflect the current action.
> +      </description>
> +      <arg name="dnd_action" type="uint"/>
> +    </event>
> +
> +    <request name="set_actions" since="3">
> +      <description summary="set the available drag-and-drop
> actions">
> +        Sets the actions that the source side client supports for
> this
> +        operation. This request may trigger a data_source.action
> event and
> +        data_offer.action events if the compositor needs changing
> the
> +        selected action.
> +      </description>
> +      <arg name="dnd_actions" type="uint"/>
> +    </request>
>    </interface>
>  
>    <interface name="wl_data_device" version="3">
> @@ -706,6 +791,46 @@
>        <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.
> +
> +        The current reserved ranges are:
> +
> +        0x0000 - 0x00FF: Reserved for the wayland core protocol.
> +        0x01FF - 0xFFFF: Reserved for future toolkit-specific use.
> Slots
> +                         may be reserved.
> +
> +        In the compositor, the selected action comes out as a result
> of
> +        matching the actions offered by the source and destination
> sides,
> +        "action" events with a "none" action will be sent to both
> source
> +        and destination if there is no match. All further checks
> will
> +        effectively happen on (source_actions & dest_actions).
> +
> +        In addition, compositors may also pick different actions in
> +        reaction to key modifiers being pressed, one common ground
> that
> +        has been present in major toolkits (and the behavior
> recommended
> +        for compositors) is:
> +
> +        - If no modifiers are pressed, the first match (in bit
> order)
> +          will be used.
> +        - Pressing Shift selects "move", if enabled in the mask.
> +        - Pressing Control selects "copy", if enabled in the mask.
> +
> +        Behavior beyond that is considered implementation-dependent.
> +        Compositors may for example bind other modifiers (like
> Alt/Meta)
> +        or drags initiated with other buttons than BTN_LEFT to
> specific
> +        actions (eg. "ask", or the next match after move/copy).
> +      </description>
> +      <entry name="none" value="0"/>
> +      <entry name="copy" value="1"/>
> +      <entry name="move" value="2"/>
> +      <entry name="ask" value="4"/>
> +    </enum>
>    </interface>
>  
>    <interface name="wl_shell" version="1">