xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(xceditor): deepen foundation api pages

Browse Source
This commit is contained in:
ssdfasd
2026-04-10 17:43:30 +08:00
parent 00cf3850d5
commit 89bbad2786
5 changed files with 193 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/api/XCEditor/Foundation/Foundation.md
View File

@@ -2,39 +2,49 @@
**命名空间**: `XCEngine::UI::Editor` **命名空间**: `XCEngine::UI::Editor`
**类型**: `submodule` **类型**: `module`
**描述**: 编辑器基础设施子模块，覆盖命令注册、命令派发、快捷键管理以及主题度量解析入口。 **描述**: `XCEditor` 的基础协议层，覆盖命令注册、命令派发、快捷键管理以及主题度量解析入口。
## 概述 ## 概览
`Foundation` 负责把 shell 壳层的静态配置转换成运行时可执行的命令与快捷键系统。按当前头文件分工： `Foundation` 解决的是“shell 和控件真正运行前，需要先有一套什么样的 editor 级基础协议”。
按当前代码，职责主要分成四块：
- `UIEditorCommandRegistry.h` - `UIEditorCommandRegistry.h`
- 声明命令描述、workspace 命令描述和注册表校验规则 - 定义 editor 命令描述、workspace 命令描述以及注册表校验规则。
- `UIEditorCommandDispatcher.h` - `UIEditorCommandDispatcher.h`
- 把命令 id 分发到 workspace controller 或 host command handler - 把 `commandId` 解析为 workspace command 或 host command，并执行 preview / dispatch。
- `UIEditorShortcutManager.h` - `UIEditorShortcutManager.h`
- 在 `UIShortcutRegistry` 之上管理绑定、校验冲突并执行调度 - 复用 `XCEngine::UI::UIShortcutRegistry` 完成快捷键绑定、冲突校验与调度。
- `UIEditorTheme.h` - `UIEditorTheme.h`
- 汇总 Collections / Fields / Shell 各控件的 metrics 与 palette 解析入口 - 为 `Collections / Fields / Shell` 汇总默认 metrics / palette 解析入口。
`new_editor/app/Application.cpp` 当前会构造 `UIEditorWorkspaceController`，再通过 `BuildEditorShellShortcutManager(...)` 接入这一层。 这层不直接渲染 widget，也不直接拥有 workspace 状态；它更像 `XCEditor` 的“命令 + 输入 + 主题”底座。
## 当前调用链
- `new_editor/src/Shell/UIEditorShellAsset.cpp` 会从 shell asset 构造命令注册表和快捷键管理器。
- `new_editor/src/Shell/UIEditorMenuModel.cpp` 通过命令注册表、命令派发器和快捷键管理器生成 menu item 的启用态与 shortcut 文案。
- 多组 `tests/UI/Editor/unit/**` 与 `tests/UI/Editor/integration/**` 当前直接把这层当作 editor shell 的最小可验证基础设施。
## 公开头文件 ## 公开头文件
- `UIEditorCommandDispatcher.h` - [UIEditorCommandRegistry](UIEditorCommandRegistry/UIEditorCommandRegistry.md) - editor 命令描述与注册表校验规则。
- `UIEditorCommandRegistry.h` - [UIEditorCommandDispatcher](UIEditorCommandDispatcher/UIEditorCommandDispatcher.md) - `commandId -> workspace/host dispatch` 入口。
- `UIEditorShortcutManager.h` - [UIEditorShortcutManager](UIEditorShortcutManager/UIEditorShortcutManager.md) - editor 快捷键绑定、校验和调度入口。
- `UIEditorTheme.h` - [UIEditorTheme](UIEditorTheme/UIEditorTheme.md) - 默认 metrics / palette 解析入口。
## 当前实现边界 ## 当前实现边界
- 当前这里只建立目录索引页，具体头文件页仍需后续补齐。 - 该模块不直接渲染 UI，而是为 `Shell`、`Collections` 和 `Fields` 提供命令、快捷键和主题基础能力。
- 该模块不直接渲染 UI，而是为 `Shell` 与各控件模块提供命令、快捷键、主题和度量解析能力。 - 当前主题解析函数统一返回静态默认值，还没有引入动态主题切换或 style 覆盖链。
- host command 仍然通过 `UIEditorHostCommandHandler` 抽象对外，不把宿主实现细节泄漏回 public header。
## 相关文档 ## 相关文档
- [XCEditor](../XCEditor.md) - [XCEditor](../XCEditor.md)
- [Shell](../Shell/Shell.md) - [Shell](../Shell/Shell.md)
- [Widgets](../Widgets/Widgets.md) - [Collections](../Collections/Collections.md)
- [Fields](../Fields/Fields.md)

