Treeland wallpaper shell
treeland_wallpaper_notifier_v1
The treeland_wallpaper_notifier_v1 interface provides notifications about the availability and lifetime of wallpaper sources managed by the compositor.
This interface is purely event-driven. Clients receive events when wallpaper sources are added, become active, or are removed, and may update their internal state or user interface accordingly.
destroy()
Destroys this treeland_wallpaper_notifier_v1 object.
Destroying a bound treeland_wallpaper_notifier_v1 object while wallpaper surface objects created from it are still alive is illegal and will result in a protocol error.
add(source_type: uint<treeland_wallpaper_notifier_v1.wallpaper_source_type>, file_source: string)
Argument | Type | Description |
|---|---|---|
| source_type | uint<treeland_wallpaper_notifier_v1.wallpaper_source_type> | The type of the wallpaper source |
| file_source | string | The file path or identifier of the wallpaper source |
This event is sent by the compositor when a new wallpaper source is added or becomes active.
The source_type argument describes the type of the wallpaper source. The meaning of the file_source argument depends on the reported source_type.
remove(file_source: string)
Argument | Type | Description |
|---|---|---|
| file_source | string | The file path or identifier of the wallpaper source |
This event indicates that the wallpaper source identified by file_source is no longer available.
After receiving this event, the client should discard any internal state associated with the wallpaper source and must not reference it anymore.
treeland_wallpaper_shell_v1
The treeland_wallpaper_shell_v1 interface is a global object exposed by the compositor that allows a client to assign the wallpaper role to a wl_surface and create wallpaper surface objects.
A wallpaper surface represents content intended to be displayed as the desktop wallpaper, such as a static image or a dynamic media source, and is associated with exactly one wl_surface.
This interface follows the shell pattern used by other Wayland protocols: it assigns a specific role to a wl_surface and manages the lifetime and behavior of wallpaper surfaces.
This interface is a singleton. At most one client may bind to treeland_wallpaper_shell_v1 at any given time.
destroy()
Destroys this treeland_wallpaper_shell_v1 object.
Destroying a bound treeland_wallpaper_shell_v1 object while there are still treeland_wallpaper_surface_v1 objects created from it is illegal and will result in a protocol error.
get_treeland_wallpaper_surface(id: new_id<treeland_wallpaper_surface_v1>, surface: object<wl_surface>, file_source: string)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_wallpaper_surface_v1> | The newly created wallpaper surface object |
| surface | object<wl_surface> | The wl_surface to which the wallpaper role is assigned |
| file_source | string | The initial wallpaper source identifier |
Creates a treeland_wallpaper_surface_v1 object and assigns the wallpaper role to the given wl_surface.
The provided wl_surface must not already have a role, and while it is used as a wallpaper surface, it must not be assigned any other role.
The file_source argument specifies the initial wallpaper source identifier. Its interpretation depends on the wallpaper source type selected by the compositor.
treeland_wallpaper_surface_v1
The treeland_wallpaper_surface_v1 interface controls the behavior of a wallpaper surface.
A wallpaper surface is bound to exactly one wl_surface and defines how that surface should be sized, positioned, and synchronized with the compositor's wallpaper management logic.
destroy()
Destroy the wallpaper surface object and release its association with the underlying wl_surface.
After calling this request, the wallpaper surface object becomes invalid and must not be used again.
This request should only be sent when the client intends to permanently stop using the wallpaper surface, such as when the client is shutting down or after receiving the treeland_wallpaper_produce_v1.removed event for this surface.
source_failed(error: uint<treeland_wallpaper_surface_v1.error>)
Argument | Type | Description |
|---|---|---|
| error | uint<treeland_wallpaper_surface_v1.error> | The error code indicating the failure reason |
Reports to the compositor that a wallpaper-related operation has failed on the client side.
This request may be sent by the client when it fails to open, load, or otherwise process the configured wallpaper source. The compositor may use this information for diagnostics, policy decisions, or to adjust internal state.
Possible error values include:
position(position: fixed)
Argument | Type | Description |
|---|---|---|
| position | fixed | Position or progress value in fixed-point format |
This event provides a position value associated with the wallpaper.
The semantic meaning of the position value is compositor-defined. It may represent a scroll offset, animation progress, or playback position. The value is expressed as a fixed-point number[0, 1.0].
pause()
This event instructs the client to pause wallpaper updates or animations.
After receiving this event, the client should stop advancing any time-based or animated wallpaper content until a play event is received.
set_playback_rate(rate: fixed)
Argument | Type | Description |
|---|---|---|
| rate | fixed | Playback rate multiplier |
Sets the playback speed of the wallpaper content.
A rate of 1.0 represents normal speed. A rate of 0.0 represents a paused state.
play()
This event instructs the client to resume wallpaper updates or animations after a pause.
slow_down(duration: uint)
Argument | Type | Description |
|---|---|---|
| duration | uint | Duration in milliseconds over which the slowdown occurs |
This event instructs the client to progressively reduce the playback or animation update rate of the wallpaper content until it comes to a complete stop.
The slowdown should be smooth and continuous rather than abrupt.
The duration argument specifies the amount of time, in milliseconds, over which the slowdown should occur. After this duration has elapsed, the client should consider the wallpaper paused.
A duration of 0 means the client should pause immediately.
error { invalid_source, permission_denied }
Argument | Value | Description |
|---|---|---|
| invalid_source | 1 | The specified wallpaper source is invalid, unsupported, or failed to load. |
| permission_denied | 2 | Permission denied when opening the specified wallpaper source |
Compositor Support
Copyright
SPDX-FileCopyrightText: 2025 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT