[RFC PATCH wayland-protocols] presentation: New protocol for presenting surfaces to the user
Carlos Garnacho
carlosg at gnome.org
Wed Oct 16 08:43:00 UTC 2019
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
More information about the wayland-devel
mailing list