From e40bd38bc55cdde67b13a82cc4c47d6550f4a66b Mon Sep 17 00:00:00 2001 From: Matthias Klumpp Date: Fri, 12 Dec 2025 18:55:20 +0100 Subject: [PATCH] Add xdg-toplevel-layers for persistent toplevel layering 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-layers/README | 4 + .../xdg-toplevel-layers-v1.xml | 143 ++++++++++++++++++ 3 files changed, 148 insertions(+) create mode 100644 staging/xdg-toplevel-layers/README create mode 100644 staging/xdg-toplevel-layers/xdg-toplevel-layers-v1.xml diff --git a/meson.build b/meson.build index 2fe65b9..f4d630a 100644 --- a/meson.build +++ b/meson.build @@ -73,6 +73,7 @@ staging_protocols = { 'xdg-system-bell': ['v1'], 'xdg-toplevel-drag': ['v1'], 'xdg-toplevel-icon': ['v1'], + 'xdg-toplevel-layers': ['v1'], 'xdg-toplevel-tag': ['v1'], 'xwayland-shell': ['v1'], } diff --git a/staging/xdg-toplevel-layers/README b/staging/xdg-toplevel-layers/README new file mode 100644 index 0000000..14fa2aa --- /dev/null +++ b/staging/xdg-toplevel-layers/README @@ -0,0 +1,4 @@ +Toplevel Layers protocol + +Maintainers: +Matthias Klumpp (@mak) diff --git a/staging/xdg-toplevel-layers/xdg-toplevel-layers-v1.xml b/staging/xdg-toplevel-layers/xdg-toplevel-layers-v1.xml new file mode 100644 index 0000000..74284f0 --- /dev/null +++ b/staging/xdg-toplevel-layers/xdg-toplevel-layers-v1.xml @@ -0,0 +1,143 @@ + + + + + Copyright © 2024-2025 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 current have focus or not when using + a stacking window manager. + + 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_layer_manager' interface defines base requests for obtaining and + managing layered items for a client. + + + + + This has no effect other than to destroy the xdg_toplevel_layer_manager object. + + + + + + Create a new layer item from an 'xdg_toplevel'. + The resulting wrapper object can then be used to set a z-order + relative to other layerable items. + + + + + + + + Create a new layer item from an imported toplevel that was previously + exported by another client using the xdg-foreign protocol. + The resulting wrapper object can then be used to set a z-order + relative to other layerable items. + + + + + + + + + The layer item object is an opaque descriptor for a positionable + element, such as a toplevel window. + It currently can only be created from an 'xdg_toplevel' or imported + toplevel. + + + + + Destroys the layer item. This request may be sent at any time by the + client. + By destroying the object, the respective toplevel represented by this + item must lose any attached state, like its layer index, and behave + like a regular toplevel. + + + + + + + + + + Request a preferred permanent Z position for this item relative to + another layer item. + This state is double-buffered and is applied on the next + wl_surface.commit of the surface represented by 'item'. + + This function associates a "layer index" with the item, with all + item surfaces assumed to be positioned at a layer with index 0 by + default. + Item surfaces that are positioned in a layer with a higher index + permanently float above items with a lower index. Items with a + lower layer index sink below items with a higher index. + When (de)activated, items must stay in their layers and do not + change order like they normally would in a stacking window manager + paradigm. + + All indices are relative to the given reference item. For example, + to position an item A two layers above the reference item, the client + would call this function with the reference item and a layer_index + of 2. This keeps the current item permanently above the reference item. + If the client then calls this function on an item B with the same reference + item, but a layer_index of 1, item B will be positioned permanently above + the reference item, but also permanently below item A. + + If a negative layer index is given, this item will permanently sink + below the reference icon. Otherwise the same semantics as with positive + indices apply for negative ones. + + Items with the same layer index respective to the reference surface + are subject to compositor policy, which usually means they will obe + user interaction and raise above or sink below each other depending on + which surface is currently activated. + + If the reference item is the same item as this item (so, using itself as + reference) an 'invalid' error must be raised. + + + + + + +