From da68b270d9bf599b8adea9099d3f46e93f30227e Mon Sep 17 00:00:00 2001 From: Matthias Klumpp Date: Thu, 16 Apr 2026 20:11:26 +0200 Subject: [PATCH] Add xdg-toplevel-groups for persistent toplevel z-ordering This new protocol allows clients to set a persistent z-order for their toplevels, permanently keeping some toplevels above others no matter which one gets activated by the user. This paradigm is very commonly used by DAW (Digital Audio Workstation) and CAD (Computer-aided Design) applications, which utilize a lot of windows and toolboxes and often have plugins running in separate processes. Signed-off-by: Matthias Klumpp --- meson.build | 1 + staging/xdg-toplevel-groups/README | 4 + .../xdg-toplevel-groups-v1.xml | 188 ++++++++++++++++++ 3 files changed, 193 insertions(+) create mode 100644 staging/xdg-toplevel-groups/README create mode 100644 staging/xdg-toplevel-groups/xdg-toplevel-groups-v1.xml diff --git a/meson.build b/meson.build index 4eda373..1ea8137 100644 --- a/meson.build +++ b/meson.build @@ -78,6 +78,7 @@ staging_protocols = { 'xdg-session-management': {'v1': ['stable/xdg-shell/xdg-shell.xml']}, 'xdg-system-bell': {'v1': []}, 'xdg-toplevel-drag': {'v1': ['stable/xdg-shell/xdg-shell.xml']}, + 'xdg-toplevel-groups': {'v1': ['stable/xdg-shell/xdg-shell.xml']}, 'xdg-toplevel-icon': {'v1': ['stable/xdg-shell/xdg-shell.xml']}, 'xdg-toplevel-tag': {'v1': ['stable/xdg-shell/xdg-shell.xml']}, 'xwayland-shell': {'v1': []}, diff --git a/staging/xdg-toplevel-groups/README b/staging/xdg-toplevel-groups/README new file mode 100644 index 0000000..c9435f2 --- /dev/null +++ b/staging/xdg-toplevel-groups/README @@ -0,0 +1,4 @@ +Toplevel Groups protocol + +Maintainers: +Matthias Klumpp (@mak) diff --git a/staging/xdg-toplevel-groups/xdg-toplevel-groups-v1.xml b/staging/xdg-toplevel-groups/xdg-toplevel-groups-v1.xml new file mode 100644 index 0000000..5030d3d --- /dev/null +++ b/staging/xdg-toplevel-groups/xdg-toplevel-groups-v1.xml @@ -0,0 +1,188 @@ + + + + + Copyright © 2024-2026 Matthias Klumpp + + 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. + + + + This protocol provides a way for clients to set a persistent layering order + between their toplevels. + + This is useful for clients that want to keep specific toplevels above or below + other toplevels, no matter whether they currently have focus or not, when using + a stacking window manager. + This is useful for multi-window applications, where for example some utility + windows or control windows should float above a main window even if they are + not currently activated. + + This document adheres to RFC 2119 when using words like "must", + "should", "may", etc. + + Warning! The protocol described in this file is currently in the testing + phase. Backward compatible changes may be added together with the + corresponding interface version bump. Backward incompatible changes can + only be done by creating a new major version of the extension. + + + + + The 'xdg_toplevel_group_manager' interface defines base requests for obtaining and + managing toplevel groups for a client. + + A toplevel group is a collection of toplevels that can be layered together. + + + + + This has no effect other than to destroy the 'xdg_toplevel_group_manager' object. + + + + + + Create a new toplevel group. + + + + + + + Import a toplevel group based on its handle. This allows clients to share + toplevel groups between each other. + The handle of a group can be obtained from the 'handle' event of the + 'xdg_toplevel_group_v1' interface. + The compositor must ensure that the same handle always refers to the + same group. + If the handle is invalid, this request must return a new group. + + + + + + + + + The 'xdg_toplevel_group' interface represents a group of toplevels that are + layered together at the same persistent z order. + + A toplevel can only be part of one group at a time. When a toplevel is added + to a group, it is removed from any previous group it was part of. + + + + + Destroys the toplevel group. This request may be sent at any time by the + client. + By destroying the object, all toplevels that were part of this group are + removed from the group and return to their default stacking behavior. + + A group is only fully destroyed if all clients that hold a reference to + it have destroyed their reference. + + + + + + Add a toplevel to this group. This request may be sent at any time by the + client. + The compositor must ensure that the toplevel is added to this group and + removed from any previous group it was part of. + + If a toplevel is destroyed, it must automatically be removed from its group + as well by the compositor. + + + + + + + Remove a toplevel from this group. This request may be sent at any time by the + client. + The compositor must ensure that the toplevel is removed from this group and + returns to its default stacking behavior. + If the specified toplevel is not part of this group, this request has no effect. + + + + + + + + + + + + Set a parent group for this group. This request may be sent at any time + by the client. + The compositor must ensure that all toplevels from this group are + persistently floating above the parent group. + The compositor must not change other behavior of the grouped toplevels + based on parent-child relationships, e.g. focus behavior or + keyboard interactivity. Toplevels in the parent group must still receive + focus as normal, with the only difference being that toplevels in the + child group are floating above toplevels in the parent group. + + If the specified parent group is the same as this group, an 'invalid' + error must be raised. + + If null is specified as the parent group, toplevels of this group + return to the default stacking behavior and the parent association + is removed. + + If a parent group is destroyed, the compositor must ensure that all + child groups of the destroyed group return to the default stacking + behavior, and that any parent association is automatically removed. + + Clients must not create circular parent-child relationships + between groups. If the compositor detects a circular chain, a + 'parent_cycle' error must be raised. + + + + + + + Obtain a handle for this group. + The compositor must ensure that the same handle always refers to the + same group. A handle must be unique to a group and should not be expected + to be persistent. + The handle can be used to import this group in other clients using the + 'get_group_from_handle' request of the 'xdg_toplevel_group_manager' + interface. + The compositor must reply with a 'handle' event in response to this request. + + + + + + This event is sent in response to the 'get_handle' request, and contains + a unique handle for this group. + + + + + +