[RFC PATCH wayland-protocols] presentation: New protocol for presenting surfaces to the user
Carlos Garnacho
carlosg at gnome.org
Thu Oct 17 22:56:38 UTC 2019
Hi Dorota!
On Wed, Oct 16, 2019 at 11:16 AM Dorota Czaplejewicz <
dorota.czaplejewicz at puri.sm> wrote:
> On Wed, 16 Oct 2019 10:43:00 +0200
> Carlos Garnacho <carlosg at gnome.org> 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 <carlosg at gnome.org>
> > ---
> > 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 <carlosg at gnome.org>
> > +
> > 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.
>
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?
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.
>
> > +
> > + - 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?
>
Bad wording... "The surface being presented may already exist and be
mapped, which might require bringing it to focus." sounds better?
>
> > +
> > + 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] http://standards.freedesktop.org/desktop-entry-spec/
> > + </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.
>
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
https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus
If it is agreed that the semantics are different after all, maybe so.
Cheers,
Carlos
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20191018/4a0bd7c3/attachment-0001.html>
More information about the wayland-devel
mailing list