<div dir="ltr"><div dir="ltr"><div dir="ltr">Hi Dorota!</div> <div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Oct 16, 2019 at 11:16 AM Dorota Czaplejewicz <<a href="mailto:dorota.czaplejewicz@puri.sm" target="_blank">dorota.czaplejewicz@puri.sm</a>> wrote: </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">On Wed, 16 Oct 2019 10:43:00 +0200 Carlos Garnacho <<a href="mailto:carlosg@gnome.org" target="_blank">carlosg@gnome.org</a>> wrote: > This protocol takes over 3 different, but interrelated aspects of > DE/client interaction: > - Startup notification: presenting feedback about applications > being launched, either through the compositor or another client > - Focus stealing prevention: letting the compositor figure out > whether immediately switching focus to a surface makes sense. > - Window raising/activation: allowing existing clients to request > focus in a controlled manner. > > Signed-off-by: Carlos Garnacho <<a href="mailto:carlosg@gnome.org" target="_blank">carlosg@gnome.org</a>> > --- > Makefile.am | 1 + > unstable/presentation/README | 5 + > .../presentation/presentation-unstable-v1.xml | 175 ++++++++++++++++++ > 3 files changed, 181 insertions(+) > create mode 100644 unstable/presentation/README > create mode 100644 unstable/presentation/presentation-unstable-v1.xml > > diff --git a/Makefile.am b/Makefile.am > index d2c89a8..bd0e52d 100644 > --- a/Makefile.am > +++ b/Makefile.am > @@ -24,6 +24,7 @@ unstable_protocols = \ > unstable/xdg-decoration/xdg-decoration-unstable-v1.xml \ > unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml \ > unstable/primary-selection/primary-selection-unstable-v1.xml \ > + unstable/presentation/presentation-unstable-v1.xml \ > $(NULL) > > stable_protocols = \ > diff --git a/unstable/presentation/README b/unstable/presentation/README > new file mode 100644 > index 0000000..5a77e97 > --- /dev/null > +++ b/unstable/presentation/README > @@ -0,0 +1,5 @@ > +Presentation protocol > + > +Maintainers: > +Carlos Garnacho <<a href="mailto:carlosg@gnome.org" target="_blank">carlosg@gnome.org</a>> > + > diff --git a/unstable/presentation/presentation-unstable-v1.xml b/unstable/presentation/presentation-unstable-v1.xml > new file mode 100644 > index 0000000..84bf961 > --- /dev/null > +++ b/unstable/presentation/presentation-unstable-v1.xml > @@ -0,0 +1,175 @@ > +<?xml version="1.0" encoding="UTF-8"?> > +<protocol name="presentation_v1"> > + <copyright> > + Copyright 2018-2019 © Red Hat, Inc. > + > + Permission is hereby granted, free of charge, to any person > + obtaining a copy of this software and associated documentation files > + (the "Software"), to deal in the Software without restriction, > + including without limitation the rights to use, copy, modify, merge, > + publish, distribute, sublicense, and/or sell copies of the Software, > + and to permit persons to whom the Software is furnished to do so, > + subject to the following conditions: > + > + The above copyright notice and this permission notice (including the > + next paragraph) shall be included in all copies or substantial > + portions of the Software. > + > + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, > + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF > + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND > + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS > + BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN > + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN > + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE > + SOFTWARE. > + </copyright> > + > + <description summary="Presentation request protocol"> > + This description provides a high-level overview of the interplay between > + the interfaces defined this protocol. For details, see the protocol > + specification. > + > + The finality of the protocol is defining a compositor context for > + surfaces requesting to be presented. Presentation requests are usually > + initiated by an existing surface, and acknowledged by a surface being > + mapped. By having both ends talk with the compositor through this protocol, > + the compositor has the information to implement different commonplace > + policies: Why does a presentation request have to come from a surface? I would expect that, similarly to creating a surface, presenting it would not require anything but a client (and maybe even no specific client) at least in the case of startup notification. </blockquote><div> </div><div>Wrt the startup notification aspect of this protocol, the reasoning was that the spawning of UI-less processes (wayland clients or not) is rarely worth UI feedback. I think my reasoning makes sense, but perhaps there's some usecase I missed?</div><div> </div><div>However, the other aspects (activation, focus stealing prevention) do require a surface, so if the consensus is that we shouldn't do that for startup notification, should probably be split somehow.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"> > + > + - Startup notification: The compositor may track wp_presenter interfaces > + being created from the launcher side, and replied upon on the launchee > + side. Compositors may also perform the application launcher role > + themselves. > + > + - Focus stealing prevention: The compositor may know whether there is > + recent user input that happened after the presentation request, and > + ensure no disruptions happen. > + > + - Window raising/activation: The presented surface may be another previously > + existing one, which might require bringing it to focus. "may be another" - is there a word like "related to" missing? </blockquote><div> </div><div>Bad wording... "The surface being presented may already exist and be mapped, which might require bringing it to focus." sounds better?</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"> > + > + A client that wishes to present another surface (of its own or from another > + client) will call wp_presentation_manager.create_presenter to create a > + presentation request. Compositors may use this object to track the source of > + the request in order to apply its policies when mapping the surface or > + bringing an existing one to focus. > + > + In the presented surface side, the request token will be notified upon > + through the wp_presentation_manager.acknowledge request. The method to pass > + the token across clients is considered an implementation detail, and is > + explicitly not observed here. > + > + Upon a successfully acknowledged presentation token, the client will receive > + a wp_presenter.done event. In the rare cases that launching an application > + would fail, the compositor may emit a wp_presenter.cancelled event > + after a reasonable timeout. > + </description> > + > + <interface name="zwp_presentation_manager" version="1"> > + <request name="create_presenter" since="1"> > + <description summary="create a new presenter"> > + Creates a new presenter. > + > + The surface argument is the toplevel that initiated the presentation > + request through user input. Compositors may want to place the presented > + surface relative to the presenter. > + > + Compositors that desire to implement focus stealing prevention > + may use this request to find out the request time. > + </description> > + <arg name="id" type="new_id" interface="zwp_presenter"/> > + <arg name="surface" type="object" interface="wl_surface"/> > + <arg name="serial" type="uint" summary="the serial from the input event"/> > + </request> > + > + <request name="acknowledge" since="1"> > + <description summary="acknowledges a presentation token"> > + Acknowledges that the calling client handled the presentation token. > + > + Applications will typically receive this through the DESKTOP_STARTUP_ID > + environment variable as set by its launcher, and should unset the > + environment variable right after this request, in order to avoid > + propagating it to child processes. > + > + Compositors will ignore unknown presentation tokens. > + > + Presentation tokens may be transferred across clients through means not > + described in this protocol. > + </description> > + <arg name="token" type="string"/> > + <arg name="surface" type="object" interface="wl_surface"/> > + </request> > + > + <request name="destroy" type="destructor"> > + <description summary="release the memory of the presentation manager object"> > + Destroy the wp_presentation_manager object. Objects created from this > + object are unaffected and should be destroyed separately. > + </description> > + </request> > + </interface> > + > + <interface name="zwp_presenter" version="1"> > + <description summary="context for presenting a surface"> > + The wp_presenter object allows clients to get the necessary context to > + request that another surface or client should be presented to the user. > + </description> > + > + <request name="set_app_id"> > + <description summary="sets the app ID of the launched application"> > + Sets the app ID of the application to be launched, the compositor > + may use this information to look up other miscellaneous information > + about it (eg. translatable name, icon, …). > + > + Clients do not need to set an app ID for presentation requests > + meant to map surfaces owned by the same client. > + > + As a best practice, it is suggested to select app > + ID's that match the basename of the application's .desktop file. > + For example, "org.freedesktop.FooViewer" where the .desktop file is > + "org.freedesktop.FooViewer.desktop". > + > + See the desktop-entry specification [0] for more details on > + application identifiers and how they relate to .desktop files. > + > + [0] <a href="http://standards.freedesktop.org/desktop-entry-spec/" rel="noreferrer" target="_blank">http://standards.freedesktop.org/desktop-entry-spec/</a> > + </description> > + </request> > + > + <request name="destroy" type="destructor"> > + <description summary="destroy zwp_presenter"> > + Destroys this zwp_presenter object. > + </description> > + </request> > + > + <event name="token" since="1"> > + <description summary="token for the presentation request"> > + Notifies of an unique presentation token (eg. UUIDs) to be used for the > + application about to be launched. > + > + In order to guarantee interoperation with the XDG Startup Notification > + spec, this launch_id is recommended to be transmitted to the launched > + application through the DESKTOP_STARTUP_ID environment variable. The > + launch ID may be passed to a running client through other means not > + observed in this protocol. > + </description> > + <arg name="token" type="string"/> > + </event> > + > + <event name="cancelled" since="1"> > + <description summary="the presenter has expired"> > + Notifies that the compositor is no longer watching this launched > + application. This may indicate failure (eg. launchee crashed) or > + may simply be the result of the launchee not replying properly > + (eg. does not implement this protocol). > + </description> > + </event> > + > + <event name="done" since="1"> > + <description summary="the presentation was performed"> > + Notifies that the launched application successfully called > + zwp_presentation_manager.acknowledge. > + </description> > + </event> > + </interface> > +</protocol> It looks okay, with the caveat that startup notification and positioning/focusing seem like two separate beasts to me. </blockquote><div> </div><div>That's a fair POV, the IPC aspect of it doesn't require that much different data flows and hence my thought of putting it together. Worth noting that both are already interrelated somehow in the last paragraph of <a href="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus">https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus</a></div><div> </div><div>If it is agreed that the semantics are different after all, maybe so.</div><div> </div><div>Cheers, </div><div> Carlos</div></div></div></div>