[RFC PATCH wayland-protocols] presentation: New protocol for presenting surfaces to the user
Olivier Fourdan
ofourdan at redhat.com
Wed Oct 16 08:54:08 UTC 2019
Hey Carlos,
On Wed, Oct 16, 2019 at 10:43 AM 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:
> +
> + - 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.
> +
> + 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>
> --
> 2.23.0
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
The name itself, “presentation” might be confusing considering we
already have a “presentation-time” protocol.
Cheers
Olivier
More information about the wayland-devel
mailing list