diff --git a/CMakeLists.txt b/CMakeLists.txt index ed62b63..3d4291b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -13,7 +13,6 @@ include(CMakePackageConfigHelpers) # Public protocol XML files (for general application developers) set(TREELAND_PROTOCOL_XML_FILES - public/treeland-dde-shell-v1.xml public/treeland-window-transition-unstable-v1.xml public/treeland-appearance-unstable-v1.xml public/treeland-decoration-unstable-v1.xml @@ -21,17 +20,20 @@ set(TREELAND_PROTOCOL_XML_FILES # DDE component protocol XML files set(TREELAND_PROTOCOL_DDE_XML_FILES + dde/treeland-dde-shell-unstable-v2.xml dde/treeland-foreign-toplevel-manager-unstable-v2.xml dde/treeland-input-manager-unstable-v1.xml dde/treeland-keyboard-state-notify-unstable-v1.xml dde/treeland-output-manager-unstable-v2.xml dde/treeland-shortcut-manager-unstable-v3.xml + dde/treeland-compositor-action-unstable-v1.xml dde/treeland-appearance-manager-unstable-v1.xml dde/treeland-virtual-output-manager-v1.xml dde/treeland-wallpaper-manager-unstable-v1.xml - dde/treeland-show-desktop-unstable-v1.xml dde/treeland-layer-shell-extension-unstable-v1.xml dde/treeland-xwindow-control-unstable-v1.xml + dde/treeland-active-notify-unstable-v1.xml + dde/treeland-region-watch-unstable-v1.xml ) # Internal protocol XML files (Treeland-specific, not for general app developers) @@ -58,6 +60,8 @@ set(TREELAND_PROTOCOL_DEPRECATED_XML_FILES deprecated/treeland-personalization-manager-v1.xml deprecated/treeland-prelaunch-splash-v1.xml deprecated/treeland-screensaver-v1.xml + deprecated/treeland-dde-shell-v1.xml + deprecated/treeland-show-desktop-unstable-v1.xml deprecated/treeland-shortcut-manager-v1.xml deprecated/treeland-shortcut-manager-v2.xml deprecated/treeland-wallpaper-color-v1.xml diff --git a/dde/README.md b/dde/README.md index 0baaa6a..59dccf9 100644 --- a/dde/README.md +++ b/dde/README.md @@ -9,12 +9,15 @@ For DDE desktop components. Installed via `TREELAND_PROTOCOL_DDE_XML_FILES`. | `treeland-keyboard-state-notify-unstable-v1.xml` | `treeland_keyboard_state_notify_unstable_v1` | `treeland_keyboard_state_notify_manager_v1`, `treeland_keyboard_state_watcher_v1` | Watch keyboard modifier (caps/num lock) state changes | | `treeland-output-manager-unstable-v2.xml` | `treeland_output_manager_unstable_v2` | `treeland_output_manager_v2`, `treeland_output_picture_control_v2` | Primary output designation, per-output color temperature and brightness control | | `treeland-shortcut-manager-unstable-v3.xml` | `treeland_shortcut_manager_unstable_v3` | `treeland_shortcut_manager_v3`, `treeland_shortcut_capture_v3` | Global keyboard shortcut binding with key/touch/multi-touch gesture support and one-shot shortcut capture | +| `treeland-compositor-action-unstable-v1.xml` | `treeland_compositor_action_unstable_v1` | `treeland_compositor_action_v1` | One-shot privileged triggering of window-independent compositor actions: workspace switching, show-desktop, multitask overview, screen zoom, FPS overlay, lockscreen, shutdown menu, user switch; window-level and task-switch actions are intentionally excluded and remain only as shortcuts in `treeland_shortcut_manager_v3` | | `treeland-appearance-manager-unstable-v1.xml` | `treeland_appearance_manager_unstable_v1` | `treeland_appearance_manager_v1` | Privileged user-level appearance configuration: cursor theme/size, global font, icon theme, accent color, window opacity, color scheme, titlebar height, global corner radius | | `treeland-virtual-output-manager-v1.xml` | `treeland_virtual_output_manager_v1` | `treeland_virtual_output_manager_v1`, `treeland_virtual_output_v1` | Virtual (mirrored) output creation and management | | `treeland-wallpaper-manager-unstable-v1.xml` | `treeland_wallpaper_manager_unstable_v1` | `treeland_wallpaper_manager_v1`, `treeland_wallpaper_v1` | Per-output wallpaper configuration with image/video sources | -| `treeland-show-desktop-unstable-v1.xml` | `treeland_show_desktop_unstable_v1` | `treeland_show_desktop_v1` | Show-desktop mode control: request mode transitions and observe compositor-driven state changes | | `treeland-layer-shell-extension-unstable-v1.xml` | `treeland_layer_shell_extension_unstable_v1` | `treeland_layer_shell_extension_manager_v1`, `treeland_layer_shell_extension_object_v1` | Compositor-driven interactive resize for layer-shell surfaces (dock / side bar / status bar): begin_resize with seat+serial, per-resize size limits, and rejection reasons | | `treeland-xwindow-control-unstable-v1.xml` | `treeland_xwindow_control_unstable_v1` | `treeland_xwindow_control_v1` | XWayland window placement: move an XWayland window (by X11 window ID) to a position relative to another surface, with wl_callback result feedback | +| `treeland-active-notify-unstable-v1.xml` | `treeland_active_notify_unstable_v1` | `treeland_active_notify_manager_v1`, `treeland_active_notify_v1` | Seat activity notification: observe pointer button/wheel enter/leave activity and drag/drop lifecycle events scoped to a seat | +| `treeland-region-watch-unstable-v1.xml` | `treeland_region_watch_unstable_v1` | `treeland_region_watch_manager_v1`, `treeland_region_watch_v1` | Edge-anchored region overlap watch: register an edge-anchored region on an output and observe enter/leave overlap events with xdg-shell toplevels | +| `treeland-dde-shell-unstable-v2.xml` | `treeland_dde_shell_unstable_v2` | `treeland_dde_shell_manager_v2`, `treeland_dde_shell_surface_v2` | DDE shell surface role: turn a wl_surface into a shell surface rendered below the wlr-layer-shell layer stack at the workspace overlay level, suggest an initial position relative to an output or the cursor, and declare switcher/dock-preview/multitask-view listing preferences via a skip bitfield | ## Breaking changes @@ -26,6 +29,25 @@ Breaking changes are grouped by version. Under each version heading, one subsect The `set_accent_color` request dropped its `a` (alpha) argument. The accent color is now an opaque RGB triple `r, g, b` (each `uint` in `[0, 255]`); the alpha channel is no longer carried on the wire. Consumers must stop sending the trailing `a` argument and must not interpret accent color opacity from this request; opacity is outside the scope of the accent color setting. +#### `treeland-show-desktop-unstable-v1.xml` + +Deprecated and moved to `deprecated/`; superseded by the `show_desktop` action of the `treeland_compositor_action_v1` global of `treeland-compositor-action-unstable-v1.xml` (in `dde/`). Wire-level differences: + +1. The replacement is a one-shot fire-and-forget trigger: the `show_desktop` action toggles show-desktop mode and the compositor sends no confirmation, whereas `set_show_desktop_state` requested an explicit transition to `show` or `normal` and the `show_desktop_state` event confirmed every state change. +2. State observation has no direct replacement: the new protocol carries no events, so clients that tracked the mode via `show_desktop_state` (including the initial state sent on bind) lose that feedback and must treat triggering as best-effort. +3. The replacement global is privileged: only the DDE clients allowed by the compositor may bind `treeland_compositor_action_v1`, whereas `treeland_show_desktop_v1` was bound by regular shell clients. + +Consumers should rebind the global as `treeland_compositor_action_v1` and trigger the `show_desktop` action; the old XML is kept installed during migration but must not be used in new code. + +#### `treeland-dde-shell-v1.xml` + +The DDE-shell protocol interfaces consumed by DDE components are split into dedicated `dde/` protocols. Each replacement is an independent privileged global; consumers should bind the new globals and stop using the deprecated dde-shell interfaces. + +- `treeland_dde_active_v1` (and its `get_treeland_dde_active` manager request) is non-functional and superseded by `treeland-active-notify-unstable-v1.xml` (`treeland_active_notify_manager_v1` / `treeland_active_notify_v1`): `get_active_notify` creates a per-seat notifier whose `activity_changed` event carries a `reason` enum and an `activity_state` enum (renamed from `active_in`/`active_out`; mouse tracks the left-button state, wheel is a per-event pulse), plus a `drag_changed` event carrying a `drag_state` enum (started/dropped/cancelled). +- `treeland_window_overlap_checker` (and its `get_window_overlap_checker` manager request) is non-functional and superseded by `treeland-region-watch-unstable-v1.xml` (`treeland_region_watch_manager_v1` / `treeland_region_watch_v1`): the watcher interface gains the `_v1` suffix, the region request is renamed from `update` to `set_region` with an explicit `anchor` enum and `invalid_anchor`/`invalid_size` errors, and `output_removed` covers output lifetime. +- `treeland_multitaskview_v1` and `treeland_lockscreen_v1` (with their creating requests) are superseded by the corresponding actions (`toggle_multitask_view`/`open_multitask_view`/`close_multitask_view` and `lockscreen`/`shutdown_menu`/`show_user_switch`) of `treeland-compositor-action-unstable-v1.xml` (`treeland_compositor_action_v1`). +- `treeland_dde_shell_surface_v1` (and its `get_shell_surface` manager request) is superseded by `treeland-dde-shell-unstable-v2.xml` (`treeland_dde_shell_manager_v2` / `treeland_dde_shell_surface_v2`), in `dde/`; the surface role is carried over with a 0-based `role` enum and a merged `set_skip_flags` bitfield. + ### 0.6.0 #### `treeland-output-manager-v1.xml` @@ -101,6 +123,6 @@ Superseded by `treeland-shortcut-manager-unstable-v3.xml`; the old v2 file moved 2. The manager interface version was reset from 3 to 1 and all `since` attributes were removed (they marked members added across v2 interface versions 2 and 3: `capture_next_shortcut`, the `invalid_surface` error, and the `tile_left`/`tile_right` actions). 3. The `action` enum was restructured and renumbered: `quit` and `taskswitch_enter` were removed (`quit` is no longer exposed as a shortcut; the task switcher is entered implicitly by the `taskswitch_next`/`taskswitch_prev` actions); the direct-switch set was expanded from `workspace_1`..`workspace_6` to `workspace_1`..`workspace_12`; and 14 new actions were added — `minimize`, `resize_window`, `move_window_to_prev_workspace`, `move_window_to_next_workspace`, `zoom_in`/`zoom_out`/`zoom_reset`, and the tiling snap family `tile_top`/`tile_bottom`/`tile_top_left`/`tile_top_right`/`tile_bottom_left`/`tile_bottom_right`. Entries were regrouped into logical families (notify, workspace switching, window state, window operations, cross-workspace move, show-desktop/multitask, task switching, tiling, screen zoom, system), so every action value changed; `notify` is now 0 and `shutdown_menu` is now 45. Some newly added actions may not yet be implemented by every compositor build; binding such an action is accepted but has no effect until implemented. 4. The commit mechanism was removed: `bind_key`, `bind_swipe_gesture`, and `bind_hold_gesture` take effect immediately, a rejected bind is reported per binding via the new `bind_failure` event, and the `commit` request, the `commit_success` and `commit_failure` events, and the `error.invalid_commit` entry no longer exist. The `error.invalid_surface` entry was renumbered from 4 to 3. Unlike the old model, one failing binding no longer rolls back the other bindings of the same batch. -5. Documentation was refined (no wire change): destroying the manager object is now documented to implicitly release the exclusive control acquired via `acquire`, and the `capture_next_shortcut` request and the capture interface semantics were rewritten to match the compositor implementation (trigger timing, seat/focus validation, the `busy`/`aborted` failure conditions, and the valid-shortcut rules). +5. Documentation was refined (no wire change): destroying the manager object is documented to implicitly release the exclusive control acquired via `acquire`, and the `capture_next_shortcut` request and the capture interface semantics were rewritten to match the compositor implementation (trigger timing, seat/focus validation, the `busy`/`aborted` failure conditions, and the valid-shortcut rules). Consumers should rebind the global as `treeland_shortcut_manager_v3`, send `acquire` before any bind or unbind request, and create capture objects via `capture_next_shortcut`; the old v2 XML is kept installed during migration but must not be used in new code. diff --git a/dde/README.zh_CN.md b/dde/README.zh_CN.md index ece28e3..442be52 100644 --- a/dde/README.zh_CN.md +++ b/dde/README.zh_CN.md @@ -9,12 +9,15 @@ | `treeland-keyboard-state-notify-unstable-v1.xml` | `treeland_keyboard_state_notify_unstable_v1` | `treeland_keyboard_state_notify_manager_v1`, `treeland_keyboard_state_watcher_v1` | 监听键盘修饰键（Caps/Num Lock）状态变化 | | `treeland-output-manager-unstable-v2.xml` | `treeland_output_manager_unstable_v2` | `treeland_output_manager_v2`, `treeland_output_picture_control_v2` | 指定主屏、逐输出色温和亮度控制 | | `treeland-shortcut-manager-unstable-v3.xml` | `treeland_shortcut_manager_unstable_v3` | `treeland_shortcut_manager_v3`, `treeland_shortcut_capture_v3` | 全局键盘快捷键绑定，支持按键/触摸/多点触摸手势及一次性快捷键捕获 | +| `treeland-compositor-action-unstable-v1.xml` | `treeland_compositor_action_unstable_v1` | `treeland_compositor_action_v1` | 特权客户端一次性触发与当前窗口无关的合成器动作：工作区切换、显示桌面、多任务视图、屏幕缩放、FPS 覆盖层、锁屏、关机菜单、用户切换；窗口级与任务切换动作被有意排除，仅作为 `treeland_shortcut_manager_v3` 中的快捷键保留 | | `treeland-appearance-manager-unstable-v1.xml` | `treeland_appearance_manager_unstable_v1` | `treeland_appearance_manager_v1` | 特权用户级外观配置：光标主题/大小、全局字体、图标主题、强调色、窗口不透明度、配色方案、标题栏高度、全局圆角 | | `treeland-virtual-output-manager-v1.xml` | `treeland_virtual_output_manager_v1` | `treeland_virtual_output_manager_v1`, `treeland_virtual_output_v1` | 虚拟（镜像）输出创建和管理 | | `treeland-wallpaper-manager-unstable-v1.xml` | `treeland_wallpaper_manager_unstable_v1` | `treeland_wallpaper_manager_v1`, `treeland_wallpaper_v1` | 逐输出壁纸配置，支持图片/视频来源 | -| `treeland-show-desktop-unstable-v1.xml` | `treeland_show_desktop_unstable_v1` | `treeland_show_desktop_v1` | 显示桌面模式控制：请求模式切换并观察合成器驱动的状态变化 | | `treeland-layer-shell-extension-unstable-v1.xml` | `treeland_layer_shell_extension_unstable_v1` | `treeland_layer_shell_extension_manager_v1`, `treeland_layer_shell_extension_object_v1` | 合成器驱动的 layer-shell 表面交互式缩放（dock / 侧边栏 / 状态栏）：begin_resize 携带 seat+serial 与单次尺寸限制，及拒绝原因 | | `treeland-xwindow-control-unstable-v1.xml` | `treeland_xwindow_control_unstable_v1` | `treeland_xwindow_control_v1` | XWayland 窗口定位：将 XWayland 窗口（按 X11 窗口 ID）移动到相对另一 surface 的位置，结果经 wl_callback 回报 | +| `treeland-active-notify-unstable-v1.xml` | `treeland_active_notify_unstable_v1` | `treeland_active_notify_manager_v1`、`treeland_active_notify_v1` | Seat 活跃通知：订阅按 Seat 限定的指针按键/滚轮进入/离开活跃状态及拖拽/放下的生命周期事件 | +| `treeland-region-watch-unstable-v1.xml` | `treeland_region_watch_unstable_v1` | `treeland_region_watch_manager_v1`、`treeland_region_watch_v1` | 沿输出边缘的区域重叠监控：注册锚定输出边缘的区域并订阅与 xdg-shell 顶层窗口重叠/解除重叠的 enter/leave 事件 | +| `treeland-dde-shell-unstable-v2.xml` | `treeland_dde_shell_unstable_v2` | `treeland_dde_shell_manager_v2`、`treeland_dde_shell_surface_v2` | DDE Shell surface 角色：将 wl_surface 转为在 wlr-layer-shell 层叠之下、工作区 overlay 层渲染的 shell surface，建议相对输出或光标的初始位置，并通过 skip 位域声明任务切换器/dock 预览/多任务视图的列表偏好 | ## 破坏性变更 @@ -26,6 +29,25 @@ `set_accent_color` 请求移除了 `a`（alpha）参数。活动色现为不透明 RGB 三元组 `r, g, b`（每个为 `[0, 255]` 范围内的 `uint`）；alpha 通道不再上线缆传输。消费者须停止发送末尾的 `a` 参数，且不得从该请求推断活动色不透明度；不透明度不在活动色设置范围内。 +#### `treeland-show-desktop-unstable-v1.xml` + +已废弃并移至 `deprecated/`；由 `treeland-compositor-action-unstable-v1.xml`（在 `dde/`）中 `treeland_compositor_action_v1` 全局对象的 `show_desktop` 动作取代。线缆级差异： + +1. 替代方案是一次性的 fire-and-forget 触发：`show_desktop` 动作切换显示桌面模式，合成器不发送任何确认；而 `set_show_desktop_state` 请求显式切换到 `show` 或 `normal`，并由 `show_desktop_state` 事件确认每一次状态变化。 +2. 状态观察无直接替代：新协议不携带任何事件，曾通过 `show_desktop_state`（含绑定时发送的初始状态）跟踪模式的客户端将失去该反馈，只能将触发视为尽力而为。 +3. 替代全局对象为特权接口：仅允许由合成器授权的 DDE 客户端绑定 `treeland_compositor_action_v1`，而 `treeland_show_desktop_v1` 可由常规 shell 客户端绑定。 + +消费者应将全局对象重新绑定为 `treeland_compositor_action_v1` 并触发 `show_desktop` 动作；旧 XML 在迁移期间仍会安装，但不得用于新代码。 + +#### `treeland-dde-shell-v1.xml` + +DDE-shell 协议中被 DDE 组件消费的接口拆分为 `dde/` 下的专用协议。每个替代品均为独立的特权全局对象；消费者应改绑新的全局对象，停止使用已废弃的 dde-shell 接口。 + +- `treeland_dde_active_v1`（含其创建请求 `get_treeland_dde_active`）已不可用，由 `treeland-active-notify-unstable-v1.xml`（`treeland_active_notify_manager_v1` / `treeland_active_notify_v1`）取代：`get_active_notify` 创建按 Seat 限定的通知对象，其 `activity_changed` 事件携带 `reason` 与 `activity_state` 枚举（由 `active_in`/`active_out` 更名；鼠标跟踪左键状态，滚轮为逐事件脉冲），并新增携带 `drag_state` 枚举（started/dropped/cancelled）的 `drag_changed` 事件。 +- `treeland_window_overlap_checker`（含其创建请求 `get_window_overlap_checker`）已不可用，由 `treeland-region-watch-unstable-v1.xml`（`treeland_region_watch_manager_v1` / `treeland_region_watch_v1`）取代：watcher 接口补上 `_v1` 后缀，设区域请求由 `update` 更名为 `set_region`，含显式 `anchor` 枚举与 `invalid_anchor`/`invalid_size` 错误，并新增 `output_removed` 覆盖输出生命周期。 +- `treeland_multitaskview_v1` 和 `treeland_lockscreen_v1`（含其创建请求）由 `treeland-compositor-action-unstable-v1.xml`（`treeland_compositor_action_v1`）的对应动作取代（`toggle_multitask_view`/`open_multitask_view`/`close_multitask_view` 与 `lockscreen`/`shutdown_menu`/`show_user_switch`）。 +- `treeland_dde_shell_surface_v1`（含其创建请求 `get_shell_surface`）由 `treeland-dde-shell-unstable-v2.xml`（`treeland_dde_shell_manager_v2` / `treeland_dde_shell_surface_v2`）取代，后者位于 `dde/`；surface 角色得以保留，`role` 枚举改为 0 基编号，skip 请求合并为 `set_skip_flags` 位域。 + ### 0.6.0 #### `treeland-output-manager-v1.xml` @@ -101,6 +123,6 @@ 2. 管理器接口版本从 3 重置为 1，并移除所有 `since` 属性（这些属性标记的是 v2 接口第 2、3 版新增的成员：`capture_next_shortcut`、`invalid_surface` 错误以及 `tile_left`/`tile_right` action）。 3. `action` 枚举重构并重新编号：移除 `quit` 与 `taskswitch_enter`（`quit` 不再作为快捷键暴露；任务切换器由 `taskswitch_next`/`taskswitch_prev` 动作隐式进入）；直接切换集合由 `workspace_1`..`workspace_6` 扩展为 `workspace_1`..`workspace_12`；新增 14 个动作——`minimize`、`resize_window`、`move_window_to_prev_workspace`、`move_window_to_next_workspace`、`zoom_in`/`zoom_out`/`zoom_reset`，以及贴边 snap 家族 `tile_top`/`tile_bottom`/`tile_top_left`/`tile_top_right`/`tile_bottom_left`/`tile_bottom_right`。各项按逻辑族重新分组（notify、工作区切换、窗口状态、窗口操作、跨工作区移动、显示桌面/多任务、任务切换、贴边、屏幕缩放、系统），因此所有动作值均变更；`notify` 现为 0，`shutdown_menu` 现为 45。部分新增动作未必已被所有合成器构建实现；绑定此类动作会被接受，但在实现前无效果。 4. 移除 commit 机制：`bind_key`、`bind_swipe_gesture`、`bind_hold_gesture` 立即生效，被拒绝的绑定通过新增的 `bind_failure` 事件逐个报告，`commit` 请求、`commit_success` 与 `commit_failure` 事件以及 `error.invalid_commit` 枚举项不复存在。`error.invalid_surface` 枚举项从 4 重编号为 3。与旧模型不同，单个绑定失败不再回滚同批次的其他绑定。 -5. 文档完善（无线缆变更）：销毁管理器对象现明确说明会隐式释放经由 `acquire` 获取的独占控制权；`capture_next_shortcut` 请求与捕获接口语义重写以对齐合成器实现（触发时机、seat/focus 校验、`busy`/`aborted` 失败条件及有效快捷键规则）。 +5. 文档完善（无线缆变更）：销毁管理器对象明确说明会隐式释放经由 `acquire` 获取的独占控制权；`capture_next_shortcut` 请求与捕获接口语义重写以对齐合成器实现（触发时机、seat/focus 校验、`busy`/`aborted` 失败条件及有效快捷键规则）。 消费者应将全局对象重新绑定为 `treeland_shortcut_manager_v3`，在发送任何 bind 或 unbind 请求前先 `acquire`，并通过 `capture_next_shortcut` 创建捕获对象；旧 v2 XML 在迁移期间仍会安装，但不得用于新代码。 diff --git a/dde/treeland-active-notify-unstable-v1.xml b/dde/treeland-active-notify-unstable-v1.xml new file mode 100644 index 0000000..d704f6e --- /dev/null +++ b/dde/treeland-active-notify-unstable-v1.xml @@ -0,0 +1,168 @@ + + + + + + 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 a privileged DDE client such as the dock or shell + to observe seat activity that the compositor detects: pointer button + and wheel activity, and drag and drop lifecycle events, scoped to a + given seat. + + The compositor must reject bind attempts from non-privileged + clients. + + The terms "must", "must not", "should", and "may" in this document + are to be interpreted as described in RFC 2119. + + + + + A global that creates treeland_active_notify_v1 objects for + privileged DDE clients. Each notifier reports activity for + one seat; clients observing several seats create several + notifiers. + + The compositor must reject bind attempts from non-privileged + clients. + + + + + Destroy the treeland_active_notify_manager_v1 object. + Notifiers created through this manager are not affected. + + + + + + Create a new treeland_active_notify_v1 object that + reports activity for the given seat. The seat must be a + valid, current wl_seat. + + + + + + + + + A notifier object reports seat activity that the compositor + detects. Activity is reported as activity_changed events + tagged with the source that triggered them and the new + activity state. Drag and drop lifecycle changes are reported + as drag_changed events tagged with the new drag state. + + The mouse and wheel sources have different semantics: + + For mouse, activity_changed reports the aggregate state of + the left pointer button only. It is sent with state active + when the left button is pressed and state inactive when it + is released. Other pointer buttons do not generate these + events. The compositor sends these events as matched pairs: + it must not send a state active event before the matching + state inactive event, nor a state inactive event when the + left button is not pressed. + + For wheel, activity_changed is a discrete per-event pulse, + not a persistent state. It is sent with state active for + each wheel event whose angle delta is positive, and state + inactive for each whose angle delta is negative; the + compositor may send several active (or several inactive) + events in a row without an intervening opposite state. + Clients must treat each wheel event independently and must + not infer a lasting state from a single event. + + The drag_changed event reports the lifecycle of a drag and + drop operation on the seat. It is sent with state started + when the operation begins. Exactly one terminal event + follows each started event: one with state dropped when the + operation completes with a successful drop, or one with + state cancelled when the operation ends without a drop + (for example because the drag was cancelled or the source + destroyed). No further drag events are sent after the + terminal event until the next started event. + + + + + The input source that triggered an activity event. Used + by the activity_changed event. See the interface + description for the per-source semantics. + + + + + + + + The state reported by the activity_changed event. See + the interface description for the per-source semantics. + + + + + + + + The state reported by the drag_changed event. + + + + + + + + + Destroy the treeland_active_notify_v1 object. The + compositor stops reporting activity for the seat bound + to this notifier. + + + + + + For mouse, sent when the left pointer button is pressed + (state active) or released (state inactive). The + compositor sends these events as matched pairs. + + For wheel, sent for each wheel event: state active when + the angle delta is positive, state inactive when it is + negative; the compositor may send several active (or + several inactive) events in a row without an + intervening opposite state. + + See the interface description for the per-source + semantics. + + + + + + + + Sent when the state of a drag and drop operation on the + seat bound to this notifier changes. + + A started event is followed by exactly one terminal + event: dropped when the operation completes with a + successful drop, or cancelled when the operation ends + without a drop (for example because the drag was + cancelled or the drag source destroyed). No further + drag events are sent after the terminal event until + the next started event. + + + + + diff --git a/dde/treeland-compositor-action-unstable-v1.xml b/dde/treeland-compositor-action-unstable-v1.xml new file mode 100644 index 0000000..87f288a --- /dev/null +++ b/dde/treeland-compositor-action-unstable-v1.xml @@ -0,0 +1,173 @@ + + + + + + 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 a privileged DDE client such as the dock, the + shutdown applet, or the greeter to trigger compositor actions + directly, without registering a keyboard or gesture shortcut. + + This protocol is independent of treeland_shortcut_manager_v3 and of + any other Treeland protocol. The action values defined here form + their own value space: they are not aligned with, and must not be + assumed to match, the action enum of the shortcut manager. The + compositor maps them to internal actions through its own table, and + future versions of either protocol may add, renumber, or remove + entries without regard to the other. + + Following the split used by KWin, this protocol exposes only actions + that are independent of the currently active window and of an + in-progress keyboard task-switching sequence: workspace switching, + show-desktop, the multitask overview, screen zoom, the FPS overlay, + and session-level actions (lock, shutdown menu, user switch). Actions + that act on the currently active window (maximize, minimize, close, + move, resize, show the window menu, snap tiling, and moving a window + across workspaces) and the task-switch stepping actions depend on + implicit runtime state (the active window or an ongoing Alt-Tab-like + sequence) and are not exposed here; they remain available only as + keyboard or gesture shortcuts registered through + treeland_shortcut_manager_v3. Exposing those window-level actions as + a directly callable interface would let a background client manipulate + a window chosen by keyboard focus rather than by explicit reference, + which is the same reason KWin keeps them behind kglobalaccel instead + of offering them on its DBus interface. + + The compositor must reject bind attempts from non-privileged + clients. + + This interface is stateless: each request is an independent one-shot + action. The compositor does not send events in response to these + requests; clients that need to observe the resulting session state + should use the appropriate session or idle protocols instead. + + The terms "must", "must not", "should", and "may" in this document + are to be interpreted as described in RFC 2119. + + + + + A global that exposes compositor actions to a privileged + DDE client. + + The compositor must reject bind attempts from non-privileged + clients. + + Only window-independent actions are exposed here; actions + that target the currently active window or step an in-progress + task switch are not part of this interface and must be triggered + as shortcuts through treeland_shortcut_manager_v3. See the + protocol-level description for the rationale. + + All actions are triggered with the trigger request, which takes + an action argument. + + The compositor should ignore an action it cannot perform, for + example locking while a lock screen is already active; clients + must not assume an action has taken effect. + + The shutdown-menu actions show the shutdown and session menu; + they differ only in which menu button receives the default + keyboard focus. shutdown_menu expresses no preference; the + power_off, reboot, suspend, hibernate, and log_out entries + request focus on the matching button. Showing the menu does not + perform the power action itself; the compositor or greeter + carries out the chosen action after the user confirms. + + + + + Shell actions exposed through the trigger request, limited + to those independent of the currently active window. + + The values are specific to this protocol. They are not + aligned with the action enum of + treeland_shortcut_manager_v3, and clients must not build any + mapping between the two enums. + + Actions that target the currently active window (maximize, + minimize, close, move, resize, show the window menu, snap + tiling, and moving a window across workspaces) and the + task-switch stepping actions are not part of this enum; they + depend on the active window or an in-progress switching + sequence and are reachable only as shortcuts via + treeland_shortcut_manager_v3. + + Values 25-30 (show_user_switch and the focused shutdown-menu + actions) have no counterpart in the shortcut manager because + they are triggered by a shell client rather than a keyboard + shortcut. The focused shutdown-menu entries behave like + shutdown_menu but request default focus on the matching + button. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Destroy the treeland_compositor_action_v1 object. This request + does not alter any compositor, shell, or session state. + + + + + + Trigger the compositor action identified by the action argument. + The compositor should ignore the request when the action + cannot be performed, for example locking while a lock + screen is already active, or showing the shutdown menu while + a lock screen is already active. Clients must not assume + the action has taken effect. + + The shutdown-menu actions show the menu; they do not perform + the power action itself. + + + + + diff --git a/dde/treeland-dde-shell-unstable-v2.xml b/dde/treeland-dde-shell-unstable-v2.xml new file mode 100644 index 0000000..d96da1a --- /dev/null +++ b/dde/treeland-dde-shell-unstable-v2.xml @@ -0,0 +1,214 @@ + + + + + + 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 lets a privileged DDE client turn a wl_surface + into a shell surface that renders below the wlr-layer-shell + layer stack, at the overlay level of the workspace, and position + it at coordinates relative to an output or auto-place it below + the cursor. + + The compositor must reject bind attempts from non-privileged + clients. + + The terms "must", "must not", "should", and "may" in this document + are to be interpreted as described in RFC 2119. + + + + + A global that creates treeland_dde_shell_surface_v2 objects for + privileged DDE clients implementing parts of the shell user + interface. + + The compositor must reject bind attempts from non-privileged + clients. + + + + + Errors raised by the treeland_dde_shell_manager_v2 + interface. + + + + + + + Destroy the treeland_dde_shell_manager_v2 object. + Shell surfaces created through this manager are not + affected. + + + + + + Create a new treeland_dde_shell_surface_v2 object for the + given surface, turning it into a shell surface. Only one + shell surface object can be associated with a given + wl_surface; the compositor raises already_shell_surface + for a second attempt. + + Recommended for use with xdg_surface. + + + + + + + + + A shell surface object assigns the DDE shell surface role to a + wl_surface. A shell surface renders below the wlr-layer-shell + layer stack, at the overlay level of the workspace: above + normal toplevel windows but below layer-shell surfaces. + + The role carries no requests that map, commit, or configure + buffer state; the client commits buffers with wl_surface + semantics as usual. + + On the server side the object is automatically destroyed when + the related wl_surface is destroyed. On the client side, + treeland_dde_shell_surface_v2.destroy() must be called before + destroying the wl_surface object. + + Positioning requests are mutually exclusive: set_position_hint + suggests fixed coordinates relative to an output, while + set_cursor_placement_hint asks the compositor to place the + surface relative to the cursor. The most recently sent + request determines the placement mode. Both requests are + hints for the initial placement of the surface: the + compositor decides the final position and may adjust it to + keep the surface accessible, for example to keep its + titlebar area within the output. Clients must not assume the + requested position is honored exactly. + + + + + The layer a shell surface renders in. Layers are ordered by + z depth. Multiple surfaces can share a single role, and + ordering within a single role is undefined. + + + + + + + Flags indicating that the surface prefers not to be listed + in specific shell views. Used by the set_skip_flags + request. Compositors should honor these preferences but + may ignore them, for example for windows the user must + always be able to reach. + + + + + + + + + The treeland_dde_shell_surface_v2 interface is removed from + the wl_surface object that was turned into a shell surface + with the treeland_dde_shell_manager_v2.get_shell_surface + request. + + The shell surface role is lost and the wl_surface is + unmapped. + + + + + + Assign the role identified by the role enum to this shell + surface, selecting the layer it renders in. The default + role before this request is overlay. + + + + + + + Suggest a position for the surface. The coordinates are + relative to the origin of the given output; for example + 50,50 suggests placing the surface 50 units right of and + 50 units below the output's top-left corner, wherever + that output currently sits in the global space spanning + all outputs. + + The output argument may be null, in which case the + compositor uses the primary output as the anchor. + Otherwise the output must be a valid, current wl_output. + The position is resolved at request time; the compositor + does not keep the output associated with this surface + afterwards, and the client may release the wl_output + proxy once the request has been sent. If the output is + later destroyed, the already-applied position is not + affected. + + This request is a hint for the initial placement of the + surface: the compositor decides the final position and + may adjust it to keep the surface accessible. Clients + must not assume the requested position is honored + exactly. + + + + + + + + + Suggest placing the surface relative to the current cursor + position: horizontally offset by x_offset from the cursor + center and vertically offset by y_offset from the bottom + of the cursor. + + This request is a hint for the initial placement of the + surface: the compositor decides the final position and + may adjust it to keep the surface accessible. Clients + must not assume the requested position is honored + exactly. + + Sending this request switches the placement mode to + cursor-relative; see the interface description for the + interaction with set_position_hint. + + + + + + + + Set the shell views that should not list this surface. The + flags argument is a bitfield of skip_flag values; setting + a flag asks the shell view not to include the surface, + clearing it restores default listing. This request + replaces any previously set flags. + + + + + + + Set whether this surface can receive keyboard focus. When + set to 0, the surface will not receive keyboard focus even + when clicked or activated. When set to 1 (the default), the + surface receives keyboard focus normally. + + + + + diff --git a/dde/treeland-region-watch-unstable-v1.xml b/dde/treeland-region-watch-unstable-v1.xml new file mode 100644 index 0000000..c4b1a41 --- /dev/null +++ b/dde/treeland-region-watch-unstable-v1.xml @@ -0,0 +1,188 @@ + + + + + + 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 a privileged DDE client such as the dock to + monitor whether a region anchored to an edge of an output overlaps + with any xdg-shell toplevel window, for example to implement smart + panel hiding. + + The compositor must reject bind attempts from non-privileged + clients. + + The terms "must", "must not", "should", and "may" in this document + are to be interpreted as described in RFC 2119. + + + + + A global that creates treeland_region_watch_v1 + objects for privileged DDE clients. Each watcher monitors + one region; clients monitoring several regions create + several watchers. + + The compositor must reject bind attempts from non-privileged + clients. + + + + + Destroy the treeland_region_watch_manager_v1 + object. Watchers created through this manager are not + affected. + + + + + + Create a new treeland_region_watch_v1 object + that monitors one region. + + + + + + + + A watcher object monitors whether a rectangular region + anchored to an edge of an output overlaps with any xdg-shell + toplevel window. + + The client registers the monitored region with the + set_region request and the compositor reports transitions + between the overlapped and clear states with the enter and + leave events. The recorded region only changes when + set_region is called; the client must call set_region again + whenever the monitored panel moves or resizes. + + After each set_region request the compositor must evaluate + the region against the current window layout and send the + matching enter or leave event; afterwards it should send + these events only when the overlap state changes. + + The watcher is associated with the wl_output passed to the + last set_region request. When that output is destroyed the + compositor sends the output_removed event; the watcher then + becomes inert: it has no monitored region and sends no + further enter or leave events. The watcher object itself is + not destroyed by output removal; the client may call + set_region again with another wl_output to resume + monitoring, or call destroy to release it. The compositor + must not send enter, leave, or output_removed after + output_removed until the next successful set_region. + + The client may release the wl_output proxy passed to + set_region at any time after the request returns; the + compositor holds its own reference and the watcher remains + associated with that output until either the output is + destroyed (triggering output_removed) or a subsequent + set_region rebinds to a different output. + + + + + The registered region is a strip along the anchored edge + of the output: for top and bottom the strip spans the + full output width and is height units thick; for left and + right it spans the full output height and is width units + thick. + + The dimension along the anchored edge is ignored: for + top and bottom the compositor uses the full output width + regardless of the width argument, and for left and right + it uses the full output height regardless of the height + argument. Only the thickness dimension matters — height + for top/bottom, width for left/right — and it must be + positive; the compositor raises invalid_size otherwise. + + + + + + + + + + Errors raised by the treeland_region_watch_v1 + interface. + + + + + + + + Destroy the treeland_region_watch_v1 object. + The compositor stops monitoring the region registered + with this watcher. + + + + + + Set the monitored region on the given output, or + re-register it when the monitored panel moves or + resizes. The region geometry is described by the anchor + enum; the compositor raises invalid_anchor for an + unknown anchor value and invalid_size when width or + height is not positive. + + The output becomes the output associated with the + watcher, replacing any previous one; it may be a + different output from a previous call (rebinding), for + example after the previous output was removed. + + After this request the compositor must evaluate the + current overlap state and send the matching enter or + leave event. + + + + + + + + + + Sent when the registered region begins to overlap any + xdg-shell toplevel window, and after a set_region + request while the region is currently overlapped. + + + + + + Sent when the registered region stops overlapping all + xdg-shell toplevel windows, and after a set_region + request while the region is currently clear. + + + + + + Sent when the wl_output passed to the last set_region + request has been destroyed by the compositor. The + watcher then becomes inert: it has no monitored region + and sends no further enter or leave events. + + The watcher object itself is not destroyed; the client + may call set_region again with another wl_output to + resume monitoring, or call destroy to release it. The + compositor must not send this event more than once + without an intervening successful set_region. + + + + diff --git a/public/treeland-dde-shell-v1.xml b/deprecated/treeland-dde-shell-v1.xml similarity index 85% rename from public/treeland-dde-shell-v1.xml rename to deprecated/treeland-dde-shell-v1.xml index 6b2fd9e..8e9cbc4 100644 --- a/public/treeland-dde-shell-v1.xml +++ b/deprecated/treeland-dde-shell-v1.xml @@ -20,7 +20,15 @@ This interface allows DDE to configure some treeland functions. - Create a treeland_window_overlap_checker object. + + Deprecated: this request is non-functional. The created + object never emits events, and its requests have no + effect apart from destroy. + + Superseded by the treeland_region_watch_manager_v1 + global of the treeland-region-watch-unstable-v1 + protocol. + @@ -38,7 +46,13 @@ - Create a new dde active for a given seat. + Deprecated: this request is non-functional. The created + object never emits events, and its requests have no + effect apart from destroy. + + Superseded by the treeland_active_notify_manager_v1 + global of the treeland-active-notify-unstable-v1 + protocol. @@ -46,7 +60,11 @@ - Create a new multitaskview context for toggle. + Deprecated: superseded by the open_multitask_view, + close_multitask_view, and toggle_multitask_view actions of + the treeland_compositor_action_v1 global of the + treeland-compositor-action-unstable-v1 protocol. This + request must not be used in new code. @@ -60,7 +78,11 @@ - Create a new lockscreen context for toggle. + Deprecated: superseded by the lockscreen, shutdown_menu, + and show_user_switch actions of the + treeland_compositor_action_v1 global of the + treeland-compositor-action-unstable-v1 protocol. This + request must not be used in new code. @@ -88,7 +110,13 @@ - A treeland_window_overlap_checker object monitors whether the detected window region overlaps with xdg-shell toplevels. + Deprecated: this interface is non-functional. Apart from + the destroy request, all requests have no effect and no + events are ever emitted. New code must not use it. + + Superseded by the treeland_region_watch_manager_v1 + global of the treeland-region-watch-unstable-v1 + protocol. @@ -242,7 +270,12 @@ - An interface used to monitor special events. + Deprecated: this interface is non-functional. Apart from + the destroy request, all requests have no effect and no + events are ever emitted. New code must not use it. + + Superseded by the treeland_active_notify_manager_v1 global of + the treeland-active-notify-unstable-v1 protocol. @@ -279,6 +312,12 @@ An interface used to control multitaskview. + + Deprecated: superseded by the open_multitask_view, + close_multitask_view, and toggle_multitask_view actions of the + treeland_compositor_action_v1 global of the + treeland-compositor-action-unstable-v1 protocol. The interface + must not be used in new code. @@ -323,6 +362,11 @@ An interface used to operate lockscreen. + + Deprecated: superseded by the lockscreen, shutdown_menu, and + show_user_switch actions of the treeland_compositor_action_v1 + global of the treeland-compositor-action-unstable-v1 protocol. + The interface must not be used in new code. diff --git a/dde/treeland-show-desktop-unstable-v1.xml b/deprecated/treeland-show-desktop-unstable-v1.xml similarity index 100% rename from dde/treeland-show-desktop-unstable-v1.xml rename to deprecated/treeland-show-desktop-unstable-v1.xml diff --git a/public/README.md b/public/README.md index 1b5c164..aa4f850 100644 --- a/public/README.md +++ b/public/README.md @@ -5,7 +5,6 @@ For general application developers. Installed via `TREELAND_PROTOCOL_XML_FILES`. | File | Protocol | Interfaces | Purpose | |------|----------|-----------|---------| | `treeland-window-transition-unstable-v1.xml` | `treeland_window_transition_unstable_v1` | `treeland_window_transition_manager_v1`, `treeland_window_transition_rect_v1` | Window open/close transition relative to a rectangle, with optional source image | -| `treeland-dde-shell-v1.xml` | `treeland_dde_shell_v1` | `treeland_dde_shell_manager_v1`, `treeland_window_overlap_checker`, `treeland_dde_shell_surface_v1`, `treeland_dde_active_v1`, `treeland_multitaskview_v1`, `treeland_window_picker_v1`, `treeland_lockscreen_v1` | DDE shell integration: surface roles, overlap detection, active events, multitask view, window picker, lockscreen; the set_xwindow_position_relative request is deprecated and non-functional, superseded by `dde/treeland-xwindow-control-unstable-v1.xml` | | `treeland-appearance-unstable-v1.xml` | `treeland_appearance_unstable_v1` | `treeland_appearance_v1` | Query and observe user-level appearance settings: cursor theme/size, fonts, icon theme, accent color, window opacity, color scheme, titlebar height, corner radius | | `treeland-decoration-unstable-v1.xml` | `treeland_decoration_unstable_v1` | `treeland_decoration_manager_v1`, `treeland_decoration_context_v1` | Per-window server-side decoration (SSD) customization by applications: corner radius, shadow, border, titlebar visibility; requires xdg-decoration SSD | ## Breaking changes @@ -20,12 +19,28 @@ The `accent_color` event dropped its `a` (alpha) argument. The accent color is n #### `treeland-dde-shell-v1.xml` -The manager request `set_xwindow_position_relative` is now documented as deprecated and non-functional: it has no effect and no callback is ever created. The file itself stays in place for now; the whole `treeland-dde-shell` protocol is slated for removal in a future release. +The whole file is deprecated and moved to `deprecated/`. It is superseded by `treeland-dde-shell-unstable-v2.xml` (in `dde/`, the surface role functionality) together with the dedicated protocols listed above; the `treeland_window_picker_v1` interface is removed without a replacement. -It is superseded by a new independent protocol in `dde/`: +Wire-level differences between v1 and v2: + +1. Only the surface role is carried over. The manager exposes just `get_shell_surface` with a new `already_shell_surface` error; the factory requests for the superseded interfaces (`get_window_overlap_checker`, `get_treeland_dde_active`, `get_treeland_multitaskview`, `get_treeland_window_picker`, `get_treeland_lockscreen`) and the `set_xwindow_position_relative` request are not carried over. +2. The `role` enum is renumbered to 0-based: `overlay` changes from 1 to 0, and its semantics are stated precisely (above normal toplevels, below layer-shell surfaces). +3. The three skip requests (`set_skip_switcher`, `set_skip_dock_preview`, `set_skip_muti_task_view`, the latter also fixing the "muti" typo) are merged into a single `set_skip_flags` request taking a `skip_flag` bitfield (`switcher` 0x1, `dock_preview` 0x2, `multitask_view` 0x4). +4. The placement requests are reworked into two hints whose final position the compositor decides: `set_position_hint` suggests fixed coordinates relative to an output (null for the primary output), and `set_cursor_placement_hint` suggests a position relative to the cursor with an `int` y_offset (v1 used `uint`). The mutual exclusivity of the two requests (most recent wins) is now specified. +5. The v2 globals must reject binds from non-privileged clients. + +Consumers should rebind as `treeland_dde_shell_manager_v2`, recreate shell surfaces through `get_shell_surface`, switch to `set_skip_flags`, and treat `overlay` as 0; window-picker consumers have no replacement and must drop the functionality. The old XML is kept installed during migration but must not be used in new code. + +The manager request `set_xwindow_position_relative` and the `treeland_dde_active_v1` and `treeland_window_overlap_checker` interfaces (with their creating manager requests `get_treeland_dde_active` and `get_window_overlap_checker`) are deprecated and non-functional: they have no effect and no events are ever emitted (their `destroy` requests remain functional so clients can release the objects). + +They are superseded by three new independent protocols in `dde/`: - `treeland-xwindow-control-unstable-v1.xml` (`treeland_xwindow_control_v1`): XWayland window placement — the `set_xwindow_position_relative` request with `wl_callback` result feedback, unchanged wire semantics. +- `treeland-active-notify-unstable-v1.xml` (`treeland_active_notify_manager_v1`, `treeland_active_notify_v1`): seat activity notification — the `get_active_notify` request creates a per-seat notifier whose `activity_changed` event carries a `reason` enum and an `activity_state` enum (renamed from `active_in`/`active_out`, with mouse tracking the left button state and wheel as per-event pulses), plus a `drag_changed` event carrying a `drag_state` enum (started/dropped/cancelled). +- `treeland-region-watch-unstable-v1.xml` (`treeland_region_watch_manager_v1`, `treeland_region_watch_v1`): edge-anchored region overlap watch — edge-anchored region registration (`set_region`) with `enter`/`leave` state events and explicit error reporting; the watcher interface is renamed from `treeland_window_overlap_checker`, gaining the `_v1` suffix, and the region-setting request is renamed from `update` to `set_region`. + +The `treeland_multitaskview_v1` and `treeland_lockscreen_v1` interfaces (with their creating requests `get_treeland_multitaskview` and `get_treeland_lockscreen`) are deprecated, superseded by the corresponding actions (`toggle_multitask_view`/`open_multitask_view`/`close_multitask_view` and `lockscreen`/`shutdown_menu`/`show_user_switch`) of the privileged `dde/treeland-compositor-action-unstable-v1.xml` protocol. -Consumers should bind the new global instead of using the manager request; the deprecated request must not be used in new code. +Consumers should bind the new globals instead of using the deprecated manager requests and interfaces; the deprecated requests and interfaces must not be used in new code. ### 0.6.0 diff --git a/public/README.zh_CN.md b/public/README.zh_CN.md index 3268241..1640345 100644 --- a/public/README.zh_CN.md +++ b/public/README.zh_CN.md @@ -5,7 +5,6 @@ | 文件 | 协议 | 接口 | 用途 | |------|----------|-----------|---------| | `treeland-window-transition-unstable-v1.xml` | `treeland_window_transition_unstable_v1` | `treeland_window_transition_manager_v1`, `treeland_window_transition_rect_v1` | 相对某个矩形的窗口打开/关闭转场，可附带源图像 | -| `treeland-dde-shell-v1.xml` | `treeland_dde_shell_v1` | `treeland_dde_shell_manager_v1`, `treeland_window_overlap_checker`, `treeland_dde_shell_surface_v1`, `treeland_dde_active_v1`, `treeland_multitaskview_v1`, `treeland_window_picker_v1`, `treeland_lockscreen_v1` | DDE Shell 集成：surface 角色、重叠检测、活跃事件、多任务视图、窗口选取、锁屏；`set_xwindow_position_relative` 请求已废弃且不可用，由 `dde/treeland-xwindow-control-unstable-v1.xml` 取代 | | `treeland-appearance-unstable-v1.xml` | `treeland_appearance_unstable_v1` | `treeland_appearance_v1` | 查询与订阅用户级外观设置：光标主题/大小、字体、图标主题、强调色、窗口不透明度、配色方案、标题栏高度、圆角 | | `treeland-decoration-unstable-v1.xml` | `treeland_decoration_unstable_v1` | `treeland_decoration_manager_v1`, `treeland_decoration_context_v1` | 逐窗口服务端装饰（SSD）定制：圆角、阴影、边框、标题栏可见性；需先经 xdg-decoration 申请 SSD | @@ -21,12 +20,28 @@ #### `treeland-dde-shell-v1.xml` -管理器的 `set_xwindow_position_relative` 请求现标注为已废弃且不可用：请求无任何效果，也不会创建任何回调。文件暂保留原位；整个 `treeland-dde-shell` 协议计划在未来版本彻底移除。 +整个文件已废弃并移至 `deprecated/`。由 `treeland-dde-shell-unstable-v2.xml`（在 `dde/`，surface 角色功能）连同上述专用协议取代；`treeland_window_picker_v1` 接口无替代直接移除。 -它由 `dde/` 下一个新的独立协议取代： +v1 与 v2 的线缆级差异： + +1. 仅 surface 角色得以保留。管理器只暴露 `get_shell_surface` 并新增 `already_shell_surface` 错误；被取代接口的工厂请求（`get_window_overlap_checker`、`get_treeland_dde_active`、`get_treeland_multitaskview`、`get_treeland_window_picker`、`get_treeland_lockscreen`）及 `set_xwindow_position_relative` 请求不再保留。 +2. `role` 枚举改为 0 基编号：`overlay` 由 1 改为 0，且语义明确化（高于普通顶层窗口、低于 layer-shell surface）。 +3. 三个 skip 请求（`set_skip_switcher`、`set_skip_dock_preview`、`set_skip_muti_task_view`，最后一个同时修正 "muti" 拼写错误）合并为单一的 `set_skip_flags` 请求，携带 `skip_flag` 位域（`switcher` 0x1、`dock_preview` 0x2、`multitask_view` 0x4）。 +4. 放置请求重构为两个提示（最终位置由合成器决定）：`set_position_hint` 建议相对输出（null 为主屏）的固定坐标，`set_cursor_placement_hint` 建议相对光标的位置（y_offset 为 `int`，v1 为 `uint`）。两请求的互斥关系（最近发送者生效）现已明确。 +5. v2 全局对象必须拒绝非特权客户端绑定。 + +消费者应改绑为 `treeland_dde_shell_manager_v2`，通过 `get_shell_surface` 重建 shell surface，改用 `set_skip_flags`，并将 `overlay` 视为 0；窗口选取消费者无替代，须移除该功能。旧 XML 在迁移期间仍会安装，但不得用于新代码。 + +管理器的 `set_xwindow_position_relative` 请求及 `treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口（含其创建请求 `get_treeland_dde_active`、`get_window_overlap_checker`）已废弃且不可用：请求无任何效果，也不会发出任何事件（`destroy` 请求仍然可用，客户端可借此释放对象）。 + +二者由 `dde/` 下三个新的独立协议取代： - `treeland-xwindow-control-unstable-v1.xml`（`treeland_xwindow_control_v1`）：XWayland 窗口定位——`set_xwindow_position_relative` 请求，结果经 `wl_callback` 回报，线缆语义不变。 +- `treeland-active-notify-unstable-v1.xml`（`treeland_active_notify_manager_v1`、`treeland_active_notify_v1`）：Seat 活跃通知——`get_active_notify` 请求创建按 Seat 限定的通知对象，其 `activity_changed` 事件携带 `reason` 与 `activity_state` 枚举（由 `active_in`/`active_out` 更名；鼠标跟踪左键状态，滚轮为逐事件脉冲），并新增携带 `drag_state` 枚举（started/dropped/cancelled）的 `drag_changed` 事件。 +- `treeland-region-watch-unstable-v1.xml`（`treeland_region_watch_manager_v1`、`treeland_region_watch_v1`）：沿输出边缘的区域重叠监控——沿输出边缘的区域注册（`set_region`）与 `enter`/`leave` 状态事件及显式错误回报；watcher 接口由 `treeland_window_overlap_checker` 更名并补上 `_v1` 后缀，设区域请求由 `update` 更名为 `set_region`。 + +`treeland_multitaskview_v1` 和 `treeland_lockscreen_v1` 接口（含其创建请求 `get_treeland_multitaskview`、`get_treeland_lockscreen`）已废弃，由新的特权协议 `dde/treeland-compositor-action-unstable-v1.xml` 的对应动作取代（`toggle_multitask_view`/`open_multitask_view`/`close_multitask_view` 与 `lockscreen`/`shutdown_menu`/`show_user_switch`）。 -消费者应改绑新的全局对象；已废弃请求不得用于新代码。 +消费者应改绑新的全局对象，不得在新代码中使用已废弃的请求与接口。 ### 0.6.0