Treeland appearance
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.
treeland_appearance_v1
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 treeland_appearance_v1 object. The compositor will no longer send events on this object after this request.
cursor_theme(name: string)
Argument | Type | Description |
|---|---|---|
| name | string | current cursor theme name |
Emitted by the compositor when the cursor theme changes. Also emitted immediately after binding to report the current theme.
Argument | Type | Description |
|---|---|---|
| width | uint | current cursor width in pixels |
| height | uint | current cursor height in pixels |
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_name | string | current proportional font family name |
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_name | string | current monospace font family name |
Emitted when the monospace font family changes. Also emitted immediately after binding to report the current font.
font_size(size: uint)
Argument | Type | Description |
|---|---|---|
| size | uint | current font size in points multiplied by 10 |
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_name | string | current icon theme name |
Emitted when the icon theme changes. Also emitted immediately after binding to report the current theme.
Argument | Type | Description |
|---|---|---|
| r | uint | current accent color red component [0, 255] |
| g | uint | current accent color green component [0, 255] |
| b | uint | current accent color blue component [0, 255] |
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 |
|---|---|---|
| opacity | fixed | current window background opacity [0.0, 1.0] |
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].
color_scheme(scheme: uint<treeland_appearance_v1.color_scheme>)
Argument | Type | Description |
|---|---|---|
| scheme | uint<treeland_appearance_v1.color_scheme> | current color scheme hint |
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 |
|---|---|---|
| height | uint | current compositor titlebar height in pixels |
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 |
|---|---|---|
| radius | uint | current global corner radius in pixels |
Emitted when the global default corner radius changes. Also emitted immediately after binding to report the current value in pixels.
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
Copyright
SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT