xdg_toplevel_groups_v1
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.
xdg_toplevel_group_manager_v1
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.
destroy()
This has no effect other than to destroy the 'xdg_toplevel_group_manager' object.
get_group(id: new_id<xdg_toplevel_group_v1>)
Argument | Type | Description |
|---|---|---|
| id | new_id<xdg_toplevel_group_v1> |
Create a new toplevel group.
get_group_from_handle(id: new_id<xdg_toplevel_group_v1>, handle: string)
Argument | Type | Description |
|---|---|---|
| id | new_id<xdg_toplevel_group_v1> | |
| handle | string | the handle of a 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.
xdg_toplevel_group_v1
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.
destroy()
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_toplevel(toplevel: object<xdg_toplevel>)
Argument | Type | Description |
|---|---|---|
| toplevel | object<xdg_toplevel> | the toplevel to add |
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_toplevel(toplevel: object<xdg_toplevel>)
Argument | Type | Description |
|---|---|---|
| toplevel | object<xdg_toplevel> | the toplevel to remove |
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_parent(parent_group: object<xdg_toplevel_group_v1>)
Argument | Type | Description |
|---|---|---|
| parent_group | object<xdg_toplevel_group_v1>allow null | the parent group |
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.
get_handle()
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.
handle(handle: string)
Argument | Type | Description |
|---|---|---|
| handle | string | the handle for this group |
This event is sent in response to the 'get_handle' request, and contains a unique handle for this group.
error { invalid, parent_cycle }
Argument | Value | Description |
|---|---|---|
| invalid | 0 | the request was invalid |
| parent_cycle | 1 | a circular parent chain was detected |
Compositor Support
Copyright
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.