diff options
| -rw-r--r-- | Makefile.am | 5 | ||||
| -rw-r--r-- | staging/xdg-activation/x11-interoperation.rst | 64 |
2 files changed, 69 insertions, 0 deletions
diff --git a/Makefile.am b/Makefile.am index 9954a74..6078b11 100644 --- a/Makefile.am +++ b/Makefile.am @@ -35,6 +35,10 @@ staging_protocols = \ staging/xdg-activation/xdg-activation-v1.xml \ $(NULL) +misc_documentation = \ + staging/xdg-activation/x11-interoperation.rst \ + $(NULL) + nobase_dist_pkgdata_DATA = \ $(unstable_protocols) \ $(stable_protocols) \ @@ -45,6 +49,7 @@ dist_noinst_DATA = \ $(sort $(foreach p,$(unstable_protocols),$(dir $p)README)) \ $(sort $(foreach p,$(stable_protocols),$(dir $p)README)) \ $(sort $(foreach p,$(staging_protocols),$(dir $p)README)) \ + $(misc_documentation) \ README.md \ GOVERNANCE.md \ MEMBERS.md \ diff --git a/staging/xdg-activation/x11-interoperation.rst b/staging/xdg-activation/x11-interoperation.rst new file mode 100644 index 0000000..3699180 --- /dev/null +++ b/staging/xdg-activation/x11-interoperation.rst @@ -0,0 +1,64 @@ +Interoperation with X11 +======================= + +*This document is non-normative.* + +The former X11 startup-notification standard +(https://cgit.freedesktop.org/startup-notification/tree/doc/startup-notification.txt) +defines the use of the DESKTOP_STARTUP_ID environment variable to propagate +startup sequences ("activation tokens" in this protocol) between launcher and +launchee. + +These startup sequence IDs are defined as a globally unique string with a +`[unique]_TIME[timestamp]` format, where the ID as a whole is used for startup +notification and the timestamp is used for focus requests and focus stealing +prevention. + +In order to observe mixed usage scenarios where Wayland and X11 clients might +be launching each other, it is possible for a compositor to manage a shared +pool of activation tokens. + +Scenario 1. Wayland client spawns X11 client +-------------------------------------------- + +1. Wayland client requests token. +2. Wayland client spawns X11 client, sets `$DESKTOP_STARTUP_ID` in its + environment with the token string. +3. X11 client starts. +4. X11 client sends startup-notification `remove` message with the activation + `$DESKTOP_STARTUP_ID` content. +5. Compositor receives startup notification message, matches ID with + the common pool. +6. The startup feedback is finished. +7. X11 client requests focus. +8. Compositor applies internal policies to allow/deny focus switch. + +Scenario 2. X11 client spawns Wayland client +-------------------------------------------- + +1. X11 client builds a "globally unique" ID +2. X11 client sends startup-notification `new` message with the ID. +3. Compositor receives startup notification message, adds the ID to + the common pool. +4. X11 client spawns Wayland client, sets `$DESKTOP_STARTUP_ID` in its + environment. +5. Wayland client starts. +6. Wayland client sets the activation token, as received from + `$DESKTOP_STARTUP_ID`. +7. Compositor receives the request, matches ID with the common pool +8. The startup feedback is finished. +9. Wayland client requests surface activation. +10. Compositor applies internal policies to allow/deny focus switch. + +Caveats +------- + +- For legacy reasons, the usage of `$DESKTOP_STARTUP_ID` (even if as a + fallback) should be observed in compositors and clients that are + concerned with X11 interoperation. + +- Depending on the X11 startup-notification implementation in use by the + compositor, the usage of the `_TIME[timestamp]` suffix may be mandatory + for its correct behavior in the first scenario, the startup-notification + reference library is one such implementation. Compositors may work + this around by adding a matching suffix to the generated activation tokens. |