Treeland appearance

query and observe user-level appearance settings

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 general applications to query and receive live notifications for user-level appearance settings managed by the compositor, including cursor theme and size, fonts (proportional, monospace, size), and visual appearance (icon theme, accent color, window opacity, color scheme, titlebar height, and corner radius).

Any client may bind this interface. The compositor pushes the current value of every setting immediately after the client binds this global, and broadcasts events to all bound clients whenever a setting changes.

The terms "must", "must not", "should", and "may" in this document are to be interpreted as described in RFC 2119.

user-level appearance settings observer

A singleton global for observing 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. Each bound client receives events reporting the initial values of all settings immediately after binding, and subsequent events whenever any setting changes.

destroy()
destroy the appearance observer object

Destroy the treeland_appearance_v1 object. The compositor will no longer send events on this object after this request.

cursor_theme(name: string)
Argument
Type
Description
namestring
current cursor theme name
cursor theme has changed

Emitted by the compositor when the cursor theme changes. Also emitted immediately after binding to report the current theme.

cursor_size(width: uint, height: uint)
Argument
Type
Description
widthuint
current cursor width in pixels
heightuint
current cursor height in pixels
cursor size has changed

Emitted by the compositor when the cursor size changes. Also emitted immediately after binding to report the current size in pixels. Width and height may differ on hardware that supports non-square cursor planes.

font(font_name: string)
Argument
Type
Description
font_namestring
current proportional font family name
proportional font has changed

Emitted when the proportional font family changes. Also emitted immediately after binding to report the current font.

monospace_font(font_name: string)
Argument
Type
Description
font_namestring
current monospace font family name
monospace font has changed

Emitted when the monospace font family changes. Also emitted immediately after binding to report the current font.

font_size(size: uint)
Argument
Type
Description
sizeuint
current font size in points multiplied by 10
font size has changed

Emitted when the base font size changes. Also emitted immediately after binding to report the current size in points multiplied by 10.

icon_theme(theme_name: string)
Argument
Type
Description
theme_namestring
current icon theme name
icon theme has changed

Emitted when the icon theme changes. Also emitted immediately after binding to report the current theme.

accent_color(r: uint, g: uint, b: uint)
Argument
Type
Description
ruint
current accent color red component [0, 255]
guint
current accent color green component [0, 255]
buint
current accent color blue component [0, 255]
accent color has changed

Emitted when the accent color changes. Also emitted immediately after binding to report the current color. Color components are unsigned values in the range [0, 255].

window_opacity(opacity: fixed)
Argument
Type
Description
opacityfixed
current window background opacity [0.0, 1.0]
global window opacity has changed

Emitted when the global window background opacity changes. Also emitted immediately after binding to report the current value. The value is a fixed-point value in the range [0.0, 1.0].

Argument
Type
Description
schemeuint<treeland_appearance_v1.color_scheme>
current color scheme hint
color scheme hint has changed

Emitted when the color scheme hint changes. Also emitted immediately after binding to report the current scheme. Clients should restyle their self-drawn components whenever this event is received.

titlebar_height(height: uint)
Argument
Type
Description
heightuint
current compositor titlebar height in pixels
compositor titlebar height has changed

Emitted when the compositor titlebar height changes. Also emitted immediately after binding to report the current value in pixels.

corner_radius(radius: uint)
Argument
Type
Description
radiusuint
current global corner radius in pixels
global window corner radius has changed

Emitted when the global default corner radius changes. Also emitted immediately after binding to report the current value in pixels.

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_manager_v1.color_scheme (in the privileged treeland-appearance-manager-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