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 <[email protected]> > Reviewed-by: Michael Catanzaro <[email protected]> > Reviewed-by: Jonas Ådahl <[email protected]> > Reviewed-by: Mike Blumenkrantz <[email protected]>
Reviewed-by: Bryce Harrington <[email protected]> (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 > [email protected] > http://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
