Treeland wallpaper manager
treeland_wallpaper_manager_v1
The treeland_wallpaper_manager_v1 interface is a global object used to create wallpaper objects for specific outputs.
destroy()
Destroy this treeland_wallpaper_manager_v1 object.
Destroying a bound treeland_wallpaper_manager_v1 object while there are wallpapers still alive created by this treeland_wallpaper_manager_v1 object instance is illegal and will result in a protocol error.
get_treeland_wallpaper(id: new_id<treeland_wallpaper_v1>, output: object<wl_output>, surface: object<wl_surface>)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_wallpaper_v1> | |
| output | object<wl_output> | |
| surface | object<wl_surface>allow null | The wl_surface associated with this wallpaper, or null to unset it |
Creates a treeland_wallpaper_v1 object bound to the specified wl_output.
The compositor may enforce that only one wallpaper exists for a given (output, role) combination.
When a surface is associated, the compositor will track the workspace the surface belongs to. Whenever the workspace changes, the compositor may notify the client of the current wallpaper file path used by that workspace.
Note: The treeland_wallpaper_v1 object must be destroyed before the associated wl_surface is destroyed.
treeland_wallpaper_v1
The treeland_wallpaper_v1 interface represents a wallpaper instance created by the compositor for a specific output, role.
The wallpaper source provided by the client is stored and managed on the compositor side. Once a wallpaper source has been set, the compositor may cache, reuse, or persist the source independently of the client.
destroy()
Destroys the treeland_wallpaper_v1 object and releases all resources associated with it on the compositor side.
After calling this request, the client must not use the wallpaper object anymore.
set_image_source(file_source: string, role: uint)
Argument | Type | Description |
|---|---|---|
| file_source | string | Path to the image file to be used as the wallpaper |
| role | uint | wallpaper role |
Sets an image as the wallpaper source, apply to the current wl_output and the active workspace. except for lockscreen wallpapers, only one wallpaper can be set per wl_output. Supported formats:
- JPG / JPEG (Joint Photographic Experts Group)
The compositor will attempt to load and display the specified image file. If the file cannot be accessed, decoded, or is in an unsupported format, the compositor will emit a failed event with an appropriate error code.
Access Control: This protocol accepts file_source such as /usr/share/wallpapers/xxx or /var/cache/wallpapers/xxxx provided by the client. the compositor will perform file verification.
set_video_source(file_source: string, role: uint)
Argument | Type | Description |
|---|---|---|
| file_source | string | Path to the video file to be used as the wallpaper |
| role | uint | wallpaper role |
Sets a video file as the wallpaper source, apply to the current wl_output and the active workspace. except for lockscreen wallpapers, only one wallpaper can be set per wl_output. Supported formats:
- MP4
- AVI
- MOV
The compositor is responsible for decoding and presenting the video. Playback behavior such as looping, synchronization, and performance characteristics are compositor-defined.
If the video source cannot be opened or decoded, a failed event will be emitted.
Access Control: This protocol accepts file_source such as /usr/share/wallpapers/xxx or /var/cache/wallpapers/xxxx provided by the client. the compositor will perform file verification.
failed(file_source: string, error: uint<treeland_wallpaper_v1.error>)
Argument | Type | Description |
|---|---|---|
| file_source | string | Path to the file to be used as the wallpaper |
| error | uint<treeland_wallpaper_v1.error> | The error code indicating the failure reason |
This event is emitted when a wallpaper-related request fails.
The failure may occur during source loading, validation, or runtime setup. The error code provides additional information about the cause of the failure.
Possible error values include:
changed(role: uint<treeland_wallpaper_v1.wallpaper_role>, source_type: uint<treeland_wallpaper_v1.wallpaper_source_type>, file_source: string)
Argument | Type | Description |
|---|---|---|
| role | uint<treeland_wallpaper_v1.wallpaper_role> | |
| source_type | uint<treeland_wallpaper_v1.wallpaper_source_type> | The type of the current wallpaper source |
| file_source | string | The file path of the current wallpaper source |
This event is emitted by the compositor to notify the client that the wallpaper source associated with this treeland_wallpaper_v1 object has changed.
The event may be emitted during initial object setup or when the wallpaper is changed due to external factors not initiated by this client, such as compositor policy decisions, workspace switches (except for lockscreen wallpapers) that affect the active wallpaper, or other system components.
Because the desktop wallpaper is designed to support different workspaces. if the client is a surface, changes to its displayed workspace will also send (reference set_reference_surface).
The event provides the current wallpaper source type and the corresponding source file path.
error { already_used, invalid_source, permission_denied }
Argument | Value | Description |
|---|---|---|
| already_used | 0 | wallpaper file has already been used and is cached on the wallpaper side |
| 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 |
wallpaper_role { desktop, lockscreen }
Argument | Value | Description |
|---|---|---|
| desktop | 0x1 | Wallpaper for the desktop environment |
| lockscreen | 0x2 | Wallpaper for the lock screen |
Compositor Support
Copyright
SPDX-FileCopyrightText: 2025 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT