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. + + + + + + +