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

[Bryce Harrington]

On Fri, Jan 15, 2016 at 09:11:39PM +0100, 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.dnd_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.dnd_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.
> 
> Changes since v6:
>   - Turned wl_data_offer.finish calls with 0/NULL state/mimetype an
>     error, made it explicit that it will only result in
>     wl_data_offer.dnd_finished being sent if successful.
> 
> Changes since v5:
>   - Further rewording of wl_data_offer.finish and wl_data_offer.accept.
>     Added error for untimely wl_data_offer.finish requests.
> 
> Changes since v4:
>   - Applied rewording suggestions from Jonas Ådahl. Added new
>     wl_data_offer.finish request to allow explicit finalization on the
>     destination side.
> 
> Changes since v3:
>   - Renamed dnd_performed to a more descriptive dnd_drop_performed,
>     documented backwards compatible behavior on wl_data_offer.accept and
>     wl_data_source.cancelled.
> 
> Changes since v2:
>   - Minor rewording.
> 
> Changes since v1:
>   - Renamed events to have a common "dnd" namespace. Made dnd_performed to
>     happen invariably, data_device.cancelled may still happen afterwards.
> 
> Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
> Reviewed-by: Michael Catanzaro <mcatanzaro at igalia.com>
> Reviewed-by: Jonas Ådahl <jadahl at gmail.com>
> Reviewed-by: Mike Blumenkrantz <zmike at samsung.com>

Reviewed-by: Bryce Harrington <bryce at osg.samsung.com>

(A few minor grammar nitpicks below, which are entirely optional and best
to do in a follow up patch post-alpha if there are no other reasons for
revving this this patch series.)

> ---
>  protocol/wayland.xml | 87 ++++++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 81 insertions(+), 6 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 8a62190..dc05993 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
> @@ -418,12 +418,27 @@
>        data directly from the source client.
>      </description>
>  
> +    <enum name="error">
> +      <entry name="invalid_finish" value="0"
> +	     summary="finish request was called untimely"/>
> +    </enum>
> +
>      <request name="accept">
>        <description summary="accept one of the offered mime types">
>  	Indicate that the client can accept the given mime type, or
>  	NULL for not accepted.
>  
> -	Used for feedback during drag-and-drop.
> +	For objects of version 2 or older, this request is used by the
> +	client to give feedback whether the client can receive the given
> +	mime type, or NULL if none is accepted; the feedback does not
> +	determine whether drag-and-drop operation succeeds or not.

whether the drag-and-drop

> +	For objects of version 3 or newer, this request determines the
> +	final result of the drag-and-drop operation. If the end result
> +	is that no mime types was accepted, the drag-and-drop operation

no mime types were accepted

> +	will be cancelled and the corresponding drag source will receive
> +	wl_data_source.cancelled. Clients may still use this event in
> +	conjunction with wl_data_source.action for feedback.
>        </description>
>  
>        <arg name="serial" type="uint"/>
> @@ -442,6 +457,11 @@
>  	The receiving client reads from the read end of the pipe until
>  	EOF and then closes its end, at which point the transfer is
>  	complete.
> +
> +	This request may happen multiple times for different mimetypes,
> +	both before and after wl_data_device.drop. Drag-and-drop destination
> +	clients may preemptively fetch data or examine it more closely to
> +	determine acceptance.
>        </description>
>        <arg name="mime_type" type="string"/>
>        <arg name="fd" type="fd"/>
> @@ -461,9 +481,26 @@
>  
>        <arg name="mime_type" type="string"/>
>      </event>
> +
> +    <!-- Version 3 additions -->
> +
> +    <request name="finish" since="3">
> +      <description summary="the offer will no longer be used">
> +	Notifies the compositor that the drag destination successfully
> +	finished the drag-and-drop operation.
> +
> +	Upon receiving this request, the compositor will emit
> +	wl_data_source.dnd_finished on the drag source client.
> +
> +	It is a client error to perform other requests than
> +	wl_data_offer.destroy after this one. It is also an error to perform
> +	this request after a NULL mime type has been set in
> +	wl_data_offer.accept.
> +      </description>
> +    </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 +547,52 @@
>  
>      <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 drag-and-drop operation was performed, but the drop destination
> +	  did not accept any of the mimetypes offered through
> +	  wl_data_source.target.
> +	- The drag-and-drop operation was performed but didn't happen over a
> +	  surface.
> +	- The compositor cancelled the drag-and-drop operation (e.g. compositor
> +	  dependent timeouts to avoid stale drag-and-drop transfers).
> +
>  	The client should clean up and destroy this data source.
> +
> +	For objects of version 2 or older, wl_data_source.cancelled will
> +	only be emitted if the data source was replaced by another data
> +	source.
> +      </description>
> +    </event>
> +
> +    <!-- Version 3 additions -->
> +
> +    <event name="dnd_drop_performed" since="3">
> +      <description summary="the drag-and-drop operation physically finished">
> +	The user performed the drop action. This event does not indicate
> +	acceptance, wl_data_source.cancelled may still be emitted afterwards
> +	if the drop destination does not accept any mimetype.
> +
> +	This event might however not be received if the compositor cancelled

However, this event might not

> +	the drag-and-drop operation before this event could happen.
> +
> +	Note that the data_source may still be used further in the future and

may still be used in the future

> +	should not be destroyed here.
>        </description>
>      </event>
>  
> +    <event name="dnd_finished" since="3">
> +      <description summary="the drag-and-drop operation concluded">
> +	The drop destination finished interoperating with this data
> +	source, the client is now free to destroy this data source and

source, so the client

> +	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 +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
> -- 
> 2.5.0
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel