xdg_decoration_v1
xdg_decoration_manager_v1
This interface allows a compositor to announce support for one or more types of decorations.
Window decorations are a set of window controls as deemed appropriate by the party managing them, such as user interface components used to move, resize and change a toplevel surface's state, drop shadows, and other visual styling around a toplevel.
A client can use this protocol to request being decorated by a supporting compositor.
If compositor and client do not negotiate the use of any type of decoration using this protocol, clients continue to self-decorate as they see fit.
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.
destroy()
Destroy the decoration manager. This doesn't destroy objects created with the manager.
get_toplevel_decoration(id: new_id<xdg_toplevel_decoration_v1>, toplevel: object<xdg_toplevel>)
Argument | Type | Description |
|---|---|---|
| id | new_id<xdg_toplevel_decoration_v1> | |
| toplevel | object<xdg_toplevel> |
Create a new decoration object associated with the given toplevel.
Creating an xdg_toplevel_decoration from an xdg_toplevel which has a buffer attached is a client error.
xdg_toplevel_decoration_v1
The decoration object allows the compositor to toggle server-side toplevel decorations for a toplevel surface. The client can request to switch to another mode.
The xdg_toplevel_decoration object must be destroyed before its xdg_toplevel.
destroy()
Destroys this object, and switches back to a mode without any server-side decorations at the next commit. The client will draw decorations as it sees fit.
The xdg_toplevel_decoration object must be destroyed before its xdg_toplevel.
set_decorations(decoration_drawer: uint<xdg_toplevel_decoration_v1.mode>, capabilities: uint<xdg_toplevel_decoration_v1.decorations>)
Argument | Type | Description |
|---|---|---|
| decoration_drawer | uint<xdg_toplevel_decoration_v1.mode> | who should draw decorations |
| capabilities | uint<xdg_toplevel_decoration_v1.decorations> | combination of decorations values |
Set the toplevel surface decoration mode. This informs the compositor that the client would like to be drawn in the provided decoration mode, and if specified, which decorations should be drawn by the compositor.
If the decoration_drawer argument is "client", the capabilities argument is used to hint to the compositor which decorations are drawn by the client.
If the decoration_drawer argument is "server", the capabilities argument must only contain valid arguments (sent in a previous decoration_capabilities event) or zero, and the compositor will draw those decorations on behalf of the client.
Clients whose decoration mode depend on the xdg_toplevel state may send a set_decorations request in response to an xdg_surface.configure event and wait for the next xdg_surface.configure event to prevent unwanted state. Such clients are responsible for preventing configure loops and must make sure not to send multiple successive set_decorations requests with the same decoration mode.
If an invalid or unknown mode is supplied by the client, the invalid_mode protocol error is raised by the compositor.
decoration_capabilities(supported_decoration_drawer: uint<xdg_toplevel_decoration_v1.mode>, decorations: uint<xdg_toplevel_decoration_v1.decorations>)
Argument | Type | Description |
|---|---|---|
| supported_decoration_drawer | uint<xdg_toplevel_decoration_v1.mode> | non-zero if server supports decorations drawn by the server |
| decorations | uint<xdg_toplevel_decoration_v1.decorations> | combination of decorations values |
This event will be always be sent once with the "client" supported_decoration_drawer argument, and will be accompanied by a second decoration_capabilities event with a "server" supported_decoration_drawer argument, if supported by the compositor.
If this event is ever sent without an accompanying "server" event type, including after object creation, the client must not request server-drawn decorations, nor commit any new state using server-drawn decorations, otherwise it will raise the invalid_mode error.
See the set_decorations request for how to signal which decoration mode the client would like, and which decorations the client would like to have drawn for it.
This event may be sent several times over the lifetime of xdg_toplevel_decoration object, each time (including the initial event) with an xdg_surface::configure event; clients must re-configure themselves with the new described modes before committing their state, otherwise an invalid_mode error is raised by the compositor.
error { unconfigured_buffer, already_constructed, orphaned, invalid_mode }
Argument | Value | Description |
|---|---|---|
| unconfigured_buffer | 0 | xdg_toplevel has a buffer attached before configure |
| already_constructed | 1 | xdg_toplevel already has a decoration object |
| orphaned | 2 | xdg_toplevel destroyed before the decoration object |
| invalid_mode | 3 | invalid mode |
mode { client_side, server_side }
Argument | Value | Description |
|---|---|---|
| client_side | 1 | no server-side toplevel decorations |
| server_side | 2 | server-side toplevel decorations |
These values describe toplevel decoration modes.
decorations { zero, drop_shadows, any_decorations }
Argument | Value | Description |
|---|---|---|
| zero | 0x0 | a zeroed bitfield |
| drop_shadows | 0x1 | drop shadows |
| any_decorations | 0x2147483648 | any type of decorations |
Compositor Support
Copyright
Copyright © 2018 Simon Ser Copyright © 2025 Dallas Strouse Copyright © 2025 Neal Gompa
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.