[PATCH] protocol: Add DnD actions

Wed Apr 8 07:08:27 PDT 2015

Hey Bryce,

Thanks for the review! I'm attaching new patches fixing the issues 
you/Marek have seen, the doc blurbs have been reworded in a few places.

This v2 also adds a wl_data_offer.source_actions event. This allows 
drag destinations to adapt their action mask accordingly, instead just 
being practically able to set a static one, things get a bit more akin 
to XDnD in this regard.

With v2, I've been able to make DnD on par with X in GTK+ (feature-
wise, that is):
https://git.gnome.org/browse/gtk+/log/?h=wip/wayland-dnd-actions
https://git.gnome.org/browse/mutter/log/?h=wip/dnd-actions

Cheers,
  Carlos

On mié, 2015-03-18 at 16:56 -0700, Bryce Harrington wrote:
> 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
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel