[PATCH wayland] protocol: Improve data source notification around DnD progress

[Michael Catanzaro]

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

These are important fixes for the protocol that will allow drags to
work between GTK+ and Chrome. Thanks for working on this, Carlos!

Nit #1: the existing documentation doesn't use the DnD abbreviation, so
I would write out "drag-and-drop" in the documentation of the cancelled
event.

Nit #2: You have a comma splice in the documentation for drag_finished;
you should change it to a semicolon, or split it into two sentences, or
add a conjunction.

Minor issue: this and the next patch introduce the requirement that
accept is called on the data offer before the mouse grab is released. I
now see this has always been required by mutter -- not sure why -- but
it's new for Weston. (In fact, sending accepts has always been
optional.) The new restriction seems a bit arbitrary and could be hard
for some clients. Chrome's cross-platform DnD abstraction all but
requires drag data to have been received before it can determine
whether to accept a mime type, so Chrome doesn't send an accept until
it's done receiving. Previously, that just meant the cursor would not
be updated in response to motion events during that time, but now it
means the drop will fail. This is not a huge deal, and the other
changes in these patches are much more important, but it suggests we
shouldn't add this restriction unless there's a good reason behind
it... and I don't know of one, so I'd like to understand that. The
change isn't necessary for the protocol as-is, and doesn't seem
necessary for DnD actions, either?

On Wed, 2015-09-30 at 22:45 +0200, Carlos Garnacho wrote:
> Currently, there's no means for the DnD origin to know whether the
> destination is actually finished with the DnD transaction, short of
> finalizing it after the first transfer finishes, or leaking it
> forever.
> 
> But this poses other interoperation problems, drag destinations might
> be requesting several mimetypes at once, might be just poking to find
> out the most suitable format, might want to defer the action to a
> popup,
> might be poking contents early before the selection was dropped...
> 
> In addition, data_source.cancelled is suitable for the situations
> where
> the DnD operation fails (not on a drop target, no matching mimetypes,
> etc..), but seems undocumented for that use (and unused in weston's
> DnD).
> 
> In order to improve the situation, the drag source should be notified
> of all stages of DnD. In addition to documenting the "cancelled"
> event
> for DnD purposes, The following 2 events have been added:
> 
> - wl_data_source.drop_performed: Happens when the operation has been
>   physically finished (eg. the button is released), it could be the
> right
>   place to reset the pointer cursor back and undo any other state
> resulting
>   from the initial button press.
> - wl_data_source.drag_finished: Happens when the destination side
> destroys
>   the wl_data_offer, at this point the source can just forget all
> data
>   related to the DnD selection as well, plus optionally deleting the
> data
>   on move operations.
> 
> Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
> ---
>  protocol/wayland.xml | 34 +++++++++++++++++++++++++++++-----
>  1 file changed, 29 insertions(+), 5 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 42c9309..1ee143f 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
> @@ -463,7 +463,7 @@
>      </event>
>    </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 +510,38 @@
>  
>      <event name="cancelled">
>        <description summary="selection was cancelled">
> -	This data source has been replaced by another 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 didn't happen over a DnD
> target.
> +
>  	The client should clean up and destroy this data source.
>        </description>
>      </event>
>  
> +    <!-- Version 3 additions -->
> +
> +    <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 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 interoperating with this data
> +	source, the client is now free to destroy this data source
> and
> +	free all associated data.
> +      </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 +683,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