[RFC PATCH wayland-protocols] presentation: New protocol for presenting surfaces to the user

Wed Oct 16 09:16:41 UTC 2019

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.

> +
> +    - 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?

> +
> +    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.

Cheers,
Dorota Czaplejewicz
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20191016/80e8d7f7/attachment.sig>