Treeland appearance manager
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 allows privileged clients such as the desktop control center to configure user-level appearance settings managed by the compositor, including cursor theme and size, fonts, and visual theming (icon theme, accent color, window opacity, color scheme, titlebar height, and corner radius).
This protocol is privileged. Binding it without compositor-level authorization may result in requests being silently ignored or the connection being terminated.
The terms "must", "must not", "should", and "may" in this document are to be interpreted as described in RFC 2119.
treeland_appearance_manager_v1
A singleton privileged global for modifying user-level appearance settings of the current user. These settings are shared by all windows and clients of the user rather than being per-window. Settings take effect immediately when a set_* request is sent. The compositor applies each change and broadcasts the new value to all clients bound to treeland_appearance_v1.
destroy()
Destroy the treeland_appearance_manager_v1 object.
set_cursor_theme(name: string)
Argument | Type | Description |
|---|---|---|
| name | string | cursor theme name as recognized by the cursor theme subsystem |
Set the cursor theme name. The compositor applies the change immediately and broadcasts a cursor_theme event to all active appearance observers. If the requested theme is empty or not installed, the compositor falls back to a default cursor theme.
Set the cursor size in pixels. Width and height are specified independently to accommodate hardware cursor planes that support non-square sizes. The compositor applies the change immediately and broadcasts a cursor_size event to all active appearance observers. Values of 0 or exceeding compositor limits are clamped to the minimum or maximum supported size.
set_font(font_name: string)
Argument | Type | Description |
|---|---|---|
| font_name | string | font family name |
Set the proportional font family. The compositor applies the change immediately and broadcasts a font event to all active appearance observers. If the requested font family is empty or not installed, the compositor falls back to a default font.
set_monospace_font(font_name: string)
Argument | Type | Description |
|---|---|---|
| font_name | string | monospace font family name |
Set the monospace font family. The compositor applies the change immediately and broadcasts a monospace_font event to all active appearance observers. If the requested font family is empty or not installed, the compositor falls back to a default monospace font.
set_font_size(size: uint)
Argument | Type | Description |
|---|---|---|
| size | uint | font size in points multiplied by 10 |
Set the base font size. The value is in points multiplied by 10, so 105 means 10.5 points. The compositor applies the change immediately and broadcasts a font_size event to all active appearance observers. A size of 0 or exceeding compositor limits is clamped to the minimum or maximum supported size.
set_icon_theme(theme_name: string)
Argument | Type | Description |
|---|---|---|
| theme_name | string | icon theme name |
Set the icon theme name. The compositor applies the change immediately and broadcasts an icon_theme event to all active appearance observers. If the specified theme is empty or not installed, the compositor falls back to a default icon theme or ignores the change.
Argument | Type | Description |
|---|---|---|
| r | uint | accent color red component [0, 255] |
| g | uint | accent color green component [0, 255] |
| b | uint | accent color blue component [0, 255] |
Set the accent color used for window decorations, focus indicators, and compositor UI elements.
Color components are unsigned values in the range [0, 255]. The compositor handles out-of-range values according to its own policy and may clamp a component to a supported bound.
The compositor applies the change immediately and broadcasts an accent_color event to all active appearance observers.
set_window_opacity(opacity: fixed)
Argument | Type | Description |
|---|---|---|
| opacity | fixed | window background opacity [0.0, 1.0] |
Set the global window background opacity as a fixed-point value in the range [0.0, 1.0]. A value of 1.0 means fully opaque; 0.0 means fully transparent. The compositor handles out-of-range values according to its own policy and may clamp a value to a supported bound.
The compositor applies the change immediately and broadcasts a window_opacity event to all active appearance observers.
set_color_scheme(scheme: uint<treeland_appearance_manager_v1.color_scheme>)
Argument | Type | Description |
|---|---|---|
| scheme | uint<treeland_appearance_manager_v1.color_scheme> | color scheme hint to apply |
Set the color scheme hint. Values outside the color_scheme enum range are silently ignored; the current color scheme is kept unchanged.
The compositor applies the change immediately, updates server-side decorations, and broadcasts a color_scheme event to all active appearance observers so that clients can restyle their self-drawn components.
set_titlebar_height(height: uint)
Argument | Type | Description |
|---|---|---|
| height | uint | titlebar height in pixels; 0 to hide titlebar |
Set the height of the compositor-drawn titlebar in pixels. A value of 0 hides the compositor titlebar. The compositor handles out-of-range values according to its own policy and may clamp a value to a supported bound.
The compositor applies the change immediately and broadcasts a titlebar_height event to all active appearance observers.
set_corner_radius(radius: uint)
Argument | Type | Description |
|---|---|---|
| radius | uint | corner radius in pixels; 0 for square corners |
Set the global default corner radius applied to window decorations in pixels. This is the default for all windows; individual windows may override it via treeland_decoration_context_v1.set_corner_radius. A value of 0 specifies square (unrounded) corners. The compositor handles out-of-range values according to its own policy and may clamp a value to a supported bound.
The compositor applies the change immediately and broadcasts a corner_radius event to all active appearance observers.
A user-level hint for the preferred color scheme. Clients should use this value to style their self-drawn widgets and UI elements accordingly. The compositor also applies this hint to server-side decorations. This is semantically equivalent to org.freedesktop.appearance color-scheme and the CSS prefers-color-scheme media feature.
This enum mirrors treeland_appearance_v1.color_scheme (in the read-only treeland-appearance-unstable-v1 protocol): the entry names and values are identical and must stay in sync. Any new value must be added to both at once.
Compositor Support
Copyright
SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT