docs(ui): refresh selection model and resources umbrella docs
This commit is contained in:
@@ -6,19 +6,46 @@
|
|||||||
|
|
||||||
**头文件**: `XCEngine/Resources/Resources.h`
|
**头文件**: `XCEngine/Resources/Resources.h`
|
||||||
|
|
||||||
**描述**: 资源模块 umbrella header，统一汇总资源类型、loader、import settings、资源管理器以及资源 IO 辅助入口。
|
**描述**: `Resources` 模块的 umbrella header，统一汇总资源类型、loader、import settings、artifact IO 以及资源管理相关入口。
|
||||||
|
|
||||||
## 概述
|
## 概览
|
||||||
|
|
||||||
`Resources.h` 本身不是某个单独类或系统的实现，而是 `Resources` 模块的聚合入口。它把常用的资源相关 public API 一次性包含进来，主要包括：
|
`Resources.h` 本身不是某个单独类或系统的实现，而是 `Resources` 模块的聚合入口。它把常用的资源相关 public API 一次性包含进来，主要包括：
|
||||||
|
|
||||||
- Core/Asset 层的 `IResource`、`ResourceHandle`、`ResourceManager`、`ResourceCache`、`AsyncLoader`
|
- Core/Asset 层的基础类型
|
||||||
- 各类资源对象与 loader，例如 `Texture`、`Mesh`、`Material`、`Shader`、`AudioClip`
|
- `IResource`
|
||||||
- 资源导入设置与若干资源 IO 辅助类型
|
- `ResourceHandle`
|
||||||
|
- `ResourceManager`
|
||||||
|
- `ResourceCache`
|
||||||
|
- `AsyncLoader`
|
||||||
|
- 常见资源对象与 loader
|
||||||
|
- `Texture` / `TextureLoader` / `TextureImportSettings`
|
||||||
|
- `Mesh` / `MeshLoader` / `MeshImportSettings`
|
||||||
|
- `Material` / `MaterialLoader`
|
||||||
|
- `Shader` / `ShaderLoader`
|
||||||
|
- `AudioClip` / `AudioClipLoader`
|
||||||
|
- `VolumeField` / `VolumeFieldLoader`
|
||||||
|
- `Model` / `ModelLoader`
|
||||||
|
- `GaussianSplat` / `GaussianSplatLoader`
|
||||||
|
- 资源 artifact / IO 辅助入口
|
||||||
|
- `ModelArtifactIO`
|
||||||
|
- `GaussianSplatArtifactIO`
|
||||||
|
- builtin 资源路径入口
|
||||||
|
- `BuiltinResources`
|
||||||
|
|
||||||
适合想一次引入整个资源子系统 public API 的调用方使用。
|
适合想一次性引入整个资源子系统 public API 的调用方使用。
|
||||||
|
|
||||||
|
## 当前作用边界
|
||||||
|
|
||||||
|
- 这是“对外聚合入口”，不是资源系统内部依赖的最小 include 集。
|
||||||
|
- 它优先覆盖调用方最常见的 public API，不保证把 `Resources` 模块下所有内部辅助头文件都一并导出。
|
||||||
|
- 随着 `Model` 和 `GaussianSplat` 进入正式资源链路，这个 umbrella header 也已经把对应类型、artifact IO 和 loader 纳入默认暴露范围。
|
||||||
|
|
||||||
## 相关文档
|
## 相关文档
|
||||||
|
|
||||||
- [当前目录](../Resources.md) - 返回 `Resources` 平行目录
|
- [当前目录](../Resources.md) - 返回 `Resources` 并行目录
|
||||||
- [API 总索引](../../../main.md) - 返回顶层索引
|
- [Model](../Model/Model.md)
|
||||||
|
- [GaussianSplat](../GaussianSplat/GaussianSplat.md)
|
||||||
|
- [Volume](../Volume/Volume.md)
|
||||||
|
- [BuiltinResources](../BuiltinResources/BuiltinResources.md)
|
||||||
|
- [API 总索引](../../../main.md)
|
||||||
|
|||||||
@@ -8,32 +8,60 @@
|
|||||||
|
|
||||||
**源文件**: `engine/src/UI/Widgets/UISelectionModel.cpp`
|
**源文件**: `engine/src/UI/Widgets/UISelectionModel.cpp`
|
||||||
|
|
||||||
**描述**: 单选字符串 id 模型，适合列表、树和属性面板中“当前选中项”这类最基础的选择状态。
|
**描述**: 以字符串 ID 为键的轻量选择模型，支持多选集合和一个“主选中项”，适合列表、树和属性面板这类 UI 控件复用。
|
||||||
|
|
||||||
## 概览
|
## 概览
|
||||||
|
|
||||||
公开接口非常直接：
|
`UISelectionModel` 已经不是早期那种“只保存一个选中 ID”的极简模型。当前公开接口围绕两层状态展开：
|
||||||
|
|
||||||
- `HasSelection()`
|
- `m_selectedIds`
|
||||||
- `GetSelectedId()`
|
保存当前所有选中项，顺序稳定，且会去重
|
||||||
- `IsSelected(...)`
|
- `m_primarySelectedId`
|
||||||
- `SetSelection(...)`
|
表示当前主选中项；通常用于键盘焦点、属性面板绑定或默认操作对象
|
||||||
- `ClearSelection()`
|
|
||||||
- `ToggleSelection(...)`
|
## 当前公开能力
|
||||||
|
|
||||||
|
- 查询接口
|
||||||
|
- `HasSelection()`
|
||||||
|
- `GetSelectedId()`
|
||||||
|
- `GetSelectedIds()`
|
||||||
|
- `GetSelectionCount()`
|
||||||
|
- `HasMultipleSelection()`
|
||||||
|
- `IsSelected(...)`
|
||||||
|
- 覆盖 / 主选中管理
|
||||||
|
- `SetSelection(...)`
|
||||||
|
- `SetSelections(...)`
|
||||||
|
- `SetPrimarySelection(...)`
|
||||||
|
- 增删切换
|
||||||
|
- `AddSelection(...)`
|
||||||
|
- `RemoveSelection(...)`
|
||||||
|
- `ClearSelection()`
|
||||||
|
- `ToggleSelection(...)`
|
||||||
|
- `ToggleSelectionMembership(...)`
|
||||||
|
|
||||||
## 当前实现行为
|
## 当前实现行为
|
||||||
|
|
||||||
- 内部状态当前只有一个 `std::string m_selectedId`。
|
- `SetSelection(...)` 会把整个选择集合替换成单个 ID；传空字符串时等价于清空选择。
|
||||||
- `HasSelection()` 只检查字符串是否为空，因此空字符串等价于“无选择”。
|
- `SetSelections(...)` 会先移除空 ID、再去重；如果未指定 `primarySelectionId`，默认把最后一个有效 ID 设为主选中项。
|
||||||
- `SetSelection(...)` 在传入和当前相同的 id 时返回 `false`；否则直接覆盖当前选中项。
|
- `SetPrimarySelection(...)` 只允许把“已经在选择集合里的项”设为主选中项。
|
||||||
- `ToggleSelection(...)` 在命中当前选中 id 时会清空选择，否则把它设为新的选中项。
|
- `AddSelection(...)` 会把新项追加到集合尾部；当 `makePrimary == true` 或当前没有主选中项时，也会同步更新 `m_primarySelectedId`。
|
||||||
- 当前模型是严格单选，不提供多选集合或 anchor/range 语义。
|
- `RemoveSelection(...)` 删除主选中项时，会把最后一个剩余项提升为新的主选中项；删空后主选中项也会一起清空。
|
||||||
|
- `ToggleSelection(...)` 的语义是“命中则移除，未命中则切成单选”。
|
||||||
|
- `ToggleSelectionMembership(...)` 的语义是“命中则移除，未命中则保留原集合并追加进去”，更适合 Ctrl / Cmd 一类多选交互。
|
||||||
|
|
||||||
|
## 当前实现边界
|
||||||
|
|
||||||
|
- 这是纯逻辑模型，不负责通知、事件派发或视图刷新。
|
||||||
|
- 选择 ID 只是普通字符串，没有内建树层级、range anchor 或排序语义。
|
||||||
|
- 去重和主选中规则都在模型内部固定实现；如果控件需要更复杂的策略，仍要在更上层包装。
|
||||||
|
|
||||||
## 测试与调用链
|
## 测试与调用链
|
||||||
|
|
||||||
- `tests/UI/Core/unit/test_ui_selection_model.cpp` 当前覆盖 set/clear/toggle 的基础行为。
|
- `tests/UI/Core/unit/test_ui_selection_model.cpp` 当前覆盖了单选、多选、主选中切换和 toggle 行为。
|
||||||
|
- 属性编辑、键盘导航或拖拽等 UI 层逻辑可以在此之上复用统一的选择状态约定。
|
||||||
|
|
||||||
## 相关文档
|
## 相关文档
|
||||||
|
|
||||||
- [Widgets](../Widgets.md)
|
- [Widgets](../Widgets.md)
|
||||||
- [UIKeyboardNavigationModel](../UIKeyboardNavigationModel/UIKeyboardNavigationModel.md)
|
- [UIKeyboardNavigationModel](../UIKeyboardNavigationModel/UIKeyboardNavigationModel.md)
|
||||||
|
- [UIDragDropInteraction](../UIDragDropInteraction/UIDragDropInteraction.md)
|
||||||
|
|||||||
Reference in New Issue
Block a user