On Fri, Jan 15, 2016 at 02:49:33PM -0800, Bryce Harrington wrote: > On Fri, Jan 15, 2016 at 09:11:40PM +0100, Carlos Garnacho wrote: > > These 2 requests have been added: > > > > - wl_data_source.set_actions: Notifies the compositor of the available > > actions on the data source. > > - wl_data_offer.set_actions: 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 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 > > > > In addition, the destination side can peek the source side actions through > > wl_data_offer.source_actions. > > > > Compared to the XDND protocol, there's two notable changes: > > > > - 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. > > > > - That same source-side preferred action is used in XDND to convey the > > modifier-induced action to the drag destination, which would then ack > > it, or reply with another action that's accepted (or none), this makes > > the XdndPosition/XdndStatus messaging very verbose, and synchronous > > because the drag source always needs to know the latest status/action > > for every position+action sent. > > > > Here it's the compositor which takes care of modifiers and matching > > available/accepted actions, this allows for the signaling to happen > > only whenever the actions/modifiers change for real. > > > > Roughly based on previous work by Giulio Camuffo <giuliocamu...@gmail.com> > > > > Changes since v10: > > - Narrow down the situations where wl_data_source/offer.accept requests > > are supposed to happen. > > > > Changes since v9: > > - Deferred the protocol errors to .finish after some IRC chat with Jonas, > > added further errors if actions API is used on selection sources/offers. > > > > Changes since v8: > > - Defined further the expected behavior on "ask", described the protocol > > errors that may happen. Fix more spaces vs tabs issues. > > > > Changes since v7: > > - Misc changes after updating the progress notification patch. > > > > Changes since v6: > > - Further explanations on wl_data_source/offer.set_actions, including a > > description of "ask" actions. Added protocol errors for unknown action > > values. > > > > Changes since v5: > > - Applied rewording suggestions from Jonas Ådahl. Dropped slot reservation > > scheme for actions. Fixed indentation and other minor formatting issues. > > > > Changes since v4: > > - Minor rewording. > > > > Changes since v3: > > - Splitted from DnD progress notification changes. > > - Further rationales in commit log. > > > > Changes since v2: > > - Renamed notify_actions to set_actions on both sides, seems more consistent > > with the rest of the protocol. > > - Spelled out better which events may be triggered on the compositor side > > by the requests, the circumstances in which events are emitted, and > > what are events useful for in clients. > > - Defined a minimal common ground wrt compositor-side action picking and > > keybindings. > > - Acknowledge the possibility of compositor/toolkit defined actions, even > > though none are used at the moment. > > Changes since v1: > > - Added wl_data_offer.source_actions to let know of the actions offered > > by a data source. > > - Renamed wl_data_source.finished to "drag_finished" for clarity > > - Improved wording as suggested by Bryce > > > > Signed-off-by: Carlos Garnacho <carl...@gnome.org> > > Reviewed-by: Michael Catanzaro <mcatanz...@igalia.com> > > Reviewed-by: Mike Blumenkrantz <zm...@samsung.com> > > Reviewed-by: Jonas Ådahl <jad...@gmail.com> > > Reviewed-by: Bryce Harrington <br...@osg.samsung.com>
I have now landed the two protocol patches after having fixed the grammar nitpicks. Carlos, it'd be good if you could just double check I did the right choices where there were options. I'm waiting with the weston patches until Monday or so, so they can get some more review. Jonas > > (Again, optional grammar nitpicks below, ok to land as follow up post-alpha.) > > > --- > > protocol/wayland.xml | 205 > > ++++++++++++++++++++++++++++++++++++++++++++++++++- > > 1 file changed, 204 insertions(+), 1 deletion(-) > > > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml > > index dc05993..cea65e9 100644 > > --- a/protocol/wayland.xml > > +++ b/protocol/wayland.xml > > @@ -421,6 +421,12 @@ > > <enum name="error"> > > <entry name="invalid_finish" value="0" > > summary="finish request was called untimely"/> > > + <entry name="invalid_action_mask" value="1" > > + summary="action mask contains invalid values"/> > > + <entry name="invalid_action" value="2" > > + summary="action argument has an invalid value"/> > > + <entry name="invalid_offer" value="3" > > + summary="offer doesn't accept this request"/> > > </enum> > > > > <request name="accept"> > > @@ -495,9 +501,98 @@ > > 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. > > + wl_data_offer.accept or no action was received through > > + wl_data_offer.action. > > </description> > > </request> > > + > > + <request name="set_actions" since="3"> > > + <description summary="set the available/preferred drag-and-drop > > actions"> > > + Sets the actions that the destination side client supports for > > + this operation. This request may trigger the emission of > > + wl_data_source.action and wl_data_offer.action events if the compositor > > + needs changing the selected action. > > needs to change > > > + This request can be called multiple times throughout the > > + drag-and-drop operation, typically in response to wl_data_device.enter > > + or wl_data_device.motion events. > > + > > + This request determines the final result of the drag-and-drop > > + operation. If the end result is that no action is accepted, > > + the drag source will receive wl_drag_source.cancelled. > > + > > + The dnd_actions argument must contain only values expressed in the > > + wl_data_device_manager.dnd_actions enum, and the preferred_action > > + argument must only contain one of those values set, otherwise it > > + will result in a protocol error. > > + > > + While managing an "ask" action, the destination drag-and-drop client > > + may perform further wl_data_offer.receive requests, and is expected > > + to perform one last wl_data_offer.set_actions request with a preferred > > + action other than "ask" (and optionally wl_data_offer.accept) before > > + requesting wl_data_offer.finish, in order to convey the action selected > > + by the user. If the preferred action is not in the > > + wl_data_offer.source_actions mask, an error will be raised. > > + > > + If the "ask" action is dismissed (e.g. user cancellation), the client > > + is expected to perform wl_data_offer.destroy right away. > > + > > + This request can only be made on drag-and-drop offers, a protocol error > > + will be raised otherwise. > > + </description> > > + <arg name="dnd_actions" type="uint"/> > > + <arg name="preferred_action" type="uint"/> > > + </request> > > + > > + <event name="source_actions" since="3"> > > + <description summary="notify the source-side available actions"> > > + This event indicates the actions offered by the data source. It > > + will be sent right after wl_data_device.enter, or anytime the source > > + side changes its offered actions through wl_data_source.set_actions. > > + </description> > > + <arg name="source_actions" type="uint"/> > > + </event> > > + > > + <event name="action" since="3"> > > + <description summary="notify the selected action"> > > + This event indicates the action selected by the compositor after > > + matching the source/destination side actions. Only one action (or > > + none) will be offered here. > > + > > + This event can be emitted multiple times during the drag-and-drop > > + operation in response to destination side action changes through > > + wl_data_offer.set_actions. > > + > > + This event will no longer be emitted after wl_data_device.drop > > + happened on the drag-and-drop destination, the client must > > + honor the last action received, or the last preferred one set > > + through wl_data_offer.set_actions when handling an "ask" action. > > + > > + Compositors may also change the selected action on the fly, mainly > > + in response to keyboard modifier changes during the drag-and-drop > > + operation. > > + > > + The most recent action received is always the valid one. Prior to > > + receiving wl_data_device.drop, the chosen action may change (e.g. > > + due to keyboard modifiers being pressed). At the time of receiving > > + wl_data_device.drop the drag-and-drop destination must honor the > > + last action received. > > + > > + Action changes may still happen after wl_data_device.drop, > > + especially on "ask" actions, where the drag-and-drop destination > > + may choose another action afterwards. Action changes happening > > + at this stage are always the result of inter-client negotiation, the > > + compositor shall no longer be able to induce a different action. > > + > > + Upon "ask" actions, the drag-and-drop destination is expected to > > + possibly choose different a different action and/or mime type, > > possibly choose a different action > > Aside: "...expected to possibly choose..." seems grammatically odd, > since "expected" indicates there is a required choice but "possibly" > suggests optional choices. Would the following preserve the meaning but > with clearer phrasing? > > Upon "ask" actions, it is expected that the drag-and-drop destination > may > potentially choose different a different action and/or mime type, > > > + based on wl_data_offer.source_actions and finally chosen by the > > + user (e.g. popping up a menu with the available options). The > > + final wl_data_offer.set_actions and wl_data_offer.accept requests > > + must happen before the call to wl_data_offer.finish. > > + </description> > > + <arg name="dnd_action" type="uint"/> > > + </event> > > </interface> > > > > <interface name="wl_data_source" version="3"> > > @@ -508,6 +603,13 @@ > > to requests to transfer the data. > > </description> > > > > + <enum name="error"> > > + <entry name="invalid_action_mask" value="0" > > + summary="action mask contains invalid values"/> > > + <entry name="invalid_source" value="1" > > + summary="source doesn't accept this request"/> > > + </enum> > > + > > <request name="offer"> > > <description summary="add an offered mime type"> > > This request adds a mime type to the set of mime types > > @@ -554,6 +656,9 @@ > > - 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 the drop destination > > + did not select any action present in the mask offered through > > + wl_data_source.action. > > did not select any of the actions present in the mask > > > - 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 > > @@ -569,6 +674,25 @@ > > > > <!-- Version 3 additions --> > > > > + <request name="set_actions" since="3"> > > + <description summary="set the available drag-and-drop actions"> > > + Sets the actions that the source side client supports for this > > + operation. This request may trigger a wl_data_source.action event and > > + wl_data_offer.action events if the compositor needs changing the > > + selected action. > > This request may trigger wl_data_source.action and wl_data_offer.action > events if the compositor needs to change the selected action. > > Do both events always get fired together if there is a change? If not, > then use "and/or" instead of "and" in the above. > > > + The dnd_actions argument must contain only values expressed in the > > + wl_data_device_manager.dnd_actions enum, otherwise it will result > > + in a protocol error. > > + > > + This request has to be made once, and can only be made on sources > > It's unclear if this is saying the request is to be made exactly once, > or at least once. So I think this should be either: > > This request must be made once only, and can only be made on sources > > or > > This request must be made at least once, and can only be made on sources > > > > + used in drag-and-drop, so it must be performed before > > + wl_data_device.start_drag. Attempting to use the source other than > > + for drag-and-drop will raise a protocol error. > > + </description> > > + <arg name="dnd_actions" type="uint"/> > > + </request> > > + > > <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 > > @@ -588,7 +712,41 @@ > > The drop destination finished interoperating with this data > > source, the client is now free to destroy this data source and > > free all associated data. > > + > > + If the action used to perform the operation was "move", the > > + source can now delete the transferred data. > > + </description> > > + </event> > > + > > + <event name="action" since="3"> > > + <description summary="notify the selected action"> > > + This event indicates the action selected by the compositor after > > + matching the source/destination side actions. Only one action (or > > + none) will be offered here. > > + > > + This event can be emitted multiple times during the drag-and-drop > > + operation, mainly in response to destination side changes through > > + wl_data_offer.set_actions, and as the data device enters/leaves > > + surfaces. > > + > > + It is only possible to receive this event after > > + wl_data_source.dnd_drop_performed if the drag-and-drop operation > > + ended in an "ask" action, in which case the final wl_data_source.action > > + event will happen immediately before wl_data_source.dnd_finished. > > + > > + Compositors may also change the selected action on the fly, mainly > > + in response to keyboard modifier changes during the drag-and-drop > > + operation. > > + > > + The most recent action received is always the valid one. The chosen > > + action may change alongside negotiation (e.g. an "ask" action can turn > > + into a "move" operation), so the effects of the final action must be > > + always applied in wl_data_offer.dnd_finished. > > final action must always be applied > > > + > > + Clients can trigger cursor surface changes from this point, so > > + they reflect the current action. > > </description> > > + <arg name="dnd_action" type="uint"/> > > </event> > > </interface> > > > > @@ -705,6 +863,17 @@ > > <description summary="end drag-and-drag session successfully"> > > The event is sent when a drag-and-drop operation is ended > > because the implicit grab is removed. > > + > > + The drag-and-drop destination is expected to honor the last action > > + received through wl_data_offer.action, if the resulting action is > > + "copy" or "move", the destination can still perform > > + wl_data_offer.receive requests, and is expected to end all > > + transfers with a wl_data_offer.finish request. > > + > > + If the resulting action is "ask", the action will not be considered > > + final. The drag-and-drop destination is expected to perform one last > > + wl_data_offer.set_actions request, or wl_data_offer.destroy in order > > + to cancel the operation. > > </description> > > </event> > > > > @@ -757,6 +926,40 @@ > > <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" bitfield="true" since="3"> > > + <description summary="drag and drop actions"> > > + This is a bitmask of the available/preferred actions in a > > + drag-and-drop operation. > > + > > + In the compositor, the selected action comes out as a result of > > + matching the actions offered by the source and destination sides. > > "comes out" seems a bit colloquial, but perhaps unnecessary anyway? > > In the compositor, the selected action is a result of > matching the actions offered by the source and destination sides. > > > + "action" events with a "none" action will be sent to both source > > + and destination if there is no match. All further checks will > > + effectively happen on (source actions ∩ destination actions). > > + > > + In addition, compositors may also pick different actions in > > + reaction to key modifiers being pressed, one common ground that > > + has been present in major toolkits (and the behavior recommended > > one common design that is used in major toolkits > > > + for compositors) is: > > + > > + - If no modifiers are pressed, the first match (in bit order) > > + will be used. > > + - Pressing Shift selects "move", if enabled in the mask. > > + - Pressing Control selects "copy", if enabled in the mask. > > + > > + Behavior beyond that is considered implementation-dependent. > > + Compositors may for example bind other modifiers (like Alt/Meta) > > + or drags initiated with other buttons than BTN_LEFT to specific > > + actions (e.g. "ask"). > > + </description> > > + <entry name="none" value="0"/> > > + <entry name="copy" value="1"/> > > + <entry name="move" value="2"/> > > + <entry name="ask" value="4"/> > > + </enum> > > </interface> > > > > <interface name="wl_shell" version="1"> > > -- > > 2.5.0 > > > > _______________________________________________ > > wayland-devel mailing list > > wayland-devel@lists.freedesktop.org > > http://lists.freedesktop.org/mailman/listinfo/wayland-devel > _______________________________________________ > wayland-devel mailing list > wayland-devel@lists.freedesktop.org > http://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel