From 77784fe6d0eb09a57f94b490e32538e4fb73ecd7 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Fri, 3 Apr 2026 13:34:05 +0800 Subject: [PATCH] docs: expand selection manager API docs --- .../ISelectionManager/ISelectionManager.md | 16 +++-- .../ISelectionManager/Selection-Mutations.md | 45 ++++++++++++++ .../ISelectionManager/Selection-Queries.md | 46 +++++++++++++++ .../Constructor-And-EventBus.md | 29 +++++++++ .../SelectionManager/Selection-Mutations.md | 59 +++++++++++++++++++ .../Selection-Queries-And-Event-Publishing.md | 55 +++++++++++++++++ .../Core/SelectionManager/SelectionManager.md | 14 +++++ 7 files changed, 255 insertions(+), 9 deletions(-) create mode 100644 docs/api/XCEngine/Editor/Core/ISelectionManager/Selection-Mutations.md create mode 100644 docs/api/XCEngine/Editor/Core/ISelectionManager/Selection-Queries.md create mode 100644 docs/api/XCEngine/Editor/Core/SelectionManager/Constructor-And-EventBus.md create mode 100644 docs/api/XCEngine/Editor/Core/SelectionManager/Selection-Mutations.md create mode 100644 docs/api/XCEngine/Editor/Core/SelectionManager/Selection-Queries-And-Event-Publishing.md diff --git a/docs/api/XCEngine/Editor/Core/ISelectionManager/ISelectionManager.md b/docs/api/XCEngine/Editor/Core/ISelectionManager/ISelectionManager.md index 0fabfa7e..6c5c7598 100644 --- a/docs/api/XCEngine/Editor/Core/ISelectionManager/ISelectionManager.md +++ b/docs/api/XCEngine/Editor/Core/ISelectionManager/ISelectionManager.md @@ -19,15 +19,13 @@ ## 核心接口 -| 方法 | 作用 | -|------|------| -| `SetSelectedEntity()` | 设置单选对象。 | -| `SetSelectedEntities()` | 设置多选集合。 | -| `AddToSelection()` / `RemoveFromSelection()` | 增删选择。 | -| `ClearSelection()` | 清空选择。 | -| `GetSelectedEntity()` / `GetSelectedEntities()` | 查询当前选择。 | -| `HasSelection()` / `GetSelectionCount()` | 查询选择状态。 | -| `IsSelected()` | 判断某实体是否已选中。 | +### 写操作 + +- [Selection Mutations](Selection-Mutations.md) + +### 读操作 + +- [Selection Queries](Selection-Queries.md) ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Core/ISelectionManager/Selection-Mutations.md b/docs/api/XCEngine/Editor/Core/ISelectionManager/Selection-Mutations.md new file mode 100644 index 00000000..266c8a66 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/ISelectionManager/Selection-Mutations.md @@ -0,0 +1,45 @@ +# ISelectionManager Selection Mutations + +**命名空间**: `XCEngine::Editor` + +**类型**: `interface methods` + +**源文件**: `editor/src/Core/ISelectionManager.h` + +## 签名 + +```cpp +virtual void SetSelectedEntity(uint64_t entityId) = 0; +virtual void SetSelectedEntities(const std::vector& entityIds) = 0; +virtual void AddToSelection(uint64_t entityId) = 0; +virtual void RemoveFromSelection(uint64_t entityId) = 0; +virtual void ClearSelection() = 0; +``` + +## 作用 + +定义编辑器当前选择集合的写操作接口。 + +## 契约语义 + +- `SetSelectedEntity(...)` + - 把当前选择替换成单个实体。 +- `SetSelectedEntities(...)` + - 用给定实体 id 列表整体替换当前多选集合。 +- `AddToSelection(...)` + - 把一个实体追加到当前选择。 +- `RemoveFromSelection(...)` + - 从当前选择中移除一个实体。 +- `ClearSelection()` + - 清空整个选择集合。 + +## 设计含义 + +- `ISelectionManager` 的职责不只是“保存一个当前对象”，而是管理完整的多选集合。 +- 上层面板、命令和事件系统都可以基于这组接口表达单选、多选、追加选择和清空选择。 + +## 相关文档 + +- [ISelectionManager](ISelectionManager.md) +- [Selection Queries](Selection-Queries.md) +- [SelectionManager](../SelectionManager/SelectionManager.md) diff --git a/docs/api/XCEngine/Editor/Core/ISelectionManager/Selection-Queries.md b/docs/api/XCEngine/Editor/Core/ISelectionManager/Selection-Queries.md new file mode 100644 index 00000000..c84b6e8a --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/ISelectionManager/Selection-Queries.md @@ -0,0 +1,46 @@ +# ISelectionManager Selection Queries + +**命名空间**: `XCEngine::Editor` + +**类型**: `interface methods` + +**源文件**: `editor/src/Core/ISelectionManager.h` + +## 签名 + +```cpp +virtual uint64_t GetSelectedEntity() const = 0; +virtual const std::vector& GetSelectedEntities() const = 0; +virtual bool HasSelection() const = 0; +virtual size_t GetSelectionCount() const = 0; +virtual bool IsSelected(uint64_t entityId) const = 0; +``` + +## 作用 + +定义当前选择集合的只读查询接口。 + +## 契约语义 + +- `GetSelectedEntity()` + - 返回当前主选中实体。 +- `GetSelectedEntities()` + - 返回当前完整选择集合。 +- `HasSelection()` + - 查询当前是否存在任何选中项。 +- `GetSelectionCount()` + - 查询当前选择数量。 +- `IsSelected(...)` + - 查询某实体是否位于当前选择集中。 + +## 设计含义 + +- 接口当前同时暴露“主选择”和“完整多选集合”，以支持: + - Inspector 只看主对象 + - Scene View gizmo 和批量操作消费完整集合 + +## 相关文档 + +- [ISelectionManager](ISelectionManager.md) +- [Selection Mutations](Selection-Mutations.md) +- [SelectionManager](../SelectionManager/SelectionManager.md) diff --git a/docs/api/XCEngine/Editor/Core/SelectionManager/Constructor-And-EventBus.md b/docs/api/XCEngine/Editor/Core/SelectionManager/Constructor-And-EventBus.md new file mode 100644 index 00000000..7615b49b --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/SelectionManager/Constructor-And-EventBus.md @@ -0,0 +1,29 @@ +# SelectionManager::SelectionManager + +**命名空间**: `XCEngine::Editor` + +**类型**: `constructor` + +**源文件**: `editor/src/Core/SelectionManager.h` + +## 签名 + +```cpp +explicit SelectionManager(EventBus& eventBus); +``` + +## 作用 + +构造一个基于实体 ID 的选择管理器，并绑定选择变化的事件发布出口。 + +## 当前实现行为 + +- 当前实现只把传入的 `EventBus` 保存到 `m_eventBus`。 +- 选择集合 `m_selectedEntities` 初始为空。 +- 后续所有选择变化都会通过这个 `EventBus` 发布 `SelectionChangedEvent`。 + +## 相关文档 + +- [SelectionManager](SelectionManager.md) +- [Selection Mutations](Selection-Mutations.md) +- [Selection Queries And Event Publishing](Selection-Queries-And-Event-Publishing.md) diff --git a/docs/api/XCEngine/Editor/Core/SelectionManager/Selection-Mutations.md b/docs/api/XCEngine/Editor/Core/SelectionManager/Selection-Mutations.md new file mode 100644 index 00000000..afb67627 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/SelectionManager/Selection-Mutations.md @@ -0,0 +1,59 @@ +# SelectionManager Selection Mutations + +**命名空间**: `XCEngine::Editor` + +**类型**: `method group` + +**源文件**: `editor/src/Core/SelectionManager.h` + +## 签名 + +```cpp +void SetSelectedEntity(uint64_t entityId) override; +void SetSelectedEntities(const std::vector& entityIds) override; +void AddToSelection(uint64_t entityId) override; +void RemoveFromSelection(uint64_t entityId) override; +void ClearSelection() override; +``` + +## 作用 + +实现当前选择集合的更新逻辑，并在每次变更后同步发布事件。 + +## 当前实现行为 + +### `SetSelectedEntity(...)` + +- 当当前选择为空时，直接把该实体 id 压入数组。 +- 否则会把数组第一个元素改成该 id，并把数组裁剪到只剩一个元素。 +- 最后调用 `PublishSelectionChanged()`。 + +### `SetSelectedEntities(...)` + +- 直接用传入 id 列表覆盖 `m_selectedEntities`。 +- 然后调用 `PublishSelectionChanged()`。 + +### `AddToSelection(...)` + +- 只有当 `entityId != 0` 且当前未选中该对象时才会追加。 +- 成功追加后调用 `PublishSelectionChanged()`。 + +### `RemoveFromSelection(...)` + +- 若当前选择中存在该 id，则删除它并调用 `PublishSelectionChanged()`。 + +### `ClearSelection()` + +- 只有当前选择非空时才会真正清空并发布事件。 +- 这避免了无变化情况下重复广播空选择。 + +## 当前实现边界 + +- 当前不会自动去重 `SetSelectedEntities(...)` 传入的重复 id。 +- 当前主选择语义由数组尾元素决定，而不是独立字段。 + +## 相关文档 + +- [SelectionManager](SelectionManager.md) +- [Constructor](Constructor-And-EventBus.md) +- [Selection Queries And Event Publishing](Selection-Queries-And-Event-Publishing.md) diff --git a/docs/api/XCEngine/Editor/Core/SelectionManager/Selection-Queries-And-Event-Publishing.md b/docs/api/XCEngine/Editor/Core/SelectionManager/Selection-Queries-And-Event-Publishing.md new file mode 100644 index 00000000..9ba5f7ec --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/SelectionManager/Selection-Queries-And-Event-Publishing.md @@ -0,0 +1,55 @@ +# SelectionManager Selection Queries And Event Publishing + +**命名空间**: `XCEngine::Editor` + +**类型**: `method group` + +**源文件**: `editor/src/Core/SelectionManager.h` + +## 签名 + +```cpp +uint64_t GetSelectedEntity() const override; +const std::vector& GetSelectedEntities() const override; +bool HasSelection() const override; +size_t GetSelectionCount() const override; +bool IsSelected(uint64_t entityId) const override; +``` + +## 作用 + +提供选择集合查询，并说明当前 `SelectionChangedEvent` 的真实发布载荷。 + +## 当前实现行为 + +### 查询接口 + +- `GetSelectedEntity()` + - 当前选择为空时返回 `0` + - 否则返回数组最后一个元素 +- `GetSelectedEntities()` + - 返回内部 `std::vector` 的 const 引用 +- `HasSelection()` + - 仅检查数组是否为空 +- `GetSelectionCount()` + - 返回数组长度 +- `IsSelected(...)` + - 通过线性查找判断是否选中 + +### 事件发布语义 + +- 内部 `PublishSelectionChanged()` 会构造 `SelectionChangedEvent` +- `event.selectedObjects = m_selectedEntities` +- `event.primarySelection = GetSelectedEntity()` +- 然后通过 `m_eventBus.Publish(event)` 同步发布 + +## 设计含义 + +- 当前实现没有单独维护“主选择”字段，而是把数组最后一个元素当作主选择。 +- 这使查询接口和事件负载保持一致。 + +## 相关文档 + +- [SelectionManager](SelectionManager.md) +- [Constructor](Constructor-And-EventBus.md) +- [Selection Mutations](Selection-Mutations.md) diff --git a/docs/api/XCEngine/Editor/Core/SelectionManager/SelectionManager.md b/docs/api/XCEngine/Editor/Core/SelectionManager/SelectionManager.md index 4e32ddb5..599965ec 100644 --- a/docs/api/XCEngine/Editor/Core/SelectionManager/SelectionManager.md +++ b/docs/api/XCEngine/Editor/Core/SelectionManager/SelectionManager.md @@ -22,6 +22,20 @@ - `GetSelectedEntity()` 返回当前列表最后一个元素。 - 空实体 ID `0` 不会被 `AddToSelection()` 添加。 +## 公开 API + +### 生命周期 + +- [Constructor](Constructor-And-EventBus.md) + +### 选择修改 + +- [Selection Mutations](Selection-Mutations.md) + +### 选择查询与事件发布 + +- [Selection Queries And Event Publishing](Selection-Queries-And-Event-Publishing.md) + ## 当前实现边界 - 当前没有选择历史。