feat(shortcut): migrate treeland-shortcut-manager v2 → v3

[deepin-wm]

概述

适配 treeland 的 shortcut 模块到 treeland-protocols 0.6.0 的 breaking 变更，将 treeland-shortcut-manager 从 v2 迁移到 v3。

变更内容

• 接口重命名：treeland_shortcut_manager_v2 → _v3，treeland_shortcut_capture_v2 → _v3
• action 枚举重新编号：notify=0（原 1），所有条目下移 1
• 移除 commit 机制：commit 请求、commit_success/commit_failure 事件、error.invalid_commit 全部删除
• 新增 bind_failure 事件：逐绑定反馈失败，不再回滚同批次其他绑定
• bind 立即生效：活跃会话立即绑定，非活跃会话延迟到激活时逐条生效
• error 枚举调整：invalid_surface 从 4→3，移除 invalid_commit
• 接口版本重置为 1，移除所有 since 属性
• 修复既有 bug：unbind 现从 m_shortcuts 映射中移除；移除 onSessionChanged 中的 early return

测试

• 更新 tests/protocols/ 下 desktop-v3 和基础 v3 两个 fixture，覆盖 capture→captured、即时 bind_key→activated、acquire、bind_key 成功/upsert/name_conflict 等链路
• 更新 examples/test_shortcut_manager 和 examples/test_shortcut_capture 示例代码，移除 commit 逻辑

关联

• Multica Issue: WM-442

Summary by Sourcery

Migrate Treeland’s shortcut manager integration and test coverage from protocol v2 to v3, adopting immediate per-binding operations and the updated action model.

New Features:

• Add support for the treeland shortcut manager v3 protocol, including immediate binding, per-binding failure reporting, and expanded shortcut actions.
• Provide interactive v3 shortcut manager and capture example applications.

Bug Fixes:

• Remove unbound shortcuts from cached session state and correctly handle deferred binds and unbinds across session changes.
• Validate gesture inputs and shortcut actions more reliably, and preserve bindings when individual registrations fail.

Enhancements:

• Extend shortcut execution to support minimize, additional tiling modes, workspace movement, and zoom actions.
• Update shortcut manager and capture integrations to use the v3 interface with version 1 semantics and without commit operations.

Build:

• Switch protocol generation and example targets from shortcut manager v2 to unstable v3 and update required Qt components.

Documentation:

• Replace the shortcut manager v2 protocol test documentation with v3 coverage and behavior specifications.

Tests:

• Migrate protocol fixtures and unit tests to v3, covering capture, immediate binding, upsert behavior, name conflicts, bind failures, and activation.

Chores:

• Rename shortcut manager implementation types and references from v2 to v3 throughout the compositor.

[deepin-ci-robot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: 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

[sourcery-ai]

Reviewer's Guide

Migrates Treeland shortcut management from protocol v2 to v3, replacing commit-based transactional binding with immediate per-bind registration and failure events, updating session lifecycle handling, examples, generated protocol integration, and protocol fixtures.

Sequence diagram for v3 immediate and deferred shortcut binding

sequenceDiagram
    participant Client
    participant ShortcutManagerV3
    participant ShortcutController
    participant Session

    Client->>ShortcutManagerV3: bind_key(name, key_sequence, flags, action)
    alt active session
        ShortcutManagerV3->>ShortcutController: registerKey(name, key, flags, action)
        alt registration fails
            ShortcutManagerV3-->>Client: bind_failure(name, error)
        end
    else inactive session
        ShortcutManagerV3->>ShortcutManagerV3: queue bind_key
        Session-->>ShortcutManagerV3: onSessionChanged()
        ShortcutManagerV3->>ShortcutController: registerKey(name, key, flags, action)
        alt registration fails
            ShortcutManagerV3-->>Client: bind_failure(name, error)
        end
    end

Loading

File-Level Changes

Change	Details	Files
Migrated the server and client integration from the v2 shortcut protocol to the unstable v3 protocol with interface version 1.	Renamed manager and capture interfaces, generated protocol sources, implementation classes, and test bindings. Updated action and error enum mappings and related compile-time consistency checks. Rewired server initialization and Qt/C client examples to use v3 APIs.	src/modules/shortcut/CMakeLists.txt src/modules/shortcut/shortcutcontroller.cpp src/modules/shortcut/shortcutcontroller.h src/modules/shortcut/shortcutmanager.cpp src/modules/shortcut/shortcutmanager.h src/seat/helper.cpp src/seat/helper.h examples/test_shortcut_manager/CMakeLists.txt examples/test_shortcut_manager/main.cpp examples/test_shortcut_capture/CMakeLists.txt examples/test_shortcut_capture/main.cpp
Reworked binding lifecycle for v3 immediate application and per-binding failure reporting.	Apply binds immediately for the active session and queue them for inactive sessions until activation. Replace transactional commit and rollback handling with independent registration and bind_failure events. Restore accepted bindings on session changes and process deferred binds/unbinds without aborting unrelated entries. Remove unbound entries from the tracked shortcut maps and eliminate obsolete commit state.	src/modules/shortcut/shortcutmanager.cpp
Updated protocol fixtures and integration tests to validate v3 behavior.	Renamed fixtures and protocol artifacts to v3 and reset client interface binding to version 1. Replaced commit assertions with immediate bind, upsert, name-conflict, bind_failure, capture, and activation coverage. Updated test documentation and coverage notes, including the remaining inactive-session limitation.	tests/protocols/CMakeLists.txt tests/protocols/INDEX.md tests/protocols/treeland-shortcut-manager-v3/CMakeLists.txt tests/protocols/treeland-shortcut-manager-v3/README.md tests/protocols/treeland-shortcut-manager-v3/setup.cpp tests/protocols/treeland-shortcut-manager-v3/treeland-shortcut-manager-v3.c tests/protocols/treeland-shortcut-manager-v3/treeland-shortcut-manager-v3.h tests/protocols/treeland-shortcut-manager-desktop-v3/CMakeLists.txt tests/protocols/treeland-shortcut-manager-desktop-v3/setup.cpp tests/protocols/treeland-shortcut-manager-desktop-v3/treeland-shortcut-manager-desktop-v3.c tests/test_protocol_shortcut/main.cpp

---

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.

[deepin-bot]

TAG Bot

New tag: 0.10.0
DISTRIBUTION: unstable
Suggest: synchronizing this PR through rebase #1392

[Copilot]

Copilot review overview

🟡 Changes recommended

Unsupported v3 actions are silently ignored, and renamed upserts can leave stale per-session bindings.

Review effort: Lite
Findings: 2 · 1

Open (3)

• Upsert leaves stale binding in per-socket state · New
• Accepted shortcut actions lack executor mappings · New
• README shortcut example conflicts with desktop fixture · New

What changed in this PR

Migrates Treeland’s shortcut manager and capture protocols from v2 to v3.

Changes:

• Replaces commit-based binding with immediate binding and bind_failure.
• Updates protocol interfaces, action enums, runtime integration, and examples.
• Adds v3 protocol fixtures and desktop coverage.

File	Description
tests/​test_protocol_shortcut/​main.cpp	Uses the v3 manager.
tests/​protocols/​treeland-shortcut-manager-v3/​treeland-shortcut-manager-v3.h	Defines v3 test state.
tests/​protocols/​treeland-shortcut-manager-v3/​treeland-shortcut-manager-v3.c	Tests v3 requests and errors.
tests/​protocols/​treeland-shortcut-manager-v3/​setup.cpp	Finds the v3 server interface.
tests/​protocols/​treeland-shortcut-manager-v3/​README.md	Documents v3 coverage.
tests/​protocols/​treeland-shortcut-manager-v3/​CMakeLists.txt	Builds the v3 fixture.
tests/​protocols/​treeland-shortcut-manager-v2/​README.md	Removes obsolete v2 documentation.
tests/​protocols/​treeland-shortcut-manager-desktop-v3/​treeland-shortcut-manager-desktop-v3.h	Defines desktop test state.
tests/​protocols/​treeland-shortcut-manager-desktop-v3/​treeland-shortcut-manager-desktop-v3.c	Tests desktop v3 behavior.
tests/​protocols/​treeland-shortcut-manager-desktop-v3/​setup.cpp	Uses the desktop v3 fixture.
tests/​protocols/​treeland-shortcut-manager-desktop-v3/​CMakeLists.txt	Builds the desktop v3 test.
tests/​protocols/​INDEX.md	Updates the protocol test index.
tests/​protocols/​CMakeLists.txt	Registers v3 tests.
src/​seat/​helper.h	Stores the v3 manager.
src/​seat/​helper.cpp	Attaches and initializes the v3 manager.
src/​modules/​shortcut/​shortcutrunner.cpp	Maps shortcut actions.
src/​modules/​shortcut/​shortcutmanager.h	Defines the v3 manager API.
src/​modules/​shortcut/​shortcutmanager.cpp	Implements v3 protocol behavior.
src/​modules/​shortcut/​shortcutcontroller.h	Updates v3 action values.
src/​modules/​shortcut/​shortcutcontroller.cpp	Implements binding errors and upserts.
src/​modules/​shortcut/​CMakeLists.txt	Generates v3 server bindings.
src/​common/​shellaction.h	Declares minimize support.
src/​common/​shellaction.cpp	Executes minimize actions.
examples/​test_shortcut_manager/​main.cpp	Migrates the manager example.
examples/​test_shortcut_manager/​CMakeLists.txt	Generates v3 client bindings.
examples/​test_shortcut_capture/​main.cpp	Migrates the capture example.
examples/​test_shortcut_capture/​CMakeLists.txt	Generates v3 capture bindings.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[sourcery-ai]

Sorry @wineee, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 16 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[zccrs]

这个最好也加上 TileTop 和 TileBottom 作为预留，比如屏幕旋转后的情况，屏幕高比宽大时，可能需要的是上下分屏而不是左右

[wineee]

这里好说，主要是协议要不要加