69
docs/api/XCEditor/Foundation/UIEditorCommandDispatcher/UIEditorCommandDispatcher.md
View File

@@ -1,43 +1,60 @@
# UIEditorCommandDispatcher # UIEditorCommandDispatcher
**命名空间**: `XCEngine` **命名空间**: `XCEngine::UI::Editor`
**类型**: `class` **类型**: `class`
**头文件**: `XCEditor/Foundation/UIEditorCommandDispatcher.h` **头文件**: `XCEditor/Foundation/UIEditorCommandDispatcher.h`
**描述**: 定义 `XCEditor/Foundation` 子目录中的 `UIEditorCommandDispatcher` public API。 **描述**: editor 命令执行入口，负责把 `commandId` 解析为 workspace command 或 host command，并执行 preview / dispatch。
## 概述 ## 概览
`UIEditorCommandDispatcher.h` 是 `XCEditor/Foundation` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `UIEditorCommandDispatcher` 位于命令描述层和 shell 工作区控制器之间。它当前做两步：
## 声明概览 1. `Evaluate(...)`
- 校验注册表，查找 `commandId`，把 `ActivePanel` / `FixedPanelId` 等静态描述解析成当前可执行的具体命令。
2. `Dispatch(...)`
- 在 `Evaluate(...)` 成功后，把 workspace 命令交给 `UIEditorWorkspaceController`，或者把 host 命令交给 `UIEditorHostCommandHandler`。
| 声明 | 类型 | 说明 | 这让 menu、shortcut 和 shell interaction 都可以共享同一套命令求值与分发逻辑。
|------|------|------|
| `UIEditorHostCommandEvaluationResult` | `struct` | 头文件中的公开声明。 |
| `UIEditorHostCommandDispatchResult` | `struct` | 头文件中的公开声明。 |
| `UIEditorHostCommandHandler` | `class` | 头文件中的公开声明。 |
| `UIEditorCommandEvaluationCode` | `enum class` | 头文件中的公开声明。 |
| `UIEditorCommandEvaluationResult` | `struct` | 头文件中的公开声明。 |
| `UIEditorCommandDispatchStatus` | `enum class` | 头文件中的公开声明。 |
| `UIEditorCommandDispatchResult` | `struct` | 头文件中的公开声明。 |
| `UIEditorCommandDispatcher` | `class` | 头文件中的公开声明。 |
## 公共方法 ## 主要声明
| 方法 | 描述 | | 声明 | 角色 |
|------|------| |------|------|
| [UIEditorCommandDispatcher()](Constructor.md) | 构造对象。 | | `UIEditorHostCommandHandler` | 宿主命令执行抽象，允许 shell 外部接管 host 命令。 |
| [GetCommandRegistry](GetCommandRegistry.md) | 获取相关状态或对象。 | | `UIEditorCommandEvaluationCode` | 命令求值失败或成功的细分原因。 |
| [SetHostCommandHandler](SetHostCommandHandler.md) | 设置相关状态或配置。 | | `UIEditorCommandEvaluationResult` | `Evaluate(...)` 的结果，包含解析出的 workspace command 与 preview 结果。 |
| [GetHostCommandHandler](GetHostCommandHandler.md) | 获取相关状态或对象。 | | `UIEditorCommandDispatchStatus` | 最终 dispatch 状态。 |
| [ValidateConfiguration](ValidateConfiguration.md) | 公开方法，详见头文件声明。 | | `UIEditorCommandDispatchResult` | `Dispatch(...)` 的结果。 |
| [Evaluate](Evaluate.md) | 公开方法，详见头文件声明。 | | `UIEditorCommandDispatcher` | 命令求值与分发器本体。 |
| [Dispatch](Dispatch.md) | 公开方法，详见头文件声明。 |
## 当前实现行为
- `ValidateConfiguration()` 直接复用 `ValidateUIEditorCommandRegistry(...)`。
- `Evaluate(...)` 当前会：
- 在注册表无效时返回 `InvalidCommandRegistry`
- 在命令不存在时返回 `UnknownCommandId`
- 对 `Host` 命令转发给 `UIEditorHostCommandHandler::EvaluateHostCommand(...)`
- 对 `Workspace` 命令解析 `panelSource`
- 在 `ActivePanel` 但当前 workspace 没有 active panel 时返回 `MissingActivePanel`
- 复制一份 controller 做 preview dispatch，用 `previewResult` 预测命令是否会被拒绝
- `Dispatch(...)` 当前先调用 `Evaluate(...)`，只有可执行时才真正分发。
- host 命令和 workspace 命令共享统一结果结构，但最终执行路径不同。
## 测试与调用链
- `tests/UI/Editor/unit/test_ui_editor_command_dispatcher.cpp`
- 当前覆盖 active panel 解析、缺少 active panel 的拒绝路径，以及 dispatch 后 workspace 状态变更。
- `tests/UI/Editor/unit/test_ui_editor_shell_interaction.cpp`
- 当前通过 shell interaction 间接消费命令派发器。
- `tests/UI/Editor/integration/shell/menu_bar_basic/main.cpp`
- 当前把命令派发器挂进 menu bar / context menu 的真实交互路径。
## 相关文档 ## 相关文档
- [当前目录](../Foundation.md) - 返回 `Foundation` 平行目录 - [Foundation](../Foundation.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [UIEditorCommandRegistry](../UIEditorCommandRegistry/UIEditorCommandRegistry.md)
- [UIEditorShortcutManager](../UIEditorShortcutManager/UIEditorShortcutManager.md)
- [UIEditorWorkspaceController](../../Shell/UIEditorWorkspaceController/UIEditorWorkspaceController.md)

65
docs/api/XCEditor/Foundation/UIEditorCommandRegistry/UIEditorCommandRegistry.md
View File

@@ -1,36 +1,59 @@
# UIEditorCommandRegistry # UIEditorCommandRegistry
**命名空间**: `XCEngine` **命名空间**: `XCEngine::UI::Editor`
**类型**: `struct` **类型**: `enums + structs + functions`
**头文件**: `XCEditor/Foundation/UIEditorCommandRegistry.h` **头文件**: `XCEditor/Foundation/UIEditorCommandRegistry.h`
**描述**: 定义 `XCEditor/Foundation` 子目录中的 `UIEditorCommandRegistry` public API。 **描述**: editor 命令描述协议与注册表校验入口，负责定义 workspace/host 命令的静态声明格式。
## 概述 ## 概览
`UIEditorCommandRegistry.h` 是 `XCEditor/Foundation` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `UIEditorCommandRegistry.h` 是 `XCEditor` 命令系统的静态描述层。它不执行命令，而是先回答这些问题：
## 声明概览 - 一个 editor 命令的 `commandId`、`displayName` 和命令种类是什么。
- 这个命令对应的是 workspace command 还是 host command。
- 如果是 workspace command，它的 panel 路由来自固定 panel、当前 active panel，还是根本不需要 panel。
- 当前整张命令表是否合法，是否存在重复 id、空 displayName 或错误的 panel source 组合。
| 声明 | 类型 | 说明 | ## 主要声明
|------|------|------|
| `UIEditorCommandKind` | `enum class` | 头文件中的公开声明。 |
| `UIEditorCommandPanelSource` | `enum class` | 头文件中的公开声明。 |
| `UIEditorWorkspaceCommandDescriptor` | `struct` | 头文件中的公开声明。 |
| `UIEditorCommandDescriptor` | `struct` | 头文件中的公开声明。 |
| `UIEditorCommandRegistry` | `struct` | 头文件中的公开声明。 |
| `UIEditorCommandRegistryValidationCode` | `enum class` | 头文件中的公开声明。 |
| `UIEditorCommandRegistryValidationResult` | `struct` | 头文件中的公开声明。 |
## 结构体成员 | 声明 | 角色 |
|------|------|
| `UIEditorCommandKind` | 区分 `Workspace` 与 `Host` 命令。 |
| `UIEditorCommandPanelSource` | 描述 panel 路由来自 `None / FixedPanelId / ActivePanel`。 |
| `UIEditorWorkspaceCommandDescriptor` | 把高层命令映射到 `UIEditorWorkspaceCommandKind + panel routing`。 |
| `UIEditorCommandDescriptor` | 单个 editor 命令的完整静态描述。 |
| `UIEditorCommandRegistry` | 命令描述表。 |
| `UIEditorCommandRegistryValidationCode` | 注册表校验失败原因。 |
| `FindUIEditorCommandDescriptor(...)` | 通过 `commandId` 查找描述。 |
| `ValidateUIEditorCommandRegistry(...)` | 校验命令表的完整性与路由合法性。 |
| 成员 | 类型 | 描述 | 默认值 | ## 当前实现行为
|------|------|------|--------|
| `commands` | `std::vector<UIEditorCommandDescriptor>` | 结构体公开字段。 | `{}` | - `ValidateUIEditorCommandRegistry(...)` 会拒绝：
- 空 `commandId`
- 空 `displayName`
- 重复 `commandId`
- host 命令错误携带 workspace panel routing
- 需要 panel 的 workspace 命令却没有 panel source
- 不需要 panel 的命令却错误携带 `FixedPanelId` / `ActivePanel`
- `FindUIEditorCommandDescriptor(...)` 当前按线性遍历 `registry.commands` 查找。
- `CommandKindRequiresPanelId(...)` 当前把 `OpenPanel / ClosePanel / ShowPanel / HidePanel / ActivatePanel` 视为需要 panel 路由；`ResetWorkspace` 不需要。
## 测试与调用链
- `tests/UI/Editor/unit/test_ui_editor_command_registry.cpp`
- 当前覆盖 descriptor 查找、重复 id、空 displayName 和 panel source 校验。
- `new_editor/src/Foundation/UIEditorCommandDispatcher.cpp`
- 直接依赖这份注册表做命令解析和配置校验。
- `new_editor/src/Shell/UIEditorMenuModel.cpp`
- 当前用它决定 menu item 的 command 元数据与启用态来源。
## 相关文档 ## 相关文档
- [当前目录](../Foundation.md) - 返回 `Foundation` 平行目录 - [Foundation](../Foundation.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [UIEditorCommandDispatcher](../UIEditorCommandDispatcher/UIEditorCommandDispatcher.md)
- [UIEditorShortcutManager](../UIEditorShortcutManager/UIEditorShortcutManager.md)
- [UIEditorWorkspaceController](../../Shell/UIEditorWorkspaceController/UIEditorWorkspaceController.md)

75
docs/api/XCEditor/Foundation/UIEditorShortcutManager/UIEditorShortcutManager.md
View File

@@ -1,45 +1,64 @@
# UIEditorShortcutManager # UIEditorShortcutManager
**命名空间**: `XCEngine` **命名空间**: `XCEngine::UI::Editor`
**类型**: `class` **类型**: `class`
**头文件**: `XCEditor/Foundation/UIEditorShortcutManager.h` **头文件**: `XCEditor/Foundation/UIEditorShortcutManager.h`
**描述**: 定义 `XCEditor/Foundation` 子目录中的 `UIEditorShortcutManager` public API。 **描述**: editor 快捷键绑定与调度入口，负责把 `UIShortcutRegistry` 的匹配结果连接到 editor 命令系统。
## 概述 ## 概览
`UIEditorShortcutManager.h` 是 `XCEditor/Foundation` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `UIEditorShortcutManager` 在 `UIShortcutRegistry` 和 `UIEditorCommandDispatcher` 之间增加了一层 editor 语义：
## 声明概览 - 先校验 command registry 和 shortcut binding 是否自洽
- 再根据输入事件和 `UIShortcutContext` 找到最佳匹配 binding
- 最后把匹配结果转换成 editor command dispatch
| 声明 | 类型 | 说明 | 它同时还承担 shortcut 文案格式化，所以 menu bar / context menu 可以直接显示“当前推荐快捷键文本”。
|------|------|------|
| `UIEditorShortcutManagerValidationCode` | `enum class` | 头文件中的公开声明。 |
| `UIEditorShortcutManagerValidationResult` | `struct` | 头文件中的公开声明。 |
| `UIEditorShortcutDispatchStatus` | `enum class` | 头文件中的公开声明。 |
| `UIEditorShortcutDispatchResult` | `struct` | 头文件中的公开声明。 |
| `UIEditorShortcutManager` | `class` | 头文件中的公开声明。 |
## 公共方法 ## 主要声明
| 方法 | 描述 | | 声明 | 角色 |
|------|------| |------|------|
| [UIEditorShortcutManager()](Constructor.md) | 构造对象。 | | `UIEditorShortcutManagerValidationCode` | 快捷键配置校验失败原因。 |
| [GetCommandDispatcher](GetCommandDispatcher.md) | 获取相关状态或对象。 | | `UIEditorShortcutManagerValidationResult` | 快捷键配置校验结果。 |
| [SetHostCommandHandler](SetHostCommandHandler.md) | 设置相关状态或配置。 | | `UIEditorShortcutDispatchStatus` | `NoMatch / Suppressed / Dispatched / Rejected` 四类结果。 |
| [GetHostCommandHandler](GetHostCommandHandler.md) | 获取相关状态或对象。 | | `UIEditorShortcutDispatchResult` | dispatch 后返回的命令 id、scope、owner 和 workspace command 结果。 |
| [GetCommandRegistry](GetCommandRegistry.md) | 获取相关状态或对象。 | | `UIEditorShortcutManager` | 快捷键绑定、校验和调度器本体。 |
| [GetShortcutRegistry](GetShortcutRegistry.md) | 获取相关状态或对象。 |
| [RegisterBinding](RegisterBinding.md) | 注册对象、回调或映射。 | ## 当前实现行为
| [UnregisterBinding](UnregisterBinding.md) | 取消注册对象、回调或映射。 |
| [ClearBindings](ClearBindings.md) | 清空内部数据。 | - `ValidateConfiguration()` 当前会拒绝：
| [ValidateConfiguration](ValidateConfiguration.md) | 公开方法，详见头文件声明。 | - 无效 command registry
| [GetPreferredShortcutText](GetPreferredShortcutText.md) | 获取相关状态或对象。 | - binding 缺少 `commandId`
| [Dispatch](Dispatch.md) | 公开方法，详见头文件声明。 | - binding 指向未知命令
- `keyCode == 0`
- 非 `Global` scope 却没有 `ownerId`
- chord/scope/owner 完全冲突的重复 binding
- `GetPreferredShortcutText(...)` 会按 `Widget > Panel > Window > Global` 的展示优先级挑选 binding，并把 chord 格式化成 `Ctrl+H` 这类文本。
- `Dispatch(...)` 当前流程是：
- 配置校验
- `m_shortcutRegistry.Match(...)`
- 若 `textInputActive == true`，返回 `Suppressed`
- 调用 `m_commandDispatcher.Dispatch(...)`
- 把匹配到的 scope / owner 和 command result 一并回填到结果结构
## 测试与调用链
- `tests/UI/Editor/unit/test_ui_editor_shortcut_manager.cpp`
- 当前覆盖未知命令、冲突 chord、active-panel 路由、panel scope 优先于 global，以及 text-input suppression。
- `tests/UI/Editor/integration/state/shortcut_dispatch/main.cpp`
- 当前验证 shortcut manager 在 editor shell 状态路径上的实际行为。
- `new_editor/src/Shell/UIEditorShellAsset.cpp`
- 当前用 asset 中的 command registry + bindings 构建 editor 快捷键管理器。
- `new_editor/src/Shell/UIEditorMenuModel.cpp`
- 当前通过它读取 shortcut 文案并参与 menu item 启用态生成。
## 相关文档 ## 相关文档
- [当前目录](../Foundation.md) - 返回 `Foundation` 平行目录 - [Foundation](../Foundation.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [UIEditorCommandRegistry](../UIEditorCommandRegistry/UIEditorCommandRegistry.md)
- [UIEditorCommandDispatcher](../UIEditorCommandDispatcher/UIEditorCommandDispatcher.md)
- [UIShortcutRegistry](../../../XCEngine/UI/Input/UIShortcutRegistry/UIShortcutRegistry.md)

40
docs/api/XCEditor/Foundation/UIEditorTheme/UIEditorTheme.md
View File

@@ -1,18 +1,44 @@
# UIEditorTheme # UIEditorTheme
**命名空间**: `XCEngine` **命名空间**: `XCEngine::UI::Editor`
**类型**: `header` **类型**: `theme-accessor header`
**头文件**: `XCEditor/Foundation/UIEditorTheme.h` **头文件**: `XCEditor/Foundation/UIEditorTheme.h`
**描述**: 定义 `XCEditor/Foundation` 子目录中的 `UIEditorTheme` public API。 **描述**: `XCEditor` 默认主题解析入口，向 `Collections / Fields / Shell` 各类控件暴露统一的 metrics 与 palette 访问函数。
## 概述 ## 概览
`UIEditorTheme.h` 是 `XCEditor/Foundation` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `UIEditorTheme.h` 当前不是“主题对象 + 可编辑主题树”，而是一组默认值解析函数。
这组函数把下游控件需要的 theme 数据集中暴露出来，包括：
- `Fields`
- bool / number / text / vector / enum / color / object / asset / property-grid
- `Collections`
- list-view / tree-view / scroll-view / tab-strip
- `Shell`
- menu-bar / menu-popup / status-bar / panel-frame / dock-host / viewport-slot / shell-compose / shell-interaction
## 当前实现行为
- `new_editor/src/Foundation/UIEditorTheme.cpp` 通过 `GetDefaultValue<T>()` + 一组宏生成所有 `ResolveUIEditor*` 默认访问器。
- 每个访问器当前都返回静态默认构造值，生命周期稳定，可安全被多处重复读取。
- 当前还没有：
- 主题资源加载
- runtime 主题切换
- 层叠式 style override
- 按 workspace / panel 定制局部 palette
## 当前调用链
- 多组 `tests/UI/Editor/integration/shell/*/main.cpp` 当前直接依赖这些默认 theme 访问器来构造演示场景。
- `Collections`、`Fields` 和 `Shell` 的控件页当前都把这里视为默认 metrics / palette 的公共来源。
## 相关文档 ## 相关文档
- [当前目录](../Foundation.md) - 返回 `Foundation` 平行目录 - [Foundation](../Foundation.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [Fields](../../Fields/Fields.md)
- [Collections](../../Collections/Collections.md)
- [Shell](../../Shell/Shell.md)