Treeland appearance manager

user-level appearance configuration management

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.

user-level appearance settings manager

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 appearance manager object

Destroy the treeland_appearance_manager_v1 object.

set_cursor_theme(name: string)
Argument
Type
Description
namestring
cursor theme name as recognized by the cursor theme subsystem
set the cursor theme

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_cursor_size(width: uint, height: uint)
Argument
Type
Description
widthuint
cursor width in pixels
heightuint
cursor height in pixels
set the cursor size

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_namestring
font family name
set the proportional font

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_namestring
monospace font family name
set the monospace font

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
sizeuint
font size in points multiplied by 10
set the font size

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_namestring
icon theme name
set the icon theme

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.

set_accent_color(r: uint, g: uint, b: uint)
Argument
Type
Description
ruint
accent color red component [0, 255]
guint
accent color green component [0, 255]
buint
accent color blue component [0, 255]
set the accent color

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
opacityfixed
window background opacity [0.0, 1.0]
set the global window background opacity

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.

Argument
Type
Description
schemeuint<treeland_appearance_manager_v1.color_scheme>
color scheme hint to apply
set the color scheme hint

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
heightuint
titlebar height in pixels; 0 to hide titlebar
set the compositor titlebar height

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
radiusuint
corner radius in pixels; 0 for square corners
set the global window corner radius

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.

color_scheme { light, dark } 
Argument
Value
Description
light0
prefer light color scheme
dark1
prefer dark color scheme
user-level color scheme hint

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

No compositor support found

SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT