Treeland decoration
Warning! This protocol is EXPERIMENTAL and under active development. It may change at any time, including in backward-incompatible ways, without incrementing the interface major version and without prior notice. No compatibility guarantees of any kind are provided. Clients and compositors must track the upstream definition in treeland-protocols and must not rely on the current interface names, requests, events, or semantics remaining stable across releases.
This protocol fine-tunes the compositor-drawn server-side decorations (SSD) of the client's own toplevel windows: corner radius, shadow, border, and titlebar visibility.
It is not standalone: the client must first negotiate SSD for the surface via xdg-decoration. The compositor applies these requests according to its own policy; in particular it may silently ignore a set_* request on a surface that has not negotiated SSD, or clamp an out-of-range value to a supported bound instead of raising an error.
This enables a "half-CSD, half-SSD" configuration: keep the compositor's border, corners and shadow while hiding its titlebar (set_titlebar_mode(hide)) and drawing a custom one.
Each property is opt-in: if a set_* request is never sent, the compositor applies its own default for that window's SSD. Sending a request takes ownership of that property for the lifetime of the context.
The terms "must", "must not", "should", and "may" in this document are to be interpreted as described in RFC 2119.
treeland_decoration_manager_v1
A global that creates per-surface SSD customization contexts.
Each surface may have at most one active decoration context. Attempting to create a second context for the same surface while one is already alive is a protocol error (already_used).
destroy()
Destroy the treeland_decoration_manager_v1 object. Existing treeland_decoration_context_v1 objects created through this manager are not affected and must be destroyed separately by the client.
get_decoration_context(id: new_id<treeland_decoration_context_v1>, surface: object<wl_surface>)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_decoration_context_v1> | new decoration context for the given surface |
| surface | object<wl_surface> | surface to decorate; must be owned by this client |
Create a treeland_decoration_context_v1 for the given surface. The surface must be owned by the requesting client; passing a surface owned by another client raises the invalid_surface protocol error.
The surface should hold a toplevel role (xdg_toplevel). The context itself may be created before SSD is negotiated; until SSD is negotiated via xdg-decoration, set_* requests on the context have no effect and are silently ignored by the compositor.
Creating a second context for the same surface while one is already alive is a protocol error (already_used).
error { already_used, invalid_surface }
Argument | Value | Description |
|---|---|---|
| already_used | 0 | a decoration context already exists for this surface |
| invalid_surface | 1 | the surface is not owned by the requesting client |
Error codes sent as protocol errors via wl_display.error.
treeland_decoration_context_v1
Controls the compositor-drawn server-side decorations for a single surface. Created by treeland_decoration_manager_v1.get_decoration_context.
All requests take effect immediately; there is no pending/commit model. The compositor applies each change as soon as it processes the request.
This object becomes inert when the underlying wl_surface is destroyed; requests on an inert context are silently ignored. The client should destroy this context before or immediately after destroying the associated wl_surface.
destroy()
Destroy the context. The compositor may revert any or all customized properties to its default behavior after this request.
set_corner_radius(radius: uint)
Argument | Type | Description |
|---|---|---|
| radius | uint | corner radius in pixels; 0 for square corners |
Override the compositor's corner rounding for this surface. Once set, the compositor no longer applies its global corner radius to this window.
A value of 0 requests square corners. The compositor applies this request according to its own policy and may clamp an out-of-range value to a supported bound.
Argument | Type | Description |
|---|---|---|
| radius | uint | shadow blur radius in pixels; 0 to disable shadow |
| offset_x | int | horizontal shadow offset in pixels; positive is right |
| offset_y | int | vertical shadow offset in pixels; positive is down |
| r | uint | shadow color red component [0, 255] |
| g | uint | shadow color green component [0, 255] |
| b | uint | shadow color blue component [0, 255] |
| a | uint | shadow color alpha component [0, 255] |
Override the compositor-drawn drop shadow for this surface.
When radius is 0 the shadow is disabled and all other arguments are ignored. Color components are unsigned in [0, 255]. The compositor applies this request according to its own policy and may clamp an out-of-range radius to a supported bound.
Argument | Type | Description |
|---|---|---|
| width | uint | border width in pixels; 0 to disable border |
| r | uint | border color red component [0, 255] |
| g | uint | border color green component [0, 255] |
| b | uint | border color blue component [0, 255] |
| a | uint | border color alpha component [0, 255] |
Override the compositor-drawn border for this surface.
When width is 0 the border is disabled and the color arguments are ignored. Color components are unsigned in [0, 255]. The compositor applies this request according to its own policy and may clamp an out-of-range width to a supported bound.
set_titlebar_mode(mode: uint<treeland_decoration_context_v1.titlebar_mode>)
Argument | Type | Description |
|---|---|---|
| mode | uint<treeland_decoration_context_v1.titlebar_mode> | titlebar visibility override |
Override whether the compositor draws a server-side titlebar for this surface, per the titlebar_mode enum. A mode value outside the titlebar_mode enum range is silently ignored; the current titlebar visibility is kept.
Hiding the titlebar leaves the rest of the SSD (border, corner radius, shadow) in effect; the client is then expected to draw its own titlebar inside the window content.
Argument | Value | Description |
|---|---|---|
| show | 0 | show the compositor titlebar (the SSD default) |
| hide | 1 | hide the compositor titlebar; the client is expected to draw its own titlebar inside the window content while keeping the rest of the SSD |
Controls whether the compositor-drawn (server-side) titlebar is visible, overriding the compositor's default. Hiding the titlebar while keeping the rest of the SSD is what produces a "half-CSD, half-SSD" configuration.
Compositor Support
Copyright
SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT