[PATCH wayland-protocols] xdg-shell: Add startup notification

[Carlos Garnacho]

The xdg_launcher interface is added for the launcher, it's used
to notify of the startup ID to be transmitted to the launchee,
plus notifications about the startup success/failure.

On the launchee side, we now have xdg_shell.set_startup_id,
which will notify the compositor of startup finalization.

This has been made to be compatible with the XDG Startup
Notification spec available for X11, the startup ID is
transmitted from the launcher to the launchee in the same
ways, so we can launch x11 from wayland applications and
viceversa. The notable difference is that wayland launchers
receive startup IDs that are guaranteed to be unique, whereas
in X11 this is a best effort of the launcher client.

Some notes have also been added about focus stealing prevention,
although that's mostly up for compositors to implement.

Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
---

I've got no full implementations yet, so this is mostly an RFC at the
moment. I mainly wonder, should we add a "serial" argument to the
create_launcher request? that'd at least ensure the launcher application
has some sort of focus, although nothing prevents an application from
being a fork bomb otherwise.

 unstable/xdg-shell/xdg-shell-unstable-v5.xml | 71 +++++++++++++++++++++++++++-
 1 file changed, 70 insertions(+), 1 deletion(-)

diff --git a/unstable/xdg-shell/xdg-shell-unstable-v5.xml b/unstable/xdg-shell/xdg-shell-unstable-v5.xml
index 542491f..1c4ef54 100644
--- a/unstable/xdg-shell/xdg-shell-unstable-v5.xml
+++ b/unstable/xdg-shell/xdg-shell-unstable-v5.xml
@@ -27,7 +27,7 @@
     DEALINGS IN THE SOFTWARE.
   </copyright>
 
-  <interface name="xdg_shell" version="1">
+  <interface name="xdg_shell" version="2">
     <description summary="create desktop-style surfaces">
       xdg_shell allows clients to turn a wl_surface into a "real window"
       which can be dragged, resized, stacked, and moved around by the
@@ -135,6 +135,35 @@
       </description>
       <arg name="serial" type="uint" summary="serial of the ping event"/>
     </request>
+
+    <!-- version 2 additions -->
+    <request name="create_launcher" since="2">
+      <description summary="create a new launcher">
+        Creates a new launcher context.
+
+        The surface argument is the toplevel where the application
+        was launched from, compositors may want to place the launched
+        application relative to the launcher surface.
+
+        Compositors that desire to implement focus stealing prevention
+        can mark the time this request is received as the "startup" time.
+      </description>
+      <arg name="id" type="new_id" interface="xdg_launcher"/>
+      <arg name="surface" type="object" interface="xdg_surface"/>
+    </request>
+
+    <request name="set_startup_id" since="2">
+      <description summary="set the application startup_id">
+        Notifies the compositor of the startup ID of this launched application.
+        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 startup IDs.
+      </description>
+      <arg name="startup_id" type="string"/>
+    </request>
   </interface>
 
   <interface name="xdg_surface" version="1">
@@ -622,4 +651,44 @@
     </event>
 
   </interface>
+
+  <interface name="xdg_launcher" version="2">
+    <description summary="context for launching applications">
+      xdg_launcher allows clients to get the necessary context to launch
+      applications, so the compositor can provide feedback about the
+      application being launched.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy xdg_launcher">
+        Destroys this xdg_launcher object.
+      </description>
+    </request>
+
+    <event name="startup_id" since="2">
+      <description summary="startup ID for the launched application">
+        Notifies of an unique startup_id (eg. UUIDs) to be used for the
+        application about to be launched.
+
+        In order to guarantee interoperation with the XDG Startup Notification
+        spec, this startup_id is recommended to be transmitted to the launched
+        application through the DESKTOP_STARTUP_ID environment variable.
+      </description>
+      <arg name="startup_id" type="string"/>
+    </event>
+
+    <event name="cancelled" since="2">
+      <description summary="the launcher has expired">
+        Notifies that the compositor is no longer watching this launched
+        application.
+      </description>
+    </event>
+
+    <event name="done" since="2">
+      <description summary="the launch operation was performed">
+        Notifies that the launched application successfully called
+        xdg_shell.set_startup_id after startup.
+      </description>
+    </event>
+  </interface>
 </protocol>
-- 
2.5.0