From 41da5a018304d9323e5ccc611770bdf9c2ffaf16 Mon Sep 17 00:00:00 2001 From: rewine Date: Tue, 15 Sep 2026 11:13:12 +0800 Subject: [PATCH 01/12] feat: add treeland-active-notify unstable-v1 protocol 1. Add treeland-active-notify-unstable-v1: manager + per-seat notifier (get_active_notify), with activity_enter/activity_leave events carrying a reason enum (mouse/wheel) and start_drag/drop events 2. Mark the dde-shell treeland_dde_active_v1 interface and its get_treeland_dde_active manager request deprecated and non-functional 3. Register the protocol in CMakeLists and update dde/public READMEs with a 0.7.0 breaking change entry Log: New active-notify protocol replaces the dde-shell treeland_dde_active_v1 interface; events renamed from active_in/active_out to activity_enter/leave Influence: 1. Install the package and verify the new XML file lands in the treeland-protocols data dir 2. Run wayland-scanner client-header and private-code on the new XML file to confirm parsing 3. Check the READMEs list the new protocol and the dde-shell deprecation note 4. Reconfigure cmake and confirm the build succeeds with the updated DDE file list --- CMakeLists.txt | 1 + dde/README.md | 1 + dde/README.zh_CN.md | 1 + dde/treeland-active-notify-unstable-v1.xml | 126 +++++++++++++++++++++ public/README.md | 9 +- public/README.zh_CN.md | 9 +- public/treeland-dde-shell-v1.xml | 8 +- 7 files changed, 146 insertions(+), 9 deletions(-) create mode 100644 dde/treeland-active-notify-unstable-v1.xml diff --git a/CMakeLists.txt b/CMakeLists.txt index ed62b63..b33cbf6 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -32,6 +32,7 @@ set(TREELAND_PROTOCOL_DDE_XML_FILES 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 ) # Internal protocol XML files (Treeland-specific, not for general app developers) diff --git a/dde/README.md b/dde/README.md index 0baaa6a..fd0c52a 100644 --- a/dde/README.md +++ b/dde/README.md @@ -15,6 +15,7 @@ For DDE desktop components. Installed via `TREELAND_PROTOCOL_DDE_XML_FILES`. | `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 | ## Breaking changes diff --git a/dde/README.zh_CN.md b/dde/README.zh_CN.md index ece28e3..b037478 100644 --- a/dde/README.zh_CN.md +++ b/dde/README.zh_CN.md @@ -15,6 +15,7 @@ | `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` | 座席活跃通知：订阅按座席限定的指针按键/滚轮进入/离开活跃状态及拖拽/放下的生命周期事件 | ## 破坏性变更 diff --git a/dde/treeland-active-notify-unstable-v1.xml b/dde/treeland-active-notify-unstable-v1.xml new file mode 100644 index 0000000..215db67 --- /dev/null +++ b/dde/treeland-active-notify-unstable-v1.xml @@ -0,0 +1,126 @@ + + + + + + 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 should 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 should 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 enter/leave transitions + tagged with the source that triggered them. + + enter means the source became active (for example a pointer + button was pressed or a wheel was scrolled in the positive + direction); leave means the source became inactive (the + button was released or the wheel was scrolled in the negative + direction). The compositor sends these events only on the + transitions, not repeatedly while a state persists. + + The start_drag and drop events report the start and end of a + drag and drop operation on the seat. + + + + + The input source that triggered an activity event. Used + by the activity_enter and activity_leave events. + + + + + + + + Destroy the treeland_active_notify_v1 object. The + compositor stops reporting activity for the seat bound + to this notifier. + + + + + + Sent when the activity source identified by reason + becomes active: for mouse, when a pointer button is + pressed; for wheel, when the wheel is scrolled in the + positive direction. + + + + + + + Sent when the activity source identified by reason + becomes inactive: for mouse, when the pressed pointer + button is released; for wheel, when the wheel is + scrolled in the negative direction. + + + + + + + Sent when a drag and drop operation starts on the seat + bound to this notifier. + + + + + + Sent when a drag and drop operation completes with a + drop on the seat bound to this notifier. + + + + diff --git a/public/README.md b/public/README.md index 1b5c164..cc57cfc 100644 --- a/public/README.md +++ b/public/README.md @@ -5,7 +5,7 @@ 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-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` (deprecated), `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 `treeland_dde_active_v1` interface and the `set_xwindow_position_relative` request are deprecated and non-functional, superseded by `dde/treeland-active-notify-unstable-v1.xml` and `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 +20,13 @@ 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 manager request `set_xwindow_position_relative` and the `treeland_dde_active_v1` interface (with its `get_treeland_dde_active` manager request) are now documented as deprecated and non-functional: they have no effect and no events are ever emitted. The file itself stays in place for now; the whole `treeland-dde-shell` protocol is slated for removal in a future release. -It is superseded by a new independent protocol in `dde/`: +They are superseded by two 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_enter`/`activity_leave` events carry a `reason` enum (renamed from `active_in`/`active_out`), plus `start_drag`/`drop` events. -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 request and interface; the deprecated request and interface 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..8924183 100644 --- a/public/README.zh_CN.md +++ b/public/README.zh_CN.md @@ -5,7 +5,7 @@ | 文件 | 协议 | 接口 | 用途 | |------|----------|-----------|---------| | `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-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 角色、重叠检测、活跃事件、多任务视图、窗口选取、锁屏；`treeland_dde_active_v1` 接口及 `set_xwindow_position_relative` 请求已废弃且不可用，由 `dde/treeland-active-notify-unstable-v1.xml` 和 `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 +21,13 @@ #### `treeland-dde-shell-v1.xml` -管理器的 `set_xwindow_position_relative` 请求现标注为已废弃且不可用：请求无任何效果，也不会创建任何回调。文件暂保留原位；整个 `treeland-dde-shell` 协议计划在未来版本彻底移除。 +管理器的 `set_xwindow_position_relative` 请求及 `treeland_dde_active_v1` 接口（含其创建请求 `get_treeland_dde_active`）现标注为已废弃且不可用：请求无任何效果，也不会发出任何事件。文件暂保留原位；整个 `treeland-dde-shell` 协议计划在未来版本彻底移除。 -它由 `dde/` 下一个新的独立协议取代： +二者由 `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`）：座席活跃通知——`get_active_notify` 请求创建按座席的通知对象，其 `activity_enter`/`activity_leave` 事件携带 `reason` 枚举（由 `active_in`/`active_out` 更名），并新增 `start_drag`/`drop` 事件。 -消费者应改绑新的全局对象；已废弃请求不得用于新代码。 +消费者应改绑新的全局对象，不得在新代码中使用已废弃的请求与接口。 ### 0.6.0 diff --git a/public/treeland-dde-shell-v1.xml b/public/treeland-dde-shell-v1.xml index 6b2fd9e..bd6739a 100644 --- a/public/treeland-dde-shell-v1.xml +++ b/public/treeland-dde-shell-v1.xml @@ -38,7 +38,13 @@ - Create a new dde active for a given seat. + Deprecated: this request is non-functional. The created + object's requests have no effect and no events are ever + emitted. + + Superseded by the treeland_active_notify_manager_v1 + global of the treeland-active-notify-unstable-v1 + protocol. From 8bbb6f54b16bc17f529a0b1a3ffe10a979987879 Mon Sep 17 00:00:00 2001 From: rewine Date: Tue, 15 Sep 2026 11:32:00 +0800 Subject: [PATCH 02/12] feat: add treeland-window-overlap-checker unstable-v1 protocol 1. Add treeland-window-overlap-checker-unstable-v1: manager plus per-region checker objects; get_window_overlap_checker factory, set_region request with anchor enum (top/bottom/left/right) and invalid_anchor/invalid_size errors, enter/leave overlap events 2. Mark the dde-shell treeland_window_overlap_checker interface and its get_window_overlap_checker manager request deprecated and non-functional 3. Register the protocol in CMakeLists and update dde/public READMEs with a 0.7.0 breaking change entry Log: New overlap-checker protocol replaces the dde-shell treeland_window_overlap_checker interface; the checker interface gains the _v1 suffix, and the region request is renamed from update to set_region with explicit error reporting Influence: 1. Install the package and verify the new XML file lands in the treeland-protocols data dir 2. Run wayland-scanner client-header and private-code on the new XML file to confirm parsing 3. Check the READMEs list the new protocol and the dde-shell deprecation note 4. Reconfigure cmake and confirm the build succeeds with the updated DDE file list --- CMakeLists.txt | 1 + dde/README.md | 1 + dde/README.zh_CN.md | 3 +- ...and-window-overlap-checker-unstable-v1.xml | 142 ++++++++++++++++++ public/README.md | 9 +- public/README.zh_CN.md | 9 +- public/treeland-dde-shell-v1.xml | 21 ++- 7 files changed, 175 insertions(+), 11 deletions(-) create mode 100644 dde/treeland-window-overlap-checker-unstable-v1.xml diff --git a/CMakeLists.txt b/CMakeLists.txt index b33cbf6..8647284 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -33,6 +33,7 @@ set(TREELAND_PROTOCOL_DDE_XML_FILES dde/treeland-layer-shell-extension-unstable-v1.xml dde/treeland-xwindow-control-unstable-v1.xml dde/treeland-active-notify-unstable-v1.xml + dde/treeland-window-overlap-checker-unstable-v1.xml ) # Internal protocol XML files (Treeland-specific, not for general app developers) diff --git a/dde/README.md b/dde/README.md index fd0c52a..e800e3e 100644 --- a/dde/README.md +++ b/dde/README.md @@ -16,6 +16,7 @@ For DDE desktop components. Installed via `TREELAND_PROTOCOL_DDE_XML_FILES`. | `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-window-overlap-checker-unstable-v1.xml` | `treeland_window_overlap_checker_unstable_v1` | `treeland_window_overlap_checker_manager_v1`, `treeland_window_overlap_checker_v1` | Window overlap monitoring: register an edge-anchored region on an output and observe enter/leave overlap events with xdg-shell toplevels | ## Breaking changes diff --git a/dde/README.zh_CN.md b/dde/README.zh_CN.md index b037478..a1630de 100644 --- a/dde/README.zh_CN.md +++ b/dde/README.zh_CN.md @@ -15,7 +15,8 @@ | `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` | 座席活跃通知：订阅按座席限定的指针按键/滚轮进入/离开活跃状态及拖拽/放下的生命周期事件 | +| `treeland-active-notify-unstable-v1.xml` | `treeland_active_notify_unstable_v1` | `treeland_active_notify_manager_v1`、`treeland_active_notify_v1` | Seat 活跃通知：订阅按 Seat 限定的指针按键/滚轮进入/离开活跃状态及拖拽/放下的生命周期事件 | +| `treeland-window-overlap-checker-unstable-v1.xml` | `treeland_window_overlap_checker_unstable_v1` | `treeland_window_overlap_checker_manager_v1`、`treeland_window_overlap_checker_v1` | 窗口重叠监测：注册沿输出边缘的区域并订阅与 xdg-shell 顶层窗口重叠/解除重叠的 enter/leave 事件 | ## 破坏性变更 diff --git a/dde/treeland-window-overlap-checker-unstable-v1.xml b/dde/treeland-window-overlap-checker-unstable-v1.xml new file mode 100644 index 0000000..244db5a --- /dev/null +++ b/dde/treeland-window-overlap-checker-unstable-v1.xml @@ -0,0 +1,142 @@ + + + + + + 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 should 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_window_overlap_checker_v1 + objects for privileged DDE clients. Each checker monitors + one region; clients monitoring several regions create + several checkers. + + The compositor should reject bind attempts from non-privileged + clients. + + + + + Destroy the treeland_window_overlap_checker_manager_v1 + object. Checkers created through this manager are not + affected. + + + + + + Create a new treeland_window_overlap_checker_v1 object + that monitors one region. + + + + + + + + A checker 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 should 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 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. + + + + + + + + + + Errors raised by the treeland_window_overlap_checker_v1 + interface. + + + + + + + + Destroy the treeland_window_overlap_checker_v1 object. + The compositor stops monitoring the region registered + with this checker. + + + + + + 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. + + After this request the compositor should 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. + + + + diff --git a/public/README.md b/public/README.md index cc57cfc..7ba934a 100644 --- a/public/README.md +++ b/public/README.md @@ -5,7 +5,7 @@ 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` (deprecated), `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 `treeland_dde_active_v1` interface and the `set_xwindow_position_relative` request are deprecated and non-functional, superseded by `dde/treeland-active-notify-unstable-v1.xml` and `dde/treeland-xwindow-control-unstable-v1.xml` | +| `treeland-dde-shell-v1.xml` | `treeland_dde_shell_v1` | `treeland_dde_shell_manager_v1`, `treeland_window_overlap_checker` (deprecated), `treeland_dde_shell_surface_v1`, `treeland_dde_active_v1` (deprecated), `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 `treeland_dde_active_v1` and `treeland_window_overlap_checker` interfaces and the `set_xwindow_position_relative` request are deprecated and non-functional, superseded by `dde/treeland-active-notify-unstable-v1.xml`, `dde/treeland-window-overlap-checker-unstable-v1.xml`, and `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,13 +20,14 @@ 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` and the `treeland_dde_active_v1` interface (with its `get_treeland_dde_active` manager request) are now documented as deprecated and non-functional: they have no effect and no events are ever emitted. The file itself stays in place for now; the whole `treeland-dde-shell` protocol is slated for removal in a future release. +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 now documented as deprecated and non-functional: they have no effect and no events are ever emitted. The file itself stays in place for now; the whole `treeland-dde-shell` protocol is slated for removal in a future release. -They are superseded by two new independent protocols in `dde/`: +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_enter`/`activity_leave` events carry a `reason` enum (renamed from `active_in`/`active_out`), plus `start_drag`/`drop` events. +- `treeland-window-overlap-checker-unstable-v1.xml` (`treeland_window_overlap_checker_manager_v1`, `treeland_window_overlap_checker_v1`): window overlap monitoring — edge-anchored region registration (`set_region`) with `enter`/`leave` state events and explicit error reporting; the checker interface is renamed from `treeland_window_overlap_checker`, gaining the `_v1` suffix, and the region-setting request is renamed from `update` to `set_region`. -Consumers should bind the new globals instead of using the deprecated manager request and interface; the deprecated request and interface 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 8924183..41d765e 100644 --- a/public/README.zh_CN.md +++ b/public/README.zh_CN.md @@ -5,7 +5,7 @@ | 文件 | 协议 | 接口 | 用途 | |------|----------|-----------|---------| | `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 角色、重叠检测、活跃事件、多任务视图、窗口选取、锁屏；`treeland_dde_active_v1` 接口及 `set_xwindow_position_relative` 请求已废弃且不可用，由 `dde/treeland-active-notify-unstable-v1.xml` 和 `dde/treeland-xwindow-control-unstable-v1.xml` 取代 | +| `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 角色、重叠检测、活跃事件、多任务视图、窗口选取、锁屏；`treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口及 `set_xwindow_position_relative` 请求已废弃且不可用，由 `dde/treeland-active-notify-unstable-v1.xml`、`dde/treeland-window-overlap-checker-unstable-v1.xml` 和 `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,11 +21,12 @@ #### `treeland-dde-shell-v1.xml` -管理器的 `set_xwindow_position_relative` 请求及 `treeland_dde_active_v1` 接口（含其创建请求 `get_treeland_dde_active`）现标注为已废弃且不可用：请求无任何效果，也不会发出任何事件。文件暂保留原位；整个 `treeland-dde-shell` 协议计划在未来版本彻底移除。 +管理器的 `set_xwindow_position_relative` 请求及 `treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口（含其创建请求 `get_treeland_dde_active`、`get_window_overlap_checker`）现标注为已废弃且不可用：请求无任何效果，也不会发出任何事件。文件暂保留原位；整个 `treeland-dde-shell` 协议计划在未来版本彻底移除。 -二者由 `dde/` 下两个新的独立协议取代： +二者由 `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`）：座席活跃通知——`get_active_notify` 请求创建按座席的通知对象，其 `activity_enter`/`activity_leave` 事件携带 `reason` 枚举（由 `active_in`/`active_out` 更名），并新增 `start_drag`/`drop` 事件。 +- `treeland-active-notify-unstable-v1.xml`（`treeland_active_notify_manager_v1`、`treeland_active_notify_v1`）：Seat 活跃通知——`get_active_notify` 请求创建按 Seat 限定的通知对象，其 `activity_enter`/`activity_leave` 事件携带 `reason` 枚举（由 `active_in`/`active_out` 更名），并新增 `start_drag`/`drop` 事件。 +- `treeland-window-overlap-checker-unstable-v1.xml`（`treeland_window_overlap_checker_manager_v1`、`treeland_window_overlap_checker_v1`）：窗口重叠监测——沿输出边缘的区域注册（`set_region`）与 `enter`/`leave` 状态事件及显式错误回报；checker 接口由 `treeland_window_overlap_checker` 更名并补上 `_v1` 后缀，设区域请求由 `update` 更名为 `set_region`。 消费者应改绑新的全局对象，不得在新代码中使用已废弃的请求与接口。 diff --git a/public/treeland-dde-shell-v1.xml b/public/treeland-dde-shell-v1.xml index bd6739a..9a2e632 100644 --- a/public/treeland-dde-shell-v1.xml +++ b/public/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's requests have no effect and no events are ever + emitted. + + Superseded by the treeland_window_overlap_checker_manager_v1 + global of the treeland-window-overlap-checker-unstable-v1 + protocol. + @@ -94,7 +102,16 @@ - A treeland_window_overlap_checker object monitors whether the detected window region overlaps with xdg-shell toplevels. + Deprecated: this interface is non-functional. All requests + have no effect and no events are ever emitted. New code must + not use it. + + Superseded by the treeland_window_overlap_checker_manager_v1 + global of the treeland-window-overlap-checker-unstable-v1 + protocol. + + This interface will be removed along with the whole protocol + in a future release. From 506f2151a8a0a2bb53faaff8af04fcb492c54e22 Mon Sep 17 00:00:00 2001 From: rewine Date: Tue, 15 Sep 2026 11:42:48 +0800 Subject: [PATCH 03/12] fix(protocol): use must instead of should for privilege rejection Log: Strengthen the non-privileged bind rejection wording from should to must in active-notify and window-overlap-checker, since it is a security requirement Influence: 1. Grep both XML files for "must reject bind" and confirm 2 occurrences each 2. Run xmllint on both files to confirm well-formedness --- dde/treeland-active-notify-unstable-v1.xml | 93 +++++++++++++------ ...and-window-overlap-checker-unstable-v1.xml | 35 ++++++- public/README.md | 4 +- public/README.zh_CN.md | 4 +- public/treeland-dde-shell-v1.xml | 24 +++-- 5 files changed, 118 insertions(+), 42 deletions(-) diff --git a/dde/treeland-active-notify-unstable-v1.xml b/dde/treeland-active-notify-unstable-v1.xml index 215db67..d494022 100644 --- a/dde/treeland-active-notify-unstable-v1.xml +++ b/dde/treeland-active-notify-unstable-v1.xml @@ -19,7 +19,7 @@ SPDX-License-Identifier: MIT and wheel activity, and drag and drop lifecycle events, scoped to a given seat. - The compositor should reject bind attempts from non-privileged + The compositor must reject bind attempts from non-privileged clients. The terms "must", "must not", "should", and "may" in this document @@ -33,7 +33,7 @@ SPDX-License-Identifier: MIT one seat; clients observing several seats create several notifiers. - The compositor should reject bind attempts from non-privileged + The compositor must reject bind attempts from non-privileged clients. @@ -58,26 +58,46 @@ SPDX-License-Identifier: MIT A notifier object reports seat activity that the compositor - detects. Activity is reported as enter/leave transitions - tagged with the source that triggered them. - - enter means the source became active (for example a pointer - button was pressed or a wheel was scrolled in the positive - direction); leave means the source became inactive (the - button was released or the wheel was scrolled in the negative - direction). The compositor sends these events only on the - transitions, not repeatedly while a state persists. - - The start_drag and drop events report the start and end of a - drag and drop operation on the seat. + detects. Activity is reported as enter/leave events tagged + with the source that triggered them. + + The mouse and wheel sources have different semantics: + + For mouse, enter and leave report the aggregate state of + the left pointer button only. activity_enter is sent when + the left button is pressed, activity_leave when it is + released. Other pointer buttons do not generate these + events. The compositor sends enter and leave as matched + pairs: it must not send a second enter before the matching + leave, nor a leave when the left button is not pressed. + + For wheel, enter and leave are discrete per-event pulses, + not a persistent state. activity_enter is sent for each + wheel event whose angle delta is positive, and + activity_leave for each whose angle delta is negative; the + compositor may send several enter (or several leave) events + in a row without an intervening opposite event. Clients + must treat each wheel event independently and must not + infer a lasting state from a single enter or leave. + + The start_drag, drop, and drag_cancelled events report the + lifecycle of a drag and drop operation on the seat. + start_drag is sent when the operation begins. Exactly one + terminal event follows each start_drag: drop when the + operation completes with a successful drop, or + drag_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 start_drag. The input source that triggered an activity event. Used - by the activity_enter and activity_leave events. + by the activity_enter and activity_leave events. See the + interface description for the per-source semantics. - + @@ -91,20 +111,24 @@ SPDX-License-Identifier: MIT - Sent when the activity source identified by reason - becomes active: for mouse, when a pointer button is - pressed; for wheel, when the wheel is scrolled in the - positive direction. + For mouse, sent when the left pointer button is + pressed. For wheel, sent for each wheel event whose + angle delta is positive; the compositor may send + several in a row without an intervening activity_leave. + See the interface description for the per-source + semantics. - Sent when the activity source identified by reason - becomes inactive: for mouse, when the pressed pointer - button is released; for wheel, when the wheel is - scrolled in the negative direction. + For mouse, sent when the left pointer button is + released. For wheel, sent for each wheel event whose + angle delta is negative; the compositor may send + several in a row without an intervening activity_enter. + See the interface description for the per-source + semantics. @@ -112,14 +136,27 @@ SPDX-License-Identifier: MIT Sent when a drag and drop operation starts on the seat - bound to this notifier. + bound to this notifier. Exactly one terminal event + (drop or drag_cancelled) follows each start_drag. - - Sent when a drag and drop operation completes with a - drop on the seat bound to this notifier. + + Terminal event for a drag and drop operation that + completes with a successful drop on the seat bound to + this notifier. No further drag events are sent after + drop until the next start_drag. + + + + + + Terminal event for a drag and drop operation that ends + without a drop, for example because the drag was + cancelled or the drag source destroyed. No further drag + events are sent after drag_cancelled until the next + start_drag. diff --git a/dde/treeland-window-overlap-checker-unstable-v1.xml b/dde/treeland-window-overlap-checker-unstable-v1.xml index 244db5a..28e5c4f 100644 --- a/dde/treeland-window-overlap-checker-unstable-v1.xml +++ b/dde/treeland-window-overlap-checker-unstable-v1.xml @@ -19,7 +19,7 @@ SPDX-License-Identifier: MIT with any xdg-shell toplevel window, for example to implement smart panel hiding. - The compositor should reject bind attempts from non-privileged + The compositor must reject bind attempts from non-privileged clients. The terms "must", "must not", "should", and "may" in this document @@ -33,7 +33,7 @@ SPDX-License-Identifier: MIT one region; clients monitoring several regions create several checkers. - The compositor should reject bind attempts from non-privileged + The compositor must reject bind attempts from non-privileged clients. @@ -71,6 +71,17 @@ SPDX-License-Identifier: MIT 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 checker 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 checker then + becomes inert: it has no monitored region and sends no + further enter or leave events. The checker 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. @@ -113,6 +124,11 @@ SPDX-License-Identifier: MIT unknown anchor value and invalid_size when width or height is not positive. + The output becomes the output associated with the + checker, 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 should evaluate the current overlap state and send the matching enter or leave event. @@ -138,5 +154,20 @@ SPDX-License-Identifier: MIT 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 + checker then becomes inert: it has no monitored region + and sends no further enter or leave events. + + The checker 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/README.md b/public/README.md index 7ba934a..467e1f0 100644 --- a/public/README.md +++ b/public/README.md @@ -20,11 +20,11 @@ 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` 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 now documented as deprecated and non-functional: they have no effect and no events are ever emitted. The file itself stays in place for now; the whole `treeland-dde-shell` protocol is slated for removal in a future release. +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 now documented as 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). The file itself stays in place for now; the whole `treeland-dde-shell` protocol is slated for removal in a future release. 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_enter`/`activity_leave` events carry a `reason` enum (renamed from `active_in`/`active_out`), plus `start_drag`/`drop` events. +- `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_enter`/`activity_leave` events carry a `reason` enum (renamed from `active_in`/`active_out`, with mouse tracking the left button state and wheel as per-event pulses), plus `start_drag`/`drop`/`drag_cancelled` lifecycle events (the latter covering drag cancellation). - `treeland-window-overlap-checker-unstable-v1.xml` (`treeland_window_overlap_checker_manager_v1`, `treeland_window_overlap_checker_v1`): window overlap monitoring — edge-anchored region registration (`set_region`) with `enter`/`leave` state events and explicit error reporting; the checker interface is renamed from `treeland_window_overlap_checker`, gaining the `_v1` suffix, and the region-setting request is renamed from `update` to `set_region`. 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. diff --git a/public/README.zh_CN.md b/public/README.zh_CN.md index 41d765e..5dc6635 100644 --- a/public/README.zh_CN.md +++ b/public/README.zh_CN.md @@ -21,11 +21,11 @@ #### `treeland-dde-shell-v1.xml` -管理器的 `set_xwindow_position_relative` 请求及 `treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口（含其创建请求 `get_treeland_dde_active`、`get_window_overlap_checker`）现标注为已废弃且不可用：请求无任何效果，也不会发出任何事件。文件暂保留原位；整个 `treeland-dde-shell` 协议计划在未来版本彻底移除。 +管理器的 `set_xwindow_position_relative` 请求及 `treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口（含其创建请求 `get_treeland_dde_active`、`get_window_overlap_checker`）现标注为已废弃且不可用：请求无任何效果，也不会发出任何事件（`destroy` 请求仍然可用，客户端可借此释放对象）。文件暂保留原位；整个 `treeland-dde-shell` 协议计划在未来版本彻底移除。 二者由 `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_enter`/`activity_leave` 事件携带 `reason` 枚举（由 `active_in`/`active_out` 更名），并新增 `start_drag`/`drop` 事件。 +- `treeland-active-notify-unstable-v1.xml`（`treeland_active_notify_manager_v1`、`treeland_active_notify_v1`）：Seat 活跃通知——`get_active_notify` 请求创建按 Seat 限定的通知对象，其 `activity_enter`/`activity_leave` 事件携带 `reason` 枚举（由 `active_in`/`active_out` 更名；鼠标跟踪左键状态，滚轮为逐事件脉冲），并新增 `start_drag`/`drop`/`drag_cancelled` 生命周期事件（后者覆盖拖拽取消）。 - `treeland-window-overlap-checker-unstable-v1.xml`（`treeland_window_overlap_checker_manager_v1`、`treeland_window_overlap_checker_v1`）：窗口重叠监测——沿输出边缘的区域注册（`set_region`）与 `enter`/`leave` 状态事件及显式错误回报；checker 接口由 `treeland_window_overlap_checker` 更名并补上 `_v1` 后缀，设区域请求由 `update` 更名为 `set_region`。 消费者应改绑新的全局对象，不得在新代码中使用已废弃的请求与接口。 diff --git a/public/treeland-dde-shell-v1.xml b/public/treeland-dde-shell-v1.xml index 9a2e632..c00933b 100644 --- a/public/treeland-dde-shell-v1.xml +++ b/public/treeland-dde-shell-v1.xml @@ -22,8 +22,8 @@ Deprecated: this request is non-functional. The created - object's requests have no effect and no events are ever - emitted. + object never emits events, and its requests have no + effect apart from destroy. Superseded by the treeland_window_overlap_checker_manager_v1 global of the treeland-window-overlap-checker-unstable-v1 @@ -47,8 +47,8 @@ Deprecated: this request is non-functional. The created - object's requests have no effect and no events are ever - emitted. + 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 @@ -102,9 +102,9 @@ - Deprecated: this interface is non-functional. All requests - have no effect and no events are ever emitted. New code must - not use it. + 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_window_overlap_checker_manager_v1 global of the treeland-window-overlap-checker-unstable-v1 @@ -265,7 +265,15 @@ - 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. + + This interface will be removed along with the whole protocol + in a future release. From 768a2a45563ad92e56434bd245149a3b98f9222d Mon Sep 17 00:00:00 2001 From: rewine Date: Tue, 15 Sep 2026 15:27:53 +0800 Subject: [PATCH 04/12] feat: add treeland-compositor-action unstable-v1 protocol 1. Add treeland-compositor-action-unstable-v1: a single privileged treeland_compositor_action_v1 global whose trigger(action) request fires one-shot window-independent compositor actions (workspace switching, show-desktop, multitask overview, screen zoom, FPS overlay, lockscreen, shutdown menu with focused variants, user switch), values 1-30 in a protocol-specific value space deliberately not aligned with treeland_shortcut_manager_v3 2. Window-level and task-switch actions are intentionally excluded and remain reachable only as shortcuts, per the KWin shell/window action split 3. Register the protocol in CMakeLists and add it to the dde READMEs Log: New compositor-action protocol replaces the multitaskview and lockscreen dde-shell interfaces and absorbs the session-control draft Influence: 1. Install the package and verify the new XML file lands in the treeland-protocols data dir 2. Run wayland-scanner client-header and private-code on the new XML file to confirm parsing 3. Check the dde READMEs list the new protocol 4. Reconfigure cmake and confirm the build succeeds with the updated DDE file list --- CMakeLists.txt | 1 + dde/README.md | 1 + dde/README.zh_CN.md | 1 + ...treeland-compositor-action-unstable-v1.xml | 173 ++++++++++++++++++ 4 files changed, 176 insertions(+) create mode 100644 dde/treeland-compositor-action-unstable-v1.xml diff --git a/CMakeLists.txt b/CMakeLists.txt index 8647284..c5172ad 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -26,6 +26,7 @@ set(TREELAND_PROTOCOL_DDE_XML_FILES 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 diff --git a/dde/README.md b/dde/README.md index e800e3e..e49fbe2 100644 --- a/dde/README.md +++ b/dde/README.md @@ -9,6 +9,7 @@ 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 | diff --git a/dde/README.zh_CN.md b/dde/README.zh_CN.md index a1630de..c881693 100644 --- a/dde/README.zh_CN.md +++ b/dde/README.zh_CN.md @@ -9,6 +9,7 @@ | `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` | 逐输出壁纸配置，支持图片/视频来源 | 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. + + + + + From 7e554b8b7168749847dc934c588fd5857bfac417 Mon Sep 17 00:00:00 2001 From: rewine Date: Tue, 15 Sep 2026 15:29:27 +0800 Subject: [PATCH 05/12] deprecate: move treeland-show-desktop to deprecated/ Superseded by the show_desktop action (value 15) of the treeland_compositor_action_v1 global of treeland-compositor-action-unstable-v1.xml: the replacement is a one-shot fire-and-forget trigger without state observation, which the documented breaking-change entry details for consumers. Log: One-shot compositor-action protocol covers show-desktop toggling; the old explicit-state protocol moves to deprecated/ Influence: 1. Verify deprecated/treeland-show-desktop-unstable-v1.xml is still installed (TREELAND_PROTOCOLS_INSTALL_DEPRECATED is ON) 2. Confirm dde/treeland-show-desktop-unstable-v1.xml no longer exists and CMakeLists references the deprecated path 3. Check the dde READMEs contain the 0.7.0 breaking-change entry and no longer list the protocol in the table --- CMakeLists.txt | 2 +- dde/README.md | 11 ++++++++++- dde/README.zh_CN.md | 11 ++++++++++- .../treeland-show-desktop-unstable-v1.xml | 0 4 files changed, 21 insertions(+), 3 deletions(-) rename {dde => deprecated}/treeland-show-desktop-unstable-v1.xml (100%) diff --git a/CMakeLists.txt b/CMakeLists.txt index c5172ad..ec39c7f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -30,7 +30,6 @@ set(TREELAND_PROTOCOL_DDE_XML_FILES 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 @@ -61,6 +60,7 @@ 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-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 e49fbe2..ba5d5a9 100644 --- a/dde/README.md +++ b/dde/README.md @@ -13,7 +13,6 @@ For DDE desktop components. Installed via `TREELAND_PROTOCOL_DDE_XML_FILES`. | `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 | @@ -29,6 +28,16 @@ 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. + ### 0.6.0 #### `treeland-output-manager-v1.xml` diff --git a/dde/README.zh_CN.md b/dde/README.zh_CN.md index c881693..20e56e5 100644 --- a/dde/README.zh_CN.md +++ b/dde/README.zh_CN.md @@ -13,7 +13,6 @@ | `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 限定的指针按键/滚轮进入/离开活跃状态及拖拽/放下的生命周期事件 | @@ -29,6 +28,16 @@ `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 在迁移期间仍会安装，但不得用于新代码。 + ### 0.6.0 #### `treeland-output-manager-v1.xml` 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 From 3df27358d14c1033e7b5caabe82e2b5b95c70b73 Mon Sep 17 00:00:00 2001 From: rewine Date: Tue, 15 Sep 2026 15:29:54 +0800 Subject: [PATCH 06/12] docs(dde-shell): deprecate multitaskview and lockscreen interfaces 1. Mark the treeland_multitaskview_v1 and treeland_lockscreen_v1 interfaces and their creating manager requests deprecated but still functional, superseded by the compositor actions of dde/treeland-compositor-action-unstable-v1.xml 2. Update the public READMEs with the deprecation note in the protocol table and the 0.7.0 breaking-change entry Log: Compositor-action protocol covers multitask toggle and lockscreen operations; the dde-shell interfaces are deprecated pending removal Influence: 1. Run wayland-scanner client-header on treeland-dde-shell-v1.xml to confirm parsing 2. Grep the public READMEs for the multitaskview/lockscreen deprecation note 3. Confirm the 0.7.0 entry lists the replacement actions --- public/README.md | 4 +++- public/README.zh_CN.md | 4 +++- public/treeland-dde-shell-v1.xml | 27 +++++++++++++++++++++++++-- 3 files changed, 31 insertions(+), 4 deletions(-) diff --git a/public/README.md b/public/README.md index 467e1f0..2324fe0 100644 --- a/public/README.md +++ b/public/README.md @@ -5,7 +5,7 @@ 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` (deprecated), `treeland_dde_shell_surface_v1`, `treeland_dde_active_v1` (deprecated), `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 `treeland_dde_active_v1` and `treeland_window_overlap_checker` interfaces and the `set_xwindow_position_relative` request are deprecated and non-functional, superseded by `dde/treeland-active-notify-unstable-v1.xml`, `dde/treeland-window-overlap-checker-unstable-v1.xml`, and `dde/treeland-xwindow-control-unstable-v1.xml` | +| `treeland-dde-shell-v1.xml` | `treeland_dde_shell_v1` | `treeland_dde_shell_manager_v1`, `treeland_window_overlap_checker` (deprecated), `treeland_dde_shell_surface_v1`, `treeland_dde_active_v1` (deprecated), `treeland_multitaskview_v1` (deprecated), `treeland_window_picker_v1`, `treeland_lockscreen_v1` (deprecated) | DDE shell integration: surface roles, overlap detection, active events, multitask view, window picker, lockscreen; the `treeland_dde_active_v1` and `treeland_window_overlap_checker` interfaces and the `set_xwindow_position_relative` request are deprecated and non-functional, superseded by `dde/treeland-active-notify-unstable-v1.xml`, `dde/treeland-window-overlap-checker-unstable-v1.xml`, and `dde/treeland-xwindow-control-unstable-v1.xml`; the `treeland_multitaskview_v1` and `treeland_lockscreen_v1` interfaces (with their creating requests) are deprecated but still functional, superseded by the actions of `dde/treeland-compositor-action-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 @@ -27,6 +27,8 @@ They are superseded by three new independent protocols in `dde/`: - `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_enter`/`activity_leave` events carry a `reason` enum (renamed from `active_in`/`active_out`, with mouse tracking the left button state and wheel as per-event pulses), plus `start_drag`/`drop`/`drag_cancelled` lifecycle events (the latter covering drag cancellation). - `treeland-window-overlap-checker-unstable-v1.xml` (`treeland_window_overlap_checker_manager_v1`, `treeland_window_overlap_checker_v1`): window overlap monitoring — edge-anchored region registration (`set_region`) with `enter`/`leave` state events and explicit error reporting; the checker 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 now documented as deprecated but still functional, superseded by the corresponding actions (`toggle_multitask_view`/`open_multitask_view`/`close_multitask_view` and `lockscreen`/`shutdown_menu`/`show_user_switch`) of the new privileged `dde/treeland-compositor-action-unstable-v1.xml` protocol. + 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 5dc6635..8c5f06b 100644 --- a/public/README.zh_CN.md +++ b/public/README.zh_CN.md @@ -5,7 +5,7 @@ | 文件 | 协议 | 接口 | 用途 | |------|----------|-----------|---------| | `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 角色、重叠检测、活跃事件、多任务视图、窗口选取、锁屏；`treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口及 `set_xwindow_position_relative` 请求已废弃且不可用，由 `dde/treeland-active-notify-unstable-v1.xml`、`dde/treeland-window-overlap-checker-unstable-v1.xml` 和 `dde/treeland-xwindow-control-unstable-v1.xml` 取代 | +| `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 角色、重叠检测、活跃事件、多任务视图、窗口选取、锁屏；`treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口及 `set_xwindow_position_relative` 请求已废弃且不可用，由 `dde/treeland-active-notify-unstable-v1.xml`、`dde/treeland-window-overlap-checker-unstable-v1.xml` 和 `dde/treeland-xwindow-control-unstable-v1.xml` 取代；`treeland_multitaskview_v1` 和 `treeland_lockscreen_v1` 接口（含其创建请求）已废弃但仍可用，由 `dde/treeland-compositor-action-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 | @@ -28,6 +28,8 @@ - `treeland-active-notify-unstable-v1.xml`（`treeland_active_notify_manager_v1`、`treeland_active_notify_v1`）：Seat 活跃通知——`get_active_notify` 请求创建按 Seat 限定的通知对象，其 `activity_enter`/`activity_leave` 事件携带 `reason` 枚举（由 `active_in`/`active_out` 更名；鼠标跟踪左键状态，滚轮为逐事件脉冲），并新增 `start_drag`/`drop`/`drag_cancelled` 生命周期事件（后者覆盖拖拽取消）。 - `treeland-window-overlap-checker-unstable-v1.xml`（`treeland_window_overlap_checker_manager_v1`、`treeland_window_overlap_checker_v1`）：窗口重叠监测——沿输出边缘的区域注册（`set_region`）与 `enter`/`leave` 状态事件及显式错误回报；checker 接口由 `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 diff --git a/public/treeland-dde-shell-v1.xml b/public/treeland-dde-shell-v1.xml index c00933b..e1100df 100644 --- a/public/treeland-dde-shell-v1.xml +++ b/public/treeland-dde-shell-v1.xml @@ -60,7 +60,12 @@ - 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 remains functional during the deprecation period + but must not be used in new code. @@ -74,7 +79,12 @@ - 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 remains functional during the deprecation period + but must not be used in new code. @@ -310,6 +320,13 @@ 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 + remains functional during the deprecation period but must not + be used in new code. @@ -354,6 +371,12 @@ 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 remains functional during the deprecation period + but must not be used in new code. From b6c91c9eea8fb994b96f1b5f279dd5650bf4fdb9 Mon Sep 17 00:00:00 2001 From: rewine Date: Tue, 15 Sep 2026 15:48:14 +0800 Subject: [PATCH 07/12] feat: add treeland-dde-shell unstable-v2 protocol 1. Add treeland-dde-shell-unstable-v2.xml: manager_v2 plus surface_v2, reduced to the surface role functionality of treeland-dde-shell-v1 with an improved wire design - 0-based role enum, the three skip requests merged into a set_skip_flags bitfield (fixing the muti typo), int y_offset for set_auto_placement, an already_shell_surface error, and documented placement-mode mutual exclusivity 2. Register the protocol in CMakeLists and add it to the public READMEs Log: Design a clean v2 successor for the surface role instead of a compatibility carry-over, per the deprecation of treeland-dde-shell-v1 Influence: 1. Install the package and verify the new XML file lands in the treeland-protocols data dir 2. Run wayland-scanner client-header and private-code on the new XML file to confirm parsing 3. Check the public READMEs list the new protocol 4. Reconfigure cmake and confirm the build succeeds with the updated public file list --- CMakeLists.txt | 1 + public/README.md | 1 + public/README.zh_CN.md | 1 + public/treeland-dde-shell-unstable-v2.xml | 194 ++++++++++++++++++++++ 4 files changed, 197 insertions(+) create mode 100644 public/treeland-dde-shell-unstable-v2.xml diff --git a/CMakeLists.txt b/CMakeLists.txt index ec39c7f..23eb63c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -15,6 +15,7 @@ include(CMakePackageConfigHelpers) set(TREELAND_PROTOCOL_XML_FILES public/treeland-dde-shell-v1.xml public/treeland-window-transition-unstable-v1.xml + public/treeland-dde-shell-unstable-v2.xml public/treeland-appearance-unstable-v1.xml public/treeland-decoration-unstable-v1.xml ) diff --git a/public/README.md b/public/README.md index 2324fe0..c1cdaf3 100644 --- a/public/README.md +++ b/public/README.md @@ -6,6 +6,7 @@ For general application developers. Installed via `TREELAND_PROTOCOL_XML_FILES`. |------|----------|-----------|---------| | `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` (deprecated), `treeland_dde_shell_surface_v1`, `treeland_dde_active_v1` (deprecated), `treeland_multitaskview_v1` (deprecated), `treeland_window_picker_v1`, `treeland_lockscreen_v1` (deprecated) | DDE shell integration: surface roles, overlap detection, active events, multitask view, window picker, lockscreen; the `treeland_dde_active_v1` and `treeland_window_overlap_checker` interfaces and the `set_xwindow_position_relative` request are deprecated and non-functional, superseded by `dde/treeland-active-notify-unstable-v1.xml`, `dde/treeland-window-overlap-checker-unstable-v1.xml`, and `dde/treeland-xwindow-control-unstable-v1.xml`; the `treeland_multitaskview_v1` and `treeland_lockscreen_v1` interfaces (with their creating requests) are deprecated but still functional, superseded by the actions of `dde/treeland-compositor-action-unstable-v1.xml` | +| `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, position it in global coordinates or auto-place it below the cursor, and declare switcher/dock-preview/multitask-view listing preferences via a skip bitfield | | `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 diff --git a/public/README.zh_CN.md b/public/README.zh_CN.md index 8c5f06b..630edf6 100644 --- a/public/README.zh_CN.md +++ b/public/README.zh_CN.md @@ -6,6 +6,7 @@ |------|----------|-----------|---------| | `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 角色、重叠检测、活跃事件、多任务视图、窗口选取、锁屏；`treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口及 `set_xwindow_position_relative` 请求已废弃且不可用，由 `dde/treeland-active-notify-unstable-v1.xml`、`dde/treeland-window-overlap-checker-unstable-v1.xml` 和 `dde/treeland-xwindow-control-unstable-v1.xml` 取代；`treeland_multitaskview_v1` 和 `treeland_lockscreen_v1` 接口（含其创建请求）已废弃但仍可用，由 `dde/treeland-compositor-action-unstable-v1.xml` 的动作取代 | +| `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 预览/多任务视图的列表偏好 | | `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 | diff --git a/public/treeland-dde-shell-unstable-v2.xml b/public/treeland-dde-shell-unstable-v2.xml new file mode 100644 index 0000000..af097ee --- /dev/null +++ b/public/treeland-dde-shell-unstable-v2.xml @@ -0,0 +1,194 @@ + + + + + + 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 is the v2 successor of treeland-dde-shell-v1, reduced + to the surface role functionality: it 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 in global coordinates. + + The other v1 interfaces are superseded by dedicated protocols or + removed: window overlap monitoring moved to + treeland-window-overlap-checker-unstable-v1, seat activity + notification to treeland-active-notify-unstable-v1, XWayland window + placement to treeland-xwindow-control-unstable-v1, and the + multitaskview, lockscreen, and session operations to + treeland-compositor-action-unstable-v1 (all in dde/). The window + picker interface is removed without a replacement; a dedicated + protocol may be designed in the future. + + 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_surface_position + places the surface at fixed global coordinates, while + set_auto_placement asks the compositor to place the surface + below the cursor and keep it within the output bounds. The + most recently sent request determines the placement mode. + + + + + 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. + + + + + + + Move the surface to the given coordinates. Coordinates are + in the global space spanning all outputs; for example + 50,50 on a 1920,0+1920x1080 output is 1970,50 in global + coordinates. + + + + + + + + Ask the compositor to place this surface near the current + cursor position: horizontally aligned with the cursor and + vertically offset by y_offset from the bottom of the + cursor. The compositor keeps the surface within the + bounds of the output under the cursor. + + Sending this request switches the placement mode to + automatic; see the interface description for the + interaction with set_surface_position. + + + + + + + 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. + + + + + From eb4687d249fe53150977364d77a70750f34d6678 Mon Sep 17 00:00:00 2001 From: rewine Date: Tue, 15 Sep 2026 15:49:04 +0800 Subject: [PATCH 08/12] deprecate: move treeland-dde-shell-v1 to deprecated/ Superseded by public/treeland-dde-shell-unstable-v2.xml (surface role, redesigned wire) together with the dedicated protocols in dde/; the window_picker interface is removed without a replacement. Documented in the 0.7.0 breaking-change entry with wire-level differences and consumer migration guidance. Closes: https://github.com/linuxdeepin/treeland/issues/1205 Log: Split dde-shell-v1 by audience; v2 keeps only the surface role with an improved design Influence: 1. Verify deprecated/treeland-dde-shell-v1.xml is still installed (TREELAND_PROTOCOLS_INSTALL_DEPRECATED is ON) 2. Confirm public/treeland-dde-shell-v1.xml no longer exists and CMakeLists references the deprecated path 3. Check the public READMEs contain the 0.7.0 breaking-change entry and the v1 table row is removed --- CMakeLists.txt | 2 +- {public => deprecated}/treeland-dde-shell-v1.xml | 0 public/README.md | 15 +++++++++++++-- public/README.zh_CN.md | 15 +++++++++++++-- 4 files changed, 27 insertions(+), 5 deletions(-) rename {public => deprecated}/treeland-dde-shell-v1.xml (100%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 23eb63c..bc612c9 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-dde-shell-unstable-v2.xml public/treeland-appearance-unstable-v1.xml @@ -61,6 +60,7 @@ 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 diff --git a/public/treeland-dde-shell-v1.xml b/deprecated/treeland-dde-shell-v1.xml similarity index 100% rename from public/treeland-dde-shell-v1.xml rename to deprecated/treeland-dde-shell-v1.xml diff --git a/public/README.md b/public/README.md index c1cdaf3..cbdff42 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` (deprecated), `treeland_dde_shell_surface_v1`, `treeland_dde_active_v1` (deprecated), `treeland_multitaskview_v1` (deprecated), `treeland_window_picker_v1`, `treeland_lockscreen_v1` (deprecated) | DDE shell integration: surface roles, overlap detection, active events, multitask view, window picker, lockscreen; the `treeland_dde_active_v1` and `treeland_window_overlap_checker` interfaces and the `set_xwindow_position_relative` request are deprecated and non-functional, superseded by `dde/treeland-active-notify-unstable-v1.xml`, `dde/treeland-window-overlap-checker-unstable-v1.xml`, and `dde/treeland-xwindow-control-unstable-v1.xml`; the `treeland_multitaskview_v1` and `treeland_lockscreen_v1` interfaces (with their creating requests) are deprecated but still functional, superseded by the actions of `dde/treeland-compositor-action-unstable-v1.xml` | | `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, position it in global coordinates or auto-place it below the cursor, and declare switcher/dock-preview/multitask-view listing preferences via a skip bitfield | | `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 | @@ -21,7 +20,19 @@ 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` 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 now documented as 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). 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 now deprecated and moved to `deprecated/`. It is superseded by `treeland-dde-shell-unstable-v2.xml` (in `public/`, reduced to the surface role functionality) together with the dedicated protocols listed above; the `treeland_window_picker_v1` interface is removed without a replacement, and a dedicated window-picking protocol may be designed in the future. + +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. `set_auto_placement` takes an `int` y_offset (v1 used `uint`), and the mutual exclusivity of the placement requests (`set_surface_position` vs `set_auto_placement`, 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 documented as 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. diff --git a/public/README.zh_CN.md b/public/README.zh_CN.md index 630edf6..2c7d96c 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 角色、重叠检测、活跃事件、多任务视图、窗口选取、锁屏；`treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口及 `set_xwindow_position_relative` 请求已废弃且不可用，由 `dde/treeland-active-notify-unstable-v1.xml`、`dde/treeland-window-overlap-checker-unstable-v1.xml` 和 `dde/treeland-xwindow-control-unstable-v1.xml` 取代；`treeland_multitaskview_v1` 和 `treeland_lockscreen_v1` 接口（含其创建请求）已废弃但仍可用，由 `dde/treeland-compositor-action-unstable-v1.xml` 的动作取代 | | `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 预览/多任务视图的列表偏好 | | `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 | @@ -22,7 +21,19 @@ #### `treeland-dde-shell-v1.xml` -管理器的 `set_xwindow_position_relative` 请求及 `treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口（含其创建请求 `get_treeland_dde_active`、`get_window_overlap_checker`）现标注为已废弃且不可用：请求无任何效果，也不会发出任何事件（`destroy` 请求仍然可用，客户端可借此释放对象）。文件暂保留原位；整个 `treeland-dde-shell` 协议计划在未来版本彻底移除。 +整个文件现已废弃并移至 `deprecated/`。由 `treeland-dde-shell-unstable-v2.xml`（在 `public/`，仅保留 surface 角色功能）连同上述专用协议取代；`treeland_window_picker_v1` 接口无替代直接移除，未来可能设计专用协议。 + +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_auto_placement` 的 y_offset 改为 `int`（v1 为 `uint`），并明确两种放置请求（`set_surface_position` 与 `set_auto_placement`）的互斥关系（最近发送的请求生效）。 +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` 回报，线缆语义不变。 From c04ae92d7d5c154edb86e700e05ec0107808129d Mon Sep 17 00:00:00 2001 From: rewine Date: Tue, 15 Sep 2026 16:36:28 +0800 Subject: [PATCH 09/12] fix: address review feedback on overlap-checker and docs 1. Bump project version 0.6.0 to 0.7.0 to match the documented breaking-change release 2. Add 0.7.0 breaking-change entry to the dde READMEs covering the active-notify, window-overlap-checker, and compositor-action replacement protocols for the deprecated dde-shell interfaces 3. Strengthen the overlap-checker set_region contract: change should to must for sending the initial enter/leave event after set_region, so clients can rely on the initial state notification 4. Define the anchor non-thickness dimension semantics: the dimension along the anchored edge is ignored (full output width/height is used); only the thickness dimension matters 5. Document the client-side wl_output lifetime rule: the client may release the wl_output proxy after set_region returns; the compositor holds its own reference Log: Address Sourcery and Copilot review comments on PR #113 Influence: 1. Grep CMakeLists.txt for VERSION 0.7.0 2. Check the dde READMEs contain a 0.7.0 treeland-dde-shell-v1.xml breaking-change subsection 3. Grep the overlap-checker XML for "must evaluate" and confirm no "should evaluate" remains 4. Read the anchor enum description and confirm the non-thickness dimension rule is stated 5. Read the interface description and confirm the wl_output proxy release rule is documented --- dde/README.md | 8 +++++ dde/README.zh_CN.md | 8 +++++ ...and-window-overlap-checker-unstable-v1.xml | 19 ++++++++-- public/treeland-dde-shell-unstable-v2.xml | 36 ++++++++----------- 4 files changed, 47 insertions(+), 24 deletions(-) diff --git a/dde/README.md b/dde/README.md index ba5d5a9..f1c2f12 100644 --- a/dde/README.md +++ b/dde/README.md @@ -38,6 +38,14 @@ Deprecated and moved to `deprecated/`; superseded by the `show_desktop` action o 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_enter`/`activity_leave` events carry a `reason` enum (renamed from `active_in`/`active_out`; mouse tracks the left-button state, wheel is a per-event pulse), plus `start_drag`/`drop`/`drag_cancelled` lifecycle events. +- `treeland_window_overlap_checker` (and its `get_window_overlap_checker` manager request) is non-functional and superseded by `treeland-window-overlap-checker-unstable-v1.xml` (`treeland_window_overlap_checker_manager_v1` / `treeland_window_overlap_checker_v1`): the checker 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) remain functional during the deprecation period and 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`). + ### 0.6.0 #### `treeland-output-manager-v1.xml` diff --git a/dde/README.zh_CN.md b/dde/README.zh_CN.md index 20e56e5..745caae 100644 --- a/dde/README.zh_CN.md +++ b/dde/README.zh_CN.md @@ -38,6 +38,14 @@ 消费者应将全局对象重新绑定为 `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_enter`/`activity_leave` 事件携带 `reason` 枚举（由 `active_in`/`active_out` 更名；鼠标跟踪左键状态，滚轮为逐事件脉冲），并新增 `start_drag`/`drop`/`drag_cancelled` 生命周期事件。 +- `treeland_window_overlap_checker`（含其创建请求 `get_window_overlap_checker`）已不可用，由 `treeland-window-overlap-checker-unstable-v1.xml`（`treeland_window_overlap_checker_manager_v1` / `treeland_window_overlap_checker_v1`）取代：checker 接口补上 `_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`）。 + ### 0.6.0 #### `treeland-output-manager-v1.xml` diff --git a/dde/treeland-window-overlap-checker-unstable-v1.xml b/dde/treeland-window-overlap-checker-unstable-v1.xml index 28e5c4f..b1dfa90 100644 --- a/dde/treeland-window-overlap-checker-unstable-v1.xml +++ b/dde/treeland-window-overlap-checker-unstable-v1.xml @@ -67,7 +67,7 @@ SPDX-License-Identifier: MIT 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 should evaluate + 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. @@ -82,6 +82,13 @@ SPDX-License-Identifier: MIT 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 checker remains + associated with that output until either the output is + destroyed (triggering output_removed) or a subsequent + set_region rebinds to a different output. @@ -91,6 +98,14 @@ SPDX-License-Identifier: MIT 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. @@ -129,7 +144,7 @@ SPDX-License-Identifier: MIT different output from a previous call (rebinding), for example after the previous output was removed. - After this request the compositor should evaluate the + After this request the compositor must evaluate the current overlap state and send the matching enter or leave event. diff --git a/public/treeland-dde-shell-unstable-v2.xml b/public/treeland-dde-shell-unstable-v2.xml index af097ee..d0f688c 100644 --- a/public/treeland-dde-shell-unstable-v2.xml +++ b/public/treeland-dde-shell-unstable-v2.xml @@ -14,21 +14,10 @@ SPDX-License-Identifier: MIT and must not rely on the current interface names, requests, events, or semantics remaining stable across releases. - This protocol is the v2 successor of treeland-dde-shell-v1, reduced - to the surface role functionality: it 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 in global coordinates. - - The other v1 interfaces are superseded by dedicated protocols or - removed: window overlap monitoring moved to - treeland-window-overlap-checker-unstable-v1, seat activity - notification to treeland-active-notify-unstable-v1, XWayland window - placement to treeland-xwindow-control-unstable-v1, and the - multitaskview, lockscreen, and session operations to - treeland-compositor-action-unstable-v1 (all in dde/). The window - picker interface is removed without a replacement; a dedicated - protocol may be designed in the future. + 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 in global coordinates or auto-place it below the cursor. The compositor must reject bind attempts from non-privileged clients. @@ -97,8 +86,10 @@ SPDX-License-Identifier: MIT Positioning requests are mutually exclusive: set_surface_position places the surface at fixed global coordinates, while set_auto_placement asks the compositor to place the surface - below the cursor and keep it within the output bounds. The - most recently sent request determines the placement mode. + below the cursor. The most recently sent request determines + the placement mode. In both modes the compositor may adjust + the final position to keep the surface accessible, for + example to keep its titlebar area within the output. @@ -149,7 +140,8 @@ SPDX-License-Identifier: MIT Move the surface to the given coordinates. Coordinates are in the global space spanning all outputs; for example 50,50 on a 1920,0+1920x1080 output is 1970,50 in global - coordinates. + coordinates. The compositor may adjust the position to + keep the surface accessible; see the interface description. @@ -157,11 +149,11 @@ SPDX-License-Identifier: MIT - Ask the compositor to place this surface near the current - cursor position: horizontally aligned with the cursor and + Ask the compositor to place this surface below the current + cursor position: horizontally centered on the cursor and vertically offset by y_offset from the bottom of the - cursor. The compositor keeps the surface within the - bounds of the output under the cursor. + cursor. The compositor may adjust the position to keep + the surface accessible; see the interface description. Sending this request switches the placement mode to automatic; see the interface description for the From db3e0049bcdfce409c50d38dddf911c75fc54900 Mon Sep 17 00:00:00 2001 From: rewine Date: Thu, 17 Sep 2026 14:04:10 +0800 Subject: [PATCH 10/12] refactor: rename active-notify events to notify style MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Merge activity_enter/activity_leave into activity_changed with reason and activity_state args 2. Merge start_drag/drop/drag_cancelled into drag_changed with drag_state enum 3. Sync dde/ and public/ READMEs with the new event and enum names Log: Renamed active-notify events and added state enums (unstable, unreleased protocol) Influence: 1. Rebuild protocol headers with wayland-scanner and confirm no warnings 2. Update any compositor/client code referencing the old event names 3. Verify mouse/wheel and drag events still report correct state transitions refactor: 重命名 active-notify 事件为通知风格 1. 将 activity_enter/activity_leave 合并为 activity_changed，携带 reason 与 activity_state 参数 2. 将 start_drag/drop/drag_cancelled 合并为 drag_changed，携带 drag_state 枚举 3. 同步 dde/ 与 public/ README 中的事件与枚举命名 Log: 重命名 active-notify 事件并新增状态枚举（unstable 未发布协议） Influence: 1. 用 wayland-scanner 重新生成头文件并确认无警告 2. 更新所有引用旧事件名的合成器/客户端代码 3. 验证鼠标/滚轮及拖拽事件仍正确报告状态迁移 --- dde/README.md | 2 +- dde/README.zh_CN.md | 2 +- dde/treeland-active-notify-unstable-v1.xml | 143 +++++++++++---------- public/README.md | 2 +- public/README.zh_CN.md | 2 +- 5 files changed, 78 insertions(+), 73 deletions(-) diff --git a/dde/README.md b/dde/README.md index f1c2f12..9eef85d 100644 --- a/dde/README.md +++ b/dde/README.md @@ -42,7 +42,7 @@ Consumers should rebind the global as `treeland_compositor_action_v1` and trigge 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_enter`/`activity_leave` events carry a `reason` enum (renamed from `active_in`/`active_out`; mouse tracks the left-button state, wheel is a per-event pulse), plus `start_drag`/`drop`/`drag_cancelled` lifecycle events. +- `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-window-overlap-checker-unstable-v1.xml` (`treeland_window_overlap_checker_manager_v1` / `treeland_window_overlap_checker_v1`): the checker 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) remain functional during the deprecation period and 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`). diff --git a/dde/README.zh_CN.md b/dde/README.zh_CN.md index 745caae..2534256 100644 --- a/dde/README.zh_CN.md +++ b/dde/README.zh_CN.md @@ -42,7 +42,7 @@ 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_enter`/`activity_leave` 事件携带 `reason` 枚举（由 `active_in`/`active_out` 更名；鼠标跟踪左键状态，滚轮为逐事件脉冲），并新增 `start_drag`/`drop`/`drag_cancelled` 生命周期事件。 +- `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-window-overlap-checker-unstable-v1.xml`（`treeland_window_overlap_checker_manager_v1` / `treeland_window_overlap_checker_v1`）取代：checker 接口补上 `_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`）。 diff --git a/dde/treeland-active-notify-unstable-v1.xml b/dde/treeland-active-notify-unstable-v1.xml index d494022..d704f6e 100644 --- a/dde/treeland-active-notify-unstable-v1.xml +++ b/dde/treeland-active-notify-unstable-v1.xml @@ -58,49 +58,70 @@ SPDX-License-Identifier: MIT A notifier object reports seat activity that the compositor - detects. Activity is reported as enter/leave events tagged - with the source that triggered them. + 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, enter and leave report the aggregate state of - the left pointer button only. activity_enter is sent when - the left button is pressed, activity_leave when it is - released. Other pointer buttons do not generate these - events. The compositor sends enter and leave as matched - pairs: it must not send a second enter before the matching - leave, nor a leave when the left button is not pressed. - - For wheel, enter and leave are discrete per-event pulses, - not a persistent state. activity_enter is sent for each - wheel event whose angle delta is positive, and - activity_leave for each whose angle delta is negative; the - compositor may send several enter (or several leave) events - in a row without an intervening opposite event. Clients - must treat each wheel event independently and must not - infer a lasting state from a single enter or leave. - - The start_drag, drop, and drag_cancelled events report the - lifecycle of a drag and drop operation on the seat. - start_drag is sent when the operation begins. Exactly one - terminal event follows each start_drag: drop when the - operation completes with a successful drop, or - drag_cancelled when the operation ends without a drop + 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 start_drag. + terminal event until the next started event. The input source that triggered an activity event. Used - by the activity_enter and activity_leave events. See the - interface description for the per-source semantics. + 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 @@ -109,55 +130,39 @@ SPDX-License-Identifier: MIT - - - For mouse, sent when the left pointer button is - pressed. For wheel, sent for each wheel event whose - angle delta is positive; the compositor may send - several in a row without an intervening activity_leave. - See the interface description for the per-source - semantics. - - - + + + 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. - - - For mouse, sent when the left pointer button is - released. For wheel, sent for each wheel event whose - angle delta is negative; the compositor may send - several in a row without an intervening activity_enter. See the interface description for the per-source semantics. + - - - Sent when a drag and drop operation starts on the seat - bound to this notifier. Exactly one terminal event - (drop or drag_cancelled) follows each start_drag. - - - - - - Terminal event for a drag and drop operation that - completes with a successful drop on the seat bound to - this notifier. No further drag events are sent after - drop until the next start_drag. - - - - - - Terminal event for a drag and drop operation that ends - without a drop, for example because the drag was - cancelled or the drag source destroyed. No further drag - events are sent after drag_cancelled until the next - start_drag. + + + 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/public/README.md b/public/README.md index cbdff42..bd2acc1 100644 --- a/public/README.md +++ b/public/README.md @@ -36,7 +36,7 @@ The manager request `set_xwindow_position_relative` and the `treeland_dde_active 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_enter`/`activity_leave` events carry a `reason` enum (renamed from `active_in`/`active_out`, with mouse tracking the left button state and wheel as per-event pulses), plus `start_drag`/`drop`/`drag_cancelled` lifecycle events (the latter covering drag cancellation). +- `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-window-overlap-checker-unstable-v1.xml` (`treeland_window_overlap_checker_manager_v1`, `treeland_window_overlap_checker_v1`): window overlap monitoring — edge-anchored region registration (`set_region`) with `enter`/`leave` state events and explicit error reporting; the checker 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 now documented as deprecated but still functional, superseded by the corresponding actions (`toggle_multitask_view`/`open_multitask_view`/`close_multitask_view` and `lockscreen`/`shutdown_menu`/`show_user_switch`) of the new privileged `dde/treeland-compositor-action-unstable-v1.xml` protocol. diff --git a/public/README.zh_CN.md b/public/README.zh_CN.md index 2c7d96c..96979cf 100644 --- a/public/README.zh_CN.md +++ b/public/README.zh_CN.md @@ -37,7 +37,7 @@ v1 与 v2 的线缆级差异： 二者由 `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_enter`/`activity_leave` 事件携带 `reason` 枚举（由 `active_in`/`active_out` 更名；鼠标跟踪左键状态，滚轮为逐事件脉冲），并新增 `start_drag`/`drop`/`drag_cancelled` 生命周期事件（后者覆盖拖拽取消）。 +- `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-window-overlap-checker-unstable-v1.xml`（`treeland_window_overlap_checker_manager_v1`、`treeland_window_overlap_checker_v1`）：窗口重叠监测——沿输出边缘的区域注册（`set_region`）与 `enter`/`leave` 状态事件及显式错误回报；checker 接口由 `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`）。 From 02effc296f3feccc22b9675839121c4f1df3c21f Mon Sep 17 00:00:00 2001 From: rewine Date: Thu, 17 Sep 2026 15:44:29 +0800 Subject: [PATCH 11/12] refactor: rename region-watch and move dde-shell-v2 to dde/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Rename window-overlap-checker to region-watch (file, protocol, interfaces, request) 2. Move dde-shell-unstable-v2 from public/ to dde/ and update CMakeLists 3. Add x_offset arg to set_auto_placement 4. Clean up READMEs: drop stale protocol refs and transitional wording Log: Renamed region-watch protocol and relocated dde-shell-v2; no user-facing API impact Influence: 1. Rebuild all protocol headers with wayland-scanner and confirm no warnings 2. Update compositor/client code using the renamed region-watch interfaces 3. Verify dde-shell-v2 still installs correctly from the dde/ directory refactor: 重命名 region-watch 并将 dde-shell-v2 移至 dde/ 1. 将 window-overlap-checker 重命名为 region-watch（文件、协议、接口、请求） 2. 将 dde-shell-unstable-v2 从 public/ 移至 dde/ 并更新 CMakeLists 3. 为 set_auto_placement 增加 x_offset 参数 4. 清理 README：移除过时协议引用与过渡性措辞 Log: 重命名 region-watch 协议并迁移 dde-shell-v2；无用户可见 API 影响 Influence: 1. 用 wayland-scanner 重建全部协议头文件并确认无警告 2. 更新使用重命名后 region-watch 接口的合成器/客户端代码 3. 验证 dde-shell-v2 从 dde/ 目录安装正常 --- CMakeLists.txt | 4 +- dde/README.md | 10 ++-- dde/README.zh_CN.md | 10 ++-- .../treeland-dde-shell-unstable-v2.xml | 10 ++-- ... => treeland-region-watch-unstable-v1.xml} | 56 +++++++++---------- deprecated/treeland-dde-shell-v1.xml | 26 +++------ public/README.md | 9 ++- public/README.zh_CN.md | 11 ++-- 8 files changed, 65 insertions(+), 71 deletions(-) rename {public => dde}/treeland-dde-shell-unstable-v2.xml (95%) rename dde/{treeland-window-overlap-checker-unstable-v1.xml => treeland-region-watch-unstable-v1.xml} (80%) diff --git a/CMakeLists.txt b/CMakeLists.txt index bc612c9..3d4291b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -14,13 +14,13 @@ include(CMakePackageConfigHelpers) # Public protocol XML files (for general application developers) set(TREELAND_PROTOCOL_XML_FILES public/treeland-window-transition-unstable-v1.xml - public/treeland-dde-shell-unstable-v2.xml public/treeland-appearance-unstable-v1.xml public/treeland-decoration-unstable-v1.xml ) # 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 @@ -33,7 +33,7 @@ set(TREELAND_PROTOCOL_DDE_XML_FILES dde/treeland-layer-shell-extension-unstable-v1.xml dde/treeland-xwindow-control-unstable-v1.xml dde/treeland-active-notify-unstable-v1.xml - dde/treeland-window-overlap-checker-unstable-v1.xml + dde/treeland-region-watch-unstable-v1.xml ) # Internal protocol XML files (Treeland-specific, not for general app developers) diff --git a/dde/README.md b/dde/README.md index 9eef85d..9441f52 100644 --- a/dde/README.md +++ b/dde/README.md @@ -16,7 +16,8 @@ For DDE desktop components. Installed via `TREELAND_PROTOCOL_DDE_XML_FILES`. | `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-window-overlap-checker-unstable-v1.xml` | `treeland_window_overlap_checker_unstable_v1` | `treeland_window_overlap_checker_manager_v1`, `treeland_window_overlap_checker_v1` | Window overlap monitoring: register an edge-anchored region on an output and observe enter/leave overlap events with xdg-shell toplevels | +| `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, position it in global coordinates or auto-place it below the cursor, and declare switcher/dock-preview/multitask-view listing preferences via a skip bitfield | ## Breaking changes @@ -43,8 +44,9 @@ Consumers should rebind the global as `treeland_compositor_action_v1` and trigge 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-window-overlap-checker-unstable-v1.xml` (`treeland_window_overlap_checker_manager_v1` / `treeland_window_overlap_checker_v1`): the checker 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) remain functional during the deprecation period and 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_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 @@ -121,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 2534256..2d9c531 100644 --- a/dde/README.zh_CN.md +++ b/dde/README.zh_CN.md @@ -16,7 +16,8 @@ | `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-window-overlap-checker-unstable-v1.xml` | `treeland_window_overlap_checker_unstable_v1` | `treeland_window_overlap_checker_manager_v1`、`treeland_window_overlap_checker_v1` | 窗口重叠监测：注册沿输出边缘的区域并订阅与 xdg-shell 顶层窗口重叠/解除重叠的 enter/leave 事件 | +| `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 预览/多任务视图的列表偏好 | ## 破坏性变更 @@ -43,8 +44,9 @@ 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-window-overlap-checker-unstable-v1.xml`（`treeland_window_overlap_checker_manager_v1` / `treeland_window_overlap_checker_v1`）取代：checker 接口补上 `_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_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 @@ -121,6 +123,6 @@ DDE-shell 协议中被 DDE 组件消费的接口拆分为 `dde/` 下的专用协 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/public/treeland-dde-shell-unstable-v2.xml b/dde/treeland-dde-shell-unstable-v2.xml similarity index 95% rename from public/treeland-dde-shell-unstable-v2.xml rename to dde/treeland-dde-shell-unstable-v2.xml index d0f688c..2180e5d 100644 --- a/public/treeland-dde-shell-unstable-v2.xml +++ b/dde/treeland-dde-shell-unstable-v2.xml @@ -150,15 +150,17 @@ SPDX-License-Identifier: MIT Ask the compositor to place this surface below the current - cursor position: horizontally centered on the cursor and - vertically offset by y_offset from the bottom of the - cursor. The compositor may adjust the position to keep - the surface accessible; see the interface description. + cursor position: horizontally offset by x_offset from the + cursor center and vertically offset by y_offset from the + bottom of the cursor. The compositor may adjust the + position to keep the surface accessible; see the interface + description. Sending this request switches the placement mode to automatic; see the interface description for the interaction with set_surface_position. + diff --git a/dde/treeland-window-overlap-checker-unstable-v1.xml b/dde/treeland-region-watch-unstable-v1.xml similarity index 80% rename from dde/treeland-window-overlap-checker-unstable-v1.xml rename to dde/treeland-region-watch-unstable-v1.xml index b1dfa90..c4b1a41 100644 --- a/dde/treeland-window-overlap-checker-unstable-v1.xml +++ b/dde/treeland-region-watch-unstable-v1.xml @@ -1,11 +1,11 @@ - + - + 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 @@ -26,12 +26,12 @@ SPDX-License-Identifier: MIT are to be interpreted as described in RFC 2119. - - - A global that creates treeland_window_overlap_checker_v1 - objects for privileged DDE clients. Each checker monitors + + + A global that creates treeland_region_watch_v1 + objects for privileged DDE clients. Each watcher monitors one region; clients monitoring several regions create - several checkers. + several watchers. The compositor must reject bind attempts from non-privileged clients. @@ -39,24 +39,24 @@ SPDX-License-Identifier: MIT - Destroy the treeland_window_overlap_checker_manager_v1 - object. Checkers created through this manager are not + Destroy the treeland_region_watch_manager_v1 + object. Watchers created through this manager are not affected. - - - Create a new treeland_window_overlap_checker_v1 object + + + Create a new treeland_region_watch_v1 object that monitors one region. - + - - - A checker object monitors whether a rectangular region + + + A watcher object monitors whether a rectangular region anchored to an edge of an output overlaps with any xdg-shell toplevel window. @@ -72,11 +72,11 @@ SPDX-License-Identifier: MIT matching enter or leave event; afterwards it should send these events only when the overlap state changes. - The checker is associated with the wl_output passed to the + 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 checker then + 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 checker object itself is + 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 @@ -85,7 +85,7 @@ SPDX-License-Identifier: MIT 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 checker remains + 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. @@ -114,8 +114,8 @@ SPDX-License-Identifier: MIT - - Errors raised by the treeland_window_overlap_checker_v1 + + Errors raised by the treeland_region_watch_v1 interface. @@ -123,10 +123,10 @@ SPDX-License-Identifier: MIT - - Destroy the treeland_window_overlap_checker_v1 object. + + Destroy the treeland_region_watch_v1 object. The compositor stops monitoring the region registered - with this checker. + with this watcher. @@ -140,7 +140,7 @@ SPDX-License-Identifier: MIT height is not positive. The output becomes the output associated with the - checker, replacing any previous one; it may be a + watcher, replacing any previous one; it may be a different output from a previous call (rebinding), for example after the previous output was removed. @@ -174,10 +174,10 @@ SPDX-License-Identifier: MIT Sent when the wl_output passed to the last set_region request has been destroyed by the compositor. The - checker then becomes inert: it has no monitored region + watcher then becomes inert: it has no monitored region and sends no further enter or leave events. - The checker object itself is not destroyed; the client + 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 diff --git a/deprecated/treeland-dde-shell-v1.xml b/deprecated/treeland-dde-shell-v1.xml index e1100df..8e9cbc4 100644 --- a/deprecated/treeland-dde-shell-v1.xml +++ b/deprecated/treeland-dde-shell-v1.xml @@ -25,8 +25,8 @@ object never emits events, and its requests have no effect apart from destroy. - Superseded by the treeland_window_overlap_checker_manager_v1 - global of the treeland-window-overlap-checker-unstable-v1 + Superseded by the treeland_region_watch_manager_v1 + global of the treeland-region-watch-unstable-v1 protocol. @@ -64,8 +64,7 @@ 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 remains functional during the deprecation period - but must not be used in new code. + request must not be used in new code. @@ -83,8 +82,7 @@ and show_user_switch actions of the treeland_compositor_action_v1 global of the treeland-compositor-action-unstable-v1 protocol. This - request remains functional during the deprecation period - but must not be used in new code. + request must not be used in new code. @@ -116,12 +114,9 @@ the destroy request, all requests have no effect and no events are ever emitted. New code must not use it. - Superseded by the treeland_window_overlap_checker_manager_v1 - global of the treeland-window-overlap-checker-unstable-v1 + Superseded by the treeland_region_watch_manager_v1 + global of the treeland-region-watch-unstable-v1 protocol. - - This interface will be removed along with the whole protocol - in a future release. @@ -281,9 +276,6 @@ Superseded by the treeland_active_notify_manager_v1 global of the treeland-active-notify-unstable-v1 protocol. - - This interface will be removed along with the whole protocol - in a future release. @@ -325,8 +317,7 @@ 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 - remains functional during the deprecation period but must not - be used in new code. + must not be used in new code. @@ -375,8 +366,7 @@ 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 remains functional during the deprecation period - but must not be used in new code. + The interface must not be used in new code. diff --git a/public/README.md b/public/README.md index bd2acc1..4eee0af 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-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, position it in global coordinates or auto-place it below the cursor, and declare switcher/dock-preview/multitask-view listing preferences via a skip bitfield | | `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,7 +19,7 @@ The `accent_color` event dropped its `a` (alpha) argument. The accent color is n #### `treeland-dde-shell-v1.xml` -The whole file is now deprecated and moved to `deprecated/`. It is superseded by `treeland-dde-shell-unstable-v2.xml` (in `public/`, reduced to the surface role functionality) together with the dedicated protocols listed above; the `treeland_window_picker_v1` interface is removed without a replacement, and a dedicated window-picking protocol may be designed in the future. +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. Wire-level differences between v1 and v2: @@ -32,14 +31,14 @@ Wire-level differences between v1 and v2: 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 documented as 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). +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-window-overlap-checker-unstable-v1.xml` (`treeland_window_overlap_checker_manager_v1`, `treeland_window_overlap_checker_v1`): window overlap monitoring — edge-anchored region registration (`set_region`) with `enter`/`leave` state events and explicit error reporting; the checker interface is renamed from `treeland_window_overlap_checker`, gaining the `_v1` suffix, and the region-setting request is renamed from `update` to `set_region`. +- `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 now documented as deprecated but still functional, superseded by the corresponding actions (`toggle_multitask_view`/`open_multitask_view`/`close_multitask_view` and `lockscreen`/`shutdown_menu`/`show_user_switch`) of the new privileged `dde/treeland-compositor-action-unstable-v1.xml` protocol. +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 globals instead of using the deprecated manager requests and interfaces; the deprecated requests and interfaces must not be used in new code. diff --git a/public/README.zh_CN.md b/public/README.zh_CN.md index 96979cf..473e02c 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-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 预览/多任务视图的列表偏好 | | `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,11 +20,11 @@ #### `treeland-dde-shell-v1.xml` -整个文件现已废弃并移至 `deprecated/`。由 `treeland-dde-shell-unstable-v2.xml`（在 `public/`，仅保留 surface 角色功能）连同上述专用协议取代；`treeland_window_picker_v1` 接口无替代直接移除，未来可能设计专用协议。 +整个文件已废弃并移至 `deprecated/`。由 `treeland-dde-shell-unstable-v2.xml`（在 `dde/`，surface 角色功能）连同上述专用协议取代；`treeland_window_picker_v1` 接口无替代直接移除。 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` 请求不再保留。 +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_auto_placement` 的 y_offset 改为 `int`（v1 为 `uint`），并明确两种放置请求（`set_surface_position` 与 `set_auto_placement`）的互斥关系（最近发送的请求生效）。 @@ -33,14 +32,14 @@ v1 与 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` 请求仍然可用，客户端可借此释放对象）。 +管理器的 `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-window-overlap-checker-unstable-v1.xml`（`treeland_window_overlap_checker_manager_v1`、`treeland_window_overlap_checker_v1`）：窗口重叠监测——沿输出边缘的区域注册（`set_region`）与 `enter`/`leave` 状态事件及显式错误回报；checker 接口由 `treeland_window_overlap_checker` 更名并补上 `_v1` 后缀，设区域请求由 `update` 更名为 `set_region`。 +- `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`）。 +`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`）。 消费者应改绑新的全局对象，不得在新代码中使用已废弃的请求与接口。 From cad113c188d78d54238406a493e4fbd96dd69e0b Mon Sep 17 00:00:00 2001 From: rewine Date: Thu, 17 Sep 2026 17:07:48 +0800 Subject: [PATCH 12/12] refactor: rework dde-shell placement requests as position hints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Rename set_surface_position to set_position_hint with output arg (null = primary) 2. Rename set_auto_placement to set_cursor_placement_hint 3. Redefine both as initial-placement hints: compositor decides final position 4. Sync READMEs with new request names and hint semantics Log: Renamed dde-shell placement requests; final position now compositor-decided Influence: 1. Rebuild protocol headers with wayland-scanner and confirm no warnings 2. Update compositor/client code calling the renamed placement requests 3. Verify primary-output fallback and compositor position adjustment behavior refactor: 重构 dde-shell 放置请求为位置提示 1. set_surface_position 更名为 set_position_hint，新增 output 参数（null 为主屏） 2. set_auto_placement 更名为 set_cursor_placement_hint 3. 两者重定义为初始放置提示：最终位置由合成器决定 4. 同步 README 的新请求名与提示语义 Log: 重命名 dde-shell 放置请求；最终位置现由合成器决定 Influence: 1. 用 wayland-scanner 重建协议头文件并确认无警告 2. 更新调用重命名后放置请求的合成器/客户端代码 3. 验证主屏回退与合成器位置调整行为 --- dde/README.md | 2 +- dde/README.zh_CN.md | 2 +- dde/treeland-dde-shell-unstable-v2.xml | 80 +++++++++++++++++--------- public/README.md | 2 +- public/README.zh_CN.md | 2 +- 5 files changed, 57 insertions(+), 31 deletions(-) diff --git a/dde/README.md b/dde/README.md index 9441f52..59dccf9 100644 --- a/dde/README.md +++ b/dde/README.md @@ -17,7 +17,7 @@ For DDE desktop components. Installed via `TREELAND_PROTOCOL_DDE_XML_FILES`. | `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, position it in global coordinates or auto-place it below the cursor, and declare switcher/dock-preview/multitask-view listing preferences via a skip bitfield | +| `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 diff --git a/dde/README.zh_CN.md b/dde/README.zh_CN.md index 2d9c531..442be52 100644 --- a/dde/README.zh_CN.md +++ b/dde/README.zh_CN.md @@ -17,7 +17,7 @@ | `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 预览/多任务视图的列表偏好 | +| `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 预览/多任务视图的列表偏好 | ## 破坏性变更 diff --git a/dde/treeland-dde-shell-unstable-v2.xml b/dde/treeland-dde-shell-unstable-v2.xml index 2180e5d..d96da1a 100644 --- a/dde/treeland-dde-shell-unstable-v2.xml +++ b/dde/treeland-dde-shell-unstable-v2.xml @@ -17,7 +17,8 @@ SPDX-License-Identifier: MIT 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 in global coordinates or auto-place it below the cursor. + it at coordinates relative to an output or auto-place it below + the cursor. The compositor must reject bind attempts from non-privileged clients. @@ -83,13 +84,16 @@ SPDX-License-Identifier: MIT treeland_dde_shell_surface_v2.destroy() must be called before destroying the wl_surface object. - Positioning requests are mutually exclusive: set_surface_position - places the surface at fixed global coordinates, while - set_auto_placement asks the compositor to place the surface - below the cursor. The most recently sent request determines - the placement mode. In both modes the compositor may adjust - the final position to keep the surface accessible, for - example to keep its titlebar area within the output. + 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. @@ -135,30 +139,52 @@ SPDX-License-Identifier: MIT - - - Move the surface to the given coordinates. Coordinates are - in the global space spanning all outputs; for example - 50,50 on a 1920,0+1920x1080 output is 1970,50 in global - coordinates. The compositor may adjust the position to - keep the surface accessible; see the interface description. + + + 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. - - + + + - - - Ask the compositor to place this surface below 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. The compositor may adjust the - position to keep the surface accessible; see the interface - description. + + + 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 - automatic; see the interface description for the - interaction with set_surface_position. + cursor-relative; see the interface description for the + interaction with set_position_hint. diff --git a/public/README.md b/public/README.md index 4eee0af..aa4f850 100644 --- a/public/README.md +++ b/public/README.md @@ -26,7 +26,7 @@ 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. `set_auto_placement` takes an `int` y_offset (v1 used `uint`), and the mutual exclusivity of the placement requests (`set_surface_position` vs `set_auto_placement`, most recent wins) is now specified. +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. diff --git a/public/README.zh_CN.md b/public/README.zh_CN.md index 473e02c..1640345 100644 --- a/public/README.zh_CN.md +++ b/public/README.zh_CN.md @@ -27,7 +27,7 @@ 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_auto_placement` 的 y_offset 改为 `int`（v1 为 `uint`），并明确两种放置请求（`set_surface_position` 与 `set_auto_placement`）的互斥关系（最近发送的请求生效）。 +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 在迁移期间仍会安装，但不得用于新代码。