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 <carl...@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 <carl...@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@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel