Treeland wallpaper shell
treeland_wallpaper_notifier_v1 接口提供关于合成器管理的壁纸源的可用性和生命周期的通知。
此接口纯粹是事件驱动的。客户端在壁纸源被添加、变为活动状态或被移除时接收事件，并可相应地更新其内部状态或用户界面。
destroy()
销毁此 treeland_wallpaper_notifier_v1 对象。
在由此对象创建的壁纸 surface 对象仍然存在时销毁已绑定的 treeland_wallpaper_notifier_v1 对象是非法的，将导致协议错误。
add(source_type: uint<treeland_wallpaper_notifier_v1.wallpaper_source_type>, file_source: string)
参数 | 类型 | 描述 |
|---|---|---|
| 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 |
当新的壁纸源被添加或变为活动状态时，合成器发送此事件。
source_type 参数描述壁纸源的类型。 file_source 参数的含义取决于报告的 source_type。
remove(file_source: string)
参数 | 类型 | 描述 |
|---|---|---|
| file_source | string | The file path or identifier of the wallpaper source |
此事件指示由 file_source 标识的壁纸源不再可用。
收到此事件后，客户端应丢弃与该壁纸源关联的任何内部状态，且不得再引用它。
treeland_wallpaper_shell_v1 接口是由合成器暴露的全局对象，允许客户端将壁纸角色分配给 wl_surface 并创建壁纸 surface 对象。
壁纸 surface 表示旨在作为桌面壁纸显示的内容，如静态图像或动态媒体源，并与一个 wl_surface 关联。
此接口遵循其他 Wayland 协议使用的 shell 模式：将特定角色分配给 wl_surface 并管理壁纸 surface 的生命周期和行为。
此接口是单例的。在同一时间，最多只有一个客户端可以绑定到 treeland_wallpaper_shell_v1。
destroy()
销毁此 treeland_wallpaper_shell_v1 对象。
在由此对象创建的 treeland_wallpaper_surface_v1 对象仍然存在时销毁已绑定的 treeland_wallpaper_shell_v1 对象是非法的，将导致协议错误。
get_treeland_wallpaper_surface(id: new_id<treeland_wallpaper_surface_v1>, surface: object<wl_surface>, file_source: string)
参数 | 类型 | 描述 |
|---|---|---|
| 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 |
创建一个 treeland_wallpaper_surface_v1 对象并将壁纸角色分配给给定的 wl_surface。
提供的 wl_surface 必须尚未有角色，在用作壁纸 surface 期间，不得分配任何其他角色。
file_source 参数指定初始壁纸源标识符。其解释取决于合成器选择的壁纸源类型。
treeland_wallpaper_surface_v1 接口控制壁纸 surface 的行为。
壁纸 surface 绑定到一个 wl_surface，并定义该 surface 应如何调整大小、定位以及与合成器的壁纸管理逻辑同步。
destroy()
销毁壁纸 surface 对象并释放其与底层 wl_surface 的关联。
调用此请求后，壁纸 surface 对象变为无效，不得再次使用。
此请求应仅在客户端打算永久停止使用壁纸 surface 时发送，例如客户端正在关闭时或收到此 surface 的 treeland_wallpaper_produce_v1.removed 事件后。
source_failed(error: uint<treeland_wallpaper_surface_v1.error>)
参数 | 类型 | 描述 |
|---|---|---|
| error | uint<treeland_wallpaper_surface_v1.error> | The error code indicating the failure reason |
向合成器报告客户端侧的壁纸相关操作已失败。
当客户端无法打开、加载或以其他方式处理配置的壁纸源时，可以发送此请求。 合成器可以将此信息用于诊断、策略决策或调整内部状态。
可能的错误值包括：
position(position: fixed)
参数 | 类型 | 描述 |
|---|---|---|
| position | fixed | Position or progress value in fixed-point format |
此事件提供与壁纸关联的位置值。
位置值的语义由合成器定义。 它可以表示滚动偏移、动画进度或播放位置。 该值以定点数 [0, 1.0] 表示。
pause()
此事件指示客户端暂停壁纸更新或动画。
收到此事件后，客户端应停止推进任何基于时间或动画的壁纸内容，直到收到 play 事件。
set_playback_rate(rate: fixed)
参数 | 类型 | 描述 |
|---|---|---|
| rate | fixed | Playback rate multiplier |
设置壁纸内容的播放速度。
速率为 1.0 表示正常速度。 速率为 0.0 表示暂停状态。
slow_down(duration: uint)
参数 | 类型 | 描述 |
|---|---|---|
| duration | uint | Duration in milliseconds over which the slowdown occurs |
此事件指示客户端逐步降低壁纸内容的播放或动画更新速率，直到完全停止。
减速应是平滑连续的，而非突然的。
duration 参数指定减速应持续的时间（以毫秒为单位）。 经过此持续时间后，客户端应认为壁纸已暂停。
持续时间为 0 表示客户端应立即暂停。
error { invalid_source, permission_denied }
参数 | 值 | 描述 |
|---|---|---|
| invalid_source | 1 | 指定的壁纸源无效、不受支持或加载失败 |
| permission_denied | 2 | 打开指定壁纸源时权限被拒绝 |
合成器支持
Copyright
SPDX-FileCopyrightText: 2025 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT