feat(dock): adapt to treeland-xwindow-control-unstable-v1 protocol

[deepin-wm]

背景

treeland-xwindow-control-unstable-v1 协议（含 set_xwindow_position_relative 接口）已从 treeland-dde-shell-v1 中独立拆分到 treeland-protocols（>=0.6.0，commit 7ba45e4 及之后）。原 treeland_dde_shell_manager_v1 中的 set_xwindow_position_relative 已标记为 deprecated。

dde-shell dock 模块需要适配，将 XEmbed 窗口相对定位调用迁移到新的 treeland_xwindow_control_v1 global 接口。

改动内容

panels/dock/waylanddockhelper.h

• 新增 #include "qwayland-treeland-xwindow-control-unstable-v1.h"
• 新增 TreeLandXWindowControl 类，继承 QWaylandClientExtensionTemplate<TreeLandXWindowControl> 和 QtWayland::treeland_xwindow_control_v1，提供 setXWindowPositionRelative 方法
• 从 TreeLandDDEShellManager 中移除 setXWindowPositionRelative 方法声明（该类保留，仍用于 get_window_overlap_checker）
• WaylandDockHelper 新增成员 QScopedPointer<TreeLandXWindowControl> m_xwindowControl

panels/dock/waylanddockhelper.cpp

• 新增 qwayland-treeland-xwindow-control-unstable-v1.h 和 wayland-treeland-xwindow-control-unstable-v1-client-protocol.h 两个 include
• 实现 TreeLandXWindowControl 构造函数和 setXWindowPositionRelative（检查 isActive()，转调新接口）
• 删除 TreeLandDDEShellManager::setXWindowPositionRelative 实现
• 构造函数中新增 m_xwindowControl.reset(new TreeLandXWindowControl())
• moveXEmbedWindow 中 isActive 检查和 setXWindowPositionRelative 调用从 m_ddeShellManager 改为 m_xwindowControl
• m_ddeShellManager 的 activeChanged 信号连接和 overlap checker 逻辑保持不动

panels/dock/CMakeLists.txt

• find_package(TreelandProtocols REQUIRED) → find_package(TreelandProtocols 0.6.0 REQUIRED)
• qt_generate_wayland_protocol_client_sources 的 FILES 列表追加 treeland-xwindow-control-unstable-v1.xml

debian/control

• treeland-protocols (>> 0.5.9) → treeland-protocols (>= 0.6.0)

注意事项

• 新接口 set_xwindow_position_relative 的请求签名和回调语义与旧接口完全一致，moveXEmbedWindow 中的 wl_callback listener 逻辑无需改动
• TreeLandDDEShellManager 类保留，仅移除 setXWindowPositionRelative 方法
• 编译环境需安装包含 treeland-xwindow-control-unstable-v1.xml 的 treeland-protocols 包（commit 7ba45e4 或后续发布版本）

Issue: DDE-320

Summary by Sourcery

Migrate dock XEmbed positioning to the treeland_xwindow_control_v1 protocol and require the corresponding Treeland protocols release.

Enhancements:

• Migrate dock XEmbed window relative positioning to the standalone treeland_xwindow_control_v1 Wayland global while retaining the existing DDE shell manager for window overlap checking.

Build:

• Require treeland-protocols version 0.6.0 or newer and generate client bindings for the treeland-xwindow-control-unstable-v1 protocol.

[sourcery-ai]

Reviewer's Guide

The dock now positions XEmbed windows through the standalone treeland_xwindow_control_v1 global, preserving the existing callback handling and DDE shell overlap-checker integration while requiring and generating the protocol from TreelandProtocols 0.6.0 or newer.

Sequence diagram for XEmbed positioning via xwindow control

sequenceDiagram
    participant Dock as WaylandDockHelper
    participant Control as TreeLandXWindowControl
    participant Wayland as treeland_xwindow_control_v1
    participant Callback as wl_callback

    Dock->>Control: setXWindowPositionRelative(wid, anchorSurface, dx, dy)
    Control->>Control: isActive()
    Control->>Wayland: set_xwindow_position_relative(wid, anchor, dx, dy)
    Wayland-->>Control: wl_callback
    Control-->>Dock: wl_callback
    Dock->>Callback: register listener
    Wayland-->>Callback: asynchronous result

Loading

File-Level Changes

Change	Details	Files
Migrate XEmbed relative positioning from the deprecated DDE shell request to the standalone Treeland XWindow Control protocol.	Add a client-extension wrapper that checks activation and forwards fixed-point coordinates to the new protocol request. Instantiate the new control extension and use it for readiness checks and asynchronous positioning callbacks. Retain the DDE shell manager for window-overlap functionality while removing its obsolete positioning API.	panels/dock/waylanddockhelper.h panels/dock/waylanddockhelper.cpp
Generate and consume client bindings for the new protocol with an explicit minimum protocol package version.	Require TreelandProtocols 0.6.0 or newer. Add the xwindow-control protocol XML to generated Wayland client sources and include its generated headers. Raise the Debian dependency to treeland-protocols >= 0.6.0.	panels/dock/CMakeLists.txt debian/control

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[wineee]

linuxdeepin/treeland#1410

[deepin-bot]

TAG Bot

New tag: 2.0.55
DISTRIBUTION: unstable
Suggest: synchronizing this PR through rebase #1752

[deepin-bot]

TAG Bot

New tag: 2.0.56
DISTRIBUTION: unstable
Suggest: synchronizing this PR through rebase #1753

[deepin-ci-robot]

deepin pr auto review

AI 代码审查报告

项目: linuxdeepin/dde-shell
PR: #1746
提交: feat(dock): adapt to treeland-xwindow-control-unstable-v1 protocol
作者: deepin-wm
关联 Issue: DDE-320
分析模式: 全量分析
审查时间: 2026-10-12

---

总体评价

项目	结果
总分	98 / 100
风险等级	None
总体结论	代码审查通过
安全漏洞	存在0个安全漏洞
漏洞对比统计	新增漏洞 0 个，减少漏洞 0 个，持平 0 个

本次提交将 dde-shell dock 模块的 XEmbed 窗口相对定位功能从已废弃的 treeland_dde_shell_manager_v1 接口迁移到独立的 treeland_xwindow_control_v1 协议。代码改动清晰、逻辑正确，符合 Wayland 客户端扩展的标准模式。析构函数正确检查 isInitialized() 后调用 destroy()，QScopedPointer 确保资源自动释放。未发现安全漏洞，仅有一处轻微的注释缺失问题。

---

修改文件列表

文件	类型	说明
debian/control	打包依赖	treeland-protocols 版本从 >> 0.5.9 升级至 >= 0.6.0
panels/dock/CMakeLists.txt	构建配置	添加版本要求 0.6.0，新增协议源文件
panels/dock/waylanddockhelper.cpp	C++ 源文件	新增 TreeLandXWindowControl 类实现，迁移方法调用
panels/dock/waylanddockhelper.h	C++ 头文件	新增 TreeLandXWindowControl 类声明，新增成员变量

---

四维度评分

维度1：语法逻辑（25分）✓ — 25/25

语法正确，逻辑清晰

分析：

1. TreeLandXWindowControl 类继承自 QWaylandClientExtensionTemplate<TreeLandXWindowControl> 和 QtWayland::treeland_xwindow_control_v1，继承结构正确，与文件中其他 Wayland 客户端扩展类（如 WallpaperColorManager、TreeLandDDEShellManager）保持一致。
2. 构造函数使用 treeland_xwindow_control_v1_interface.version 初始化基类，这是 Qt Wayland 客户端扩展的标准做法。
3. 析构函数在调用 destroy() 前检查 isInitialized()，防止对未初始化对象调用 destroy，逻辑正确。
4. setXWindowPositionRelative 方法先检查 isActive() 再调用协议方法，返回 nullptr 表示未激活，与原实现行为一致。
5. moveXEmbedWindow 函数中的检查从 m_ddeShellManager 改为 m_xwindowControl，空指针检查 !m_xwindowControl || !m_xwindowControl->isActive() 逻辑正确。
6. wl_fixed_from_double() 用于 double 到 Wayland fixed-point 的转换，类型转换正确。
7. 无编译错误、无内存泄漏、无空指针解引用风险。

维度2：代码质量（25分）✓ — 23/25

代码结构清晰，注释完整

分析：

1. 注释完整性（-2分）：新增的 TreeLandXWindowControl::setXWindowPositionRelative 方法（waylanddockhelper.h:103）缺少文档注释。原 TreeLandDDEShellManager 类中的同名方法有注释 "Move XEmbed window to position relative to anchor surface / Returns wl_callback* or nullptr if not active"，迁移后该注释未保留到新类中。
2. 代码重复：无重复代码。新类遵循文件中已有的 Wayland 客户端扩展类模式，结构一致。
3. 结构合理性：类职责分离清晰 —— TreeLandDDEShellManager 保留窗口重叠检测功能，TreeLandXWindowControl 专门负责窗口定位，符合单一职责原则。
4. 调试信息清理：qWarning() 输出已从 "manager active" 更新为 "xwindow control active"，与变量名保持一致，无残留调试代码。

维度3：代码性能（20分）✓ — 20/20

性能良好，资源使用合理

分析：

1. 无算法复杂度问题，协议调用为 O(1) 操作。
2. QScopedPointer 管理新对象生命周期，无需手动释放，无资源泄漏风险。
3. Wayland 协议调用使用异步回调机制（wl_callback），不阻塞主线程。
4. 无不必要的内存拷贝或分配。
5. 构造函数中 m_xwindowControl.reset(new TreeLandXWindowControl()) 仅执行一次初始化，无性能影响。

维度4：代码安全（30分）✓ — 30/30

存在0个安全漏洞

分析：

1. 无用户输入直接拼接命令的风险，所有参数（wid、anchor、dx、dy）均为强类型，直接传递给 Wayland 协议接口。
2. 无硬编码密钥或敏感信息。
3. 无缓冲区溢出风险，Wayland 协议层处理参数验证。
4. 无路径遍历、SQL 注入、命令注入等安全风险。
5. 无不安全的随机数或弱加密算法使用。

---

改进建议

建议1：补充方法文档注释

文件: panels/dock/waylanddockhelper.h:103

问题: TreeLandXWindowControl::setXWindowPositionRelative 方法缺少文档注释。

建议修复:

class TreeLandXWindowControl : public QWaylandClientExtensionTemplate<TreeLandXWindowControl>, public QtWayland::treeland_xwindow_control_v1
{
    Q_OBJECT

public:
    explicit TreeLandXWindowControl();

    ~TreeLandXWindowControl() override;

    // Move XEmbed window to position relative to anchor surface
    // Returns wl_callback* or nullptr if not active
    struct ::wl_callback *setXWindowPositionRelative(uint32_t wid, struct ::wl_surface *anchor, double dx, double dy);
};

---

OCR 审查结果

项目	结果
审查文件数	3
评论数	0
漏洞数	0
结论	No comments generated. Looks good to me.

---

审查清单

• 已按四维度标准完成代码分析（语法逻辑、代码质量、代码性能、代码安全）
• 代码安全维度第一行包含"存在0个安全漏洞"
• 包含漏洞对比统计行（新增/减少/持平）
• 每个维度标记✓/✕与评价词一致
• 审查结论考虑了 commit message 的目的（协议迁移适配）
• 问题定位准确，行号和函数名正确
• 环境变量使用正确，文件路径无误

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: 18202781743, deepin-wm

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• debian/deepin/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[wineee]

/merge

[deepin-bot]

This pr cannot be merged! (status: blocked)

[18202781743]

/forcemerge

[deepin-bot]

This pr force merged! (status: blocked)