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

Submitted by Carlos Garnacho on Oct. 16, 2019, 8:43 a.m.

Details

Message ID 20191016084300.60070-1-carlosg@gnome.org
State New
Headers show
Series "presentation: New protocol for presenting surfaces to the user" ( rev: 1 ) in Wayland

Not browsing as part of any series.

Commit Message

Carlos Garnacho Oct. 16, 2019, 8:43 a.m.
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@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

Patch hide | download patch | download mbox

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@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>

Comments

Hey Carlos,

On Wed, Oct 16, 2019 at 10:43 AM Carlos Garnacho <carlosg@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@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@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

The name itself, “presentation” might be confusing considering we
already have a “presentation-time” protocol.

Cheers
Olivier