Add XCUI input focus shortcut MVP

2026-04-04 18:55:20 +08:00
parent a9bf9ef35c
commit 611ca705c8
17 changed files with 1342 additions and 0 deletions
--- a/docs/plan/used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md
+++ b/docs/plan/used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md
@@ -0,0 +1,140 @@
+# XCUI Input / Focus / Shortcut Subplan 完成归档
+
+日期：`2026-04-04`
+
+## 1. 归档结论
+
+`Subplan-04` 在其原始定义边界内已经完成，可以归档。
+
+这里的“完成”指的是：
+
+- 已建立 XCUI 输入事件基础模型
+- 已建立焦点、激活路径、指针捕获路径三套状态管理
+- 已建立 capture / target / bubble 三阶段输入路由
+- 已建立 shortcut scope 与命令匹配机制
+- 已建立统一的 `UIInputDispatcher`
+- 已补齐最小单元测试并完成通过验证
+
+这里的“完成”不包括：
+
+- Win32 原生消息采集
+- ImGui / Editor 侧的输入桥接
+- 文本输入控件级别的 IME 细节
+
+这些内容本来就不在 `Subplan-04` 的负责边界里，后续应由 `Subplan-05`、`Subplan-08`、`Subplan-09` 等继续接手。
+
+## 2. 本次落地内容
+
+### 2.1 输入事件模型
+
+已扩展 `UIInputEvent`：
+
+- `PointerEnter`
+- `PointerLeave`
+- `pointerId`
+- `timestampNanoseconds`
+- `repeat`
+- `synthetic`
+
+相关文件：
+
+- `engine/include/XCEngine/UI/Types.h`
+
+### 2.2 焦点与路径模型
+
+已补齐：
+
+- `UIElementId`
+- `UIInputPath`
+- `UIFocusController`
+- `UIFocusChange`
+
+相关文件：
+
+- `engine/include/XCEngine/UI/Input/UIInputPath.h`
+- `engine/include/XCEngine/UI/Input/UIFocusController.h`
+- `engine/src/UI/Input/UIInputPath.cpp`
+- `engine/src/UI/Input/UIFocusController.cpp`
+
+### 2.3 Shortcut 系统
+
+已补齐：
+
+- `UIShortcutScope`
+- `UIShortcutChord`
+- `UIShortcutBinding`
+- `UIShortcutRegistry`
+- shortcut scope 优先级匹配规则
+
+相关文件：
+
+- `engine/include/XCEngine/UI/Input/UIShortcutRegistry.h`
+- `engine/src/UI/Input/UIShortcutRegistry.cpp`
+
+### 2.4 输入路由与统一分发器
+
+已补齐：
+
+- `UIInputRouter`
+- `UIInputRoutingPlan`
+- `UIInputRoutingStep`
+- `UIInputDispatcher`
+
+相关文件：
+
+- `engine/include/XCEngine/UI/Input/UIInputRouter.h`
+- `engine/include/XCEngine/UI/Input/UIInputDispatcher.h`
+- `engine/src/UI/Input/UIInputRouter.cpp`
+- `engine/src/UI/Input/UIInputDispatcher.cpp`
+
+## 3. 测试与验证
+
+新增测试：
+
+- `tests/Input/test_xcui_input_dispatcher.cpp`
+
+已完成验证：
+
+- `cmake --build build --config Debug --target input_tests`
+- `ctest -C Debug -R "XCUI.*" --output-on-failure`
+
+验证结果：
+
+- `6 / 6` 通过
+
+覆盖点包括：
+
+- focus path 切换
+- capture path 优先级
+- keyboard routed path 顺序
+- shortcut scope 匹配优先级
+- pointer down / pointer up 对 active path 的影响
+- shortcut 命中后优先消费、跳过普通 routing
+
+## 4. 对后续 subplan 的可复用输出
+
+当前已经可以被后续直接依赖的稳定入口：
+
+- `XCEngine::UI::UIInputPath`
+- `XCEngine::UI::UIFocusController`
+- `XCEngine::UI::UIShortcutRegistry`
+- `XCEngine::UI::UIInputRouter`
+- `XCEngine::UI::UIInputDispatcher`
+
+后续建议对接方式：
+
+- `Subplan-05`：负责把 ImGui/平台输入桥接进这套 dispatcher
+- `Subplan-08`：负责把 menu / dock / panel shell 的 shortcut scope 接进 registry
+- `Subplan-09`：负责把 viewport shell 的 pointer / focus / capture 接进 routing
+
+## 5. 原 subplan 文件
+
+原始 subplan 文件保留在：
+
+- `docs/plan/xcui-subplans/Subplan-04_XCUI-Input-Focus-Shortcut.md`
+
+其状态应视为：
+
+- 已完成
+- 已归档
+- 不再作为活跃开发计划继续扩写
--- a/docs/plan/xcui-subplans/README.md
+++ b/docs/plan/xcui-subplans/README.md
@@ -0,0 +1,44 @@
+# XCUI Parallel Subplans
+
+基于 [XCUI完整架构设计与执行计划](../XCUI完整架构设计与执行计划.md) 的并行拆分版本。
+
+当前建议：
+
+- `Phase 0` 由主线继续推进，目标是把 ImGui 从 engine/editor 公共边界剥离出来。
+- 其他人不要再去碰 `Phase 0` 正在改的边界文件，优先认领下面的独立 subplan。
+- 每个人只领一个 subplan，按“自己负责的目录”做增量开发，避免跨 subplan 改核心契约。
+
+推荐并行顺序：
+
+- 可以立刻开始：`01` `03` `04` `05` `06`
+- 建议在 Core/Backend 契约初步稳定后启动：`07` `08` `09`
+
+已完成归档：
+
+- `Subplan-02`：已于 `2026-04-04` 归档到 [../used/XCUI_Subplan-02_LayoutEngine_完成归档_2026-04-04.md](../used/XCUI_Subplan-02_LayoutEngine_完成归档_2026-04-04.md)
+- `Subplan-04`：已于 `2026-04-04` 归档到 [../used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md](../used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md)
+
+统一协作约束：
+
+- 共享契约文件尽量只由主线或对应 owner 修改。
+- 新模块优先放到新目录，不要把 XCUI 新逻辑继续塞进旧的 ImGui helper。
+- 每个 subplan 都要自带最小测试或样例，不接受只落抽象不落验证。
+- 每个 subplan 完成后，至少产出一个可被其他 subplan 直接依赖的稳定入口。
+
+共享高风险边界：
+
+- `engine/include/XCEngine/UI/`
+- `engine/include/XCEngine/Core/Layer.h`
+- `engine/include/XCEngine/Core/LayerStack.h`
+- `editor/src/Application.cpp`
+- `editor/src/Viewport/IViewportHostService.h`
+
+Subplan 列表：
+
+- `Subplan-01`：XCUI Core Tree / State / Invalidation
+- `Subplan-03`：XCUI Style / Theme / Token
+- `Subplan-05`：XCUI ImGui Transition Backend
+- `Subplan-06`：XCUI Markup / Import / Hot Reload
+- `Subplan-07`：XCUI Schema Inspector / PropertyGrid
+- `Subplan-08`：XCUI DockHost / Menu / Panel Shell
+- `Subplan-09`：XCUI ViewportSlot / Editor Integration
--- a/docs/plan/xcui-subplans/Subplan-04_XCUI-Input-Focus-Shortcut.md
+++ b/docs/plan/xcui-subplans/Subplan-04_XCUI-Input-Focus-Shortcut.md
@@ -0,0 +1,53 @@
+# Subplan 04：XCUI Input / Focus / Shortcut
+
+状态：
+
+- 已于 `2026-04-04` 完成当前 subplan 定义边界内的实现。
+- 已归档到：
+  [../used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md](../used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md)
+
+目标：
+
+- 建立 XCUI 的输入事件、焦点流转和快捷键分发模型。
+- 让输入不再直接写死在 ImGui 调用点里。
+
+负责人边界：
+
+- 负责 `engine/src/UI/Input/`。
+- 负责 pointer / keyboard / focus / command dispatch 的抽象。
+- 不负责平台消息采集本身。
+
+建议目录：
+
+- `engine/include/XCEngine/UI/Input/`
+- `engine/src/UI/Input/`
+- `tests` 中 input/focus 测试
+
+前置依赖：
+
+- 依赖 `Subplan 01` 的 tree 和 hit-test 基础契约。
+- 需要和 `Subplan 05` 对齐 adapter 输入桥接接口。
+
+现在就可以先做的内容：
+
+- 设计 `UIInputEvent` 丰富版本
+- 设计 focus path / active path / capture path
+- 设计 shortcut scope：global / window / panel / widget
+- 写 focus 切换和冒泡/捕获测试
+
+明确不做：
+
+- 不做 Win32 原生消息处理细节
+- 不做具体文本输入 widget
+
+交付物：
+
+- XCUI 输入分发器
+- 焦点管理器
+- 快捷键绑定与分发机制
+
+验收标准：
+
+- 可以确定事件从哪里来、往哪里走、谁消费
+- 焦点切换规则稳定可测
+- 快捷键系统可与 editor shell 直接对接