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

Mon Dec 21 19:18:54 PST 2015

On Tue, Dec 22, 2015 at 02:33:32AM +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 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>
> ---
>  protocol/wayland.xml | 75 +++++++++++++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 69 insertions(+), 6 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index df8ed19..ae5ef21 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
> @@ -423,7 +423,17 @@
>  	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.
> +
> +	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
> +	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"/>
> @@ -461,9 +471,24 @@
>  
>        <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 data offer will no longer be used.
> +	Upon receiving this request, the compositor will emit
> +	wl_data_source.drag_finished or wl_data_source.cancelled on the drag
> +	source client depending on the most recent wl_data_offer.accept and
> +	wl_data_offer.set_actions requests received from this offer.
> +
> +	It is a client error to perform other requests than
> +	wl_data_offer.destroy after this one.
> +      </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 +535,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).

Another thing to add:

	- The drag-and-drop was performed and the mimetype negotiation
	  succeded, but the destination did not finish the operation.

.. or something, as to what happened if the wl_data_offer.destroy was
called without a wl_data_offer.finish.

Jonas

> +
>  	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
> +	the drag-and-drop operation before this event could happen.
> +
> +	Note that the data_source may still be used further in the future and
> +	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
> +	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 +722,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