diff --git a/docs/api/XCEngine/Editor/UI/PopupState/DeferredPopupState.md b/docs/api/XCEngine/Editor/UI/PopupState/DeferredPopupState.md new file mode 100644 index 00000000..4a968960 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/PopupState/DeferredPopupState.md @@ -0,0 +1,51 @@ +# DeferredPopupState + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `class` + +**源文件**: `editor/src/UI/PopupState.h` + +## 作用 + +表示“下一帧打开一个 ImGui popup”的最小延迟打开状态。 + +## 公开接口 + +```cpp +void RequestOpen(); +void ConsumeOpenRequest(const char* popupId); +bool HasPendingOpenRequest() const; +void Clear(); +``` + +## 当前实现行为 + +- `RequestOpen()` + - 只把内部 `m_openRequested` 设为 `true` + - 当前帧不会立刻调用 `ImGui::OpenPopup(...)` +- `ConsumeOpenRequest(popupId)` + - 只有当存在待消费请求时才会调用 `ImGui::OpenPopup(popupId)` + - 成功消费后会把待开标志清回 `false` +- `HasPendingOpenRequest()` + - 返回当前是否还保留未消费的打开请求 +- `Clear()` + - 只清空待开标志 + +## 典型使用位置 + +- `MainMenuActionRouter` 用它驱动 `Help -> About` +- `InspectorActionRouter` 用它驱动 `Add Component` +- `HierarchyActionRouter` 用它驱动层级空白区域或选项 popup +- `AboutEditorDialog` 会在真正绘制前调用 `ConsumeOpenRequest(...)` + +## 设计含义 + +- 这类 helper 的核心价值是把“请求打开 popup”和“实际调用 `ImGui::OpenPopup()` 的帧时机”分开。 +- 这样调用方不需要自己维护散落的布尔标志。 + +## 相关文档 + +- [PopupState](PopupState.md) +- [TargetedPopupState](TargetedPopupState.md) +- [AboutEditorDialog](../AboutEditorDialog/AboutEditorDialog.md) diff --git a/docs/api/XCEngine/Editor/UI/PopupState/InlineTextEditState.md b/docs/api/XCEngine/Editor/UI/PopupState/InlineTextEditState.md new file mode 100644 index 00000000..cfc2cbeb --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/PopupState/InlineTextEditState.md @@ -0,0 +1,68 @@ +# InlineTextEditState + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `template class` + +**源文件**: `editor/src/UI/PopupState.h` + +## 签名 + +```cpp +template +class InlineTextEditState; +``` + +## 作用 + +为列表项或树节点的“行内重命名”提供目标项、文本缓冲区和首帧聚焦状态。 + +## 公开接口 + +```cpp +void Begin(ItemId itemId, const char* initialValue = ""); +bool IsActive() const; +bool IsEditing(ItemId itemId) const; +ItemId Item() const; +bool ConsumeFocusRequest(); +void SetValue(const char* value); +bool Empty() const; +char* Buffer(); +const char* Buffer() const; +constexpr size_t BufferSize() const; +void Cancel(); +``` + +## 当前实现行为 + +- `Begin(itemId, initialValue)` + - 进入编辑态 + - 记录当前目标项 id + - 把初始文本写入缓冲区 + - 把 `m_focusRequested` 设为 `true` +- `IsEditing(itemId)` + - 只有在当前处于活动编辑态且目标项匹配时返回 `true` +- `ConsumeFocusRequest()` + - 第一次消费时返回 `true`，随后自动清零 + - 适合驱动 `ImGui::SetKeyboardFocusHere()` 一类逻辑 +- `SetValue(...)` + - 用 `strcpy_s` 更新当前缓冲区 +- `Cancel()` + - 退出编辑态 + - 清空目标项、文本缓冲区和待聚焦标志 + +## 典型使用位置 + +- `HierarchyPanel` 用 `InlineTextEditState` 保存实体重命名状态 +- `ProjectPanel` 用 `InlineTextEditState` 保存项目资源项重命名状态 + +## 设计含义 + +- 即时模式 UI 里，行内重命名最麻烦的通常是“哪一项正在编辑”和“进入编辑后只聚焦一次”。 +- 这个 helper 把这两件事一起封装了。 + +## 相关文档 + +- [PopupState](PopupState.md) +- [HierarchyPanel](../../panels/HierarchyPanel/HierarchyPanel.md) +- [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) diff --git a/docs/api/XCEngine/Editor/UI/PopupState/PopupState.md b/docs/api/XCEngine/Editor/UI/PopupState/PopupState.md index b57b0e18..45a9edd6 100644 --- a/docs/api/XCEngine/Editor/UI/PopupState/PopupState.md +++ b/docs/api/XCEngine/Editor/UI/PopupState/PopupState.md @@ -12,19 +12,21 @@ `PopupState.h` 当前包含四类非常实用的 UI 状态辅助类型： -- `DeferredPopupState` -- `TargetedPopupState` -- `TextInputPopupState` -- `InlineTextEditState` +- [DeferredPopupState](DeferredPopupState.md) +- [TargetedPopupState](TargetedPopupState.md) +- [TextInputPopupState](TextInputPopupState.md) +- [InlineTextEditState](InlineTextEditState.md) 它们共同解决一个问题：把 ImGui 的即时模式弹窗交互变成可维护的状态机。 ## 当前实现 -- `DeferredPopupState` 负责“下一帧打开弹窗” -- `TargetedPopupState` 在打开弹窗的同时绑定一个目标对象 -- `TextInputPopupState` 内置固定容量字符缓冲区，适合创建目录等对话框 -- `InlineTextEditState` 适合 Hierarchy 中的行内重命名 +| 类型 | 作用 | +|------|------| +| [DeferredPopupState](DeferredPopupState.md) | 负责“下一帧打开弹窗”。 | +| [TargetedPopupState](TargetedPopupState.md) | 在打开弹窗的同时绑定一个目标对象。 | +| [TextInputPopupState](TextInputPopupState.md) | 内置固定容量字符缓冲区，适合轻量文本输入 popup。 | +| [InlineTextEditState](InlineTextEditState.md) | 适合 Hierarchy / Project 中的行内重命名。 | ## 设计说明 @@ -44,6 +46,10 @@ ## 相关文档 - [UI](../UI.md) +- [DeferredPopupState](DeferredPopupState.md) +- [TargetedPopupState](TargetedPopupState.md) +- [TextInputPopupState](TextInputPopupState.md) +- [InlineTextEditState](InlineTextEditState.md) - [ProjectActionRouter](../../Actions/ProjectActionRouter/ProjectActionRouter.md) - [HierarchyActionRouter](../../Actions/HierarchyActionRouter/HierarchyActionRouter.md) - [AboutEditorDialog](../AboutEditorDialog/AboutEditorDialog.md) diff --git a/docs/api/XCEngine/Editor/UI/PopupState/TargetedPopupState.md b/docs/api/XCEngine/Editor/UI/PopupState/TargetedPopupState.md new file mode 100644 index 00000000..9fd6f59d --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/PopupState/TargetedPopupState.md @@ -0,0 +1,65 @@ +# TargetedPopupState + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `template class` + +**源文件**: `editor/src/UI/PopupState.h` + +## 签名 + +```cpp +template +class TargetedPopupState; +``` + +## 作用 + +在延迟打开 popup 的同时，把一个目标对象或目标句柄绑定到该 popup 状态上。 + +## 公开接口 + +```cpp +void RequestOpen(Target target); +void ConsumeOpenRequest(const char* popupId); +bool HasPendingOpenRequest() const; +bool HasTarget() const; +Target& TargetValue(); +const Target& TargetValue() const; +void Clear(); +``` + +## 当前实现行为 + +- `RequestOpen(target)` + - 会把 `target` 移入 `m_target` + - 把 `m_hasTarget` 设为 `true` + - 再通过内部 `DeferredPopupState` 记录一次待开请求 +- `ConsumeOpenRequest(...)` + - 直接转发给内部 `DeferredPopupState` +- `HasPendingOpenRequest()` + - 返回当前是否还存在未消费的 popup 打开请求 +- `HasTarget()` + - 返回当前是否已绑定有效目标 +- `TargetValue()` + - 返回当前绑定目标 +- `Clear()` + - 清空内部 popup 请求 + - 把目标重置为 `Target{}` + - 把 `m_hasTarget` 设回 `false` + +## 典型使用位置 + +- `HierarchyActionRouter` 用 `TargetedPopupState` 维护实体右键菜单目标 +- `ProjectActionRouter` 用 `TargetedPopupState` 维护项目资源项上下文菜单目标 + +## 当前实现边界 + +- 目标对象的生命周期不由该类型管理。 +- 它只保存一个值或句柄，不做失效检测。 + +## 相关文档 + +- [PopupState](PopupState.md) +- [DeferredPopupState](DeferredPopupState.md) +- [ProjectActionRouter](../../Actions/ProjectActionRouter/ProjectActionRouter.md) diff --git a/docs/api/XCEngine/Editor/UI/PopupState/TextInputPopupState.md b/docs/api/XCEngine/Editor/UI/PopupState/TextInputPopupState.md new file mode 100644 index 00000000..b6206961 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/PopupState/TextInputPopupState.md @@ -0,0 +1,64 @@ +# TextInputPopupState + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `template class` + +**源文件**: `editor/src/UI/PopupState.h` + +## 签名 + +```cpp +template +class TextInputPopupState; +``` + +## 作用 + +为单字段文本输入 popup 提供固定容量缓冲区和延迟打开状态。 + +## 公开接口 + +```cpp +void RequestOpen(const char* initialValue = ""); +void ConsumeOpenRequest(const char* popupId); +void SetValue(const char* value); +void Clear(); +bool Empty() const; +char* Buffer(); +const char* Buffer() const; +constexpr size_t BufferSize() const; +``` + +## 当前实现行为 + +- `RequestOpen(initialValue)` + - 先把初始值写入内部字符缓冲区 + - 再通过内部 `DeferredPopupState` 记录待开请求 +- `ConsumeOpenRequest(...)` + - 转发给内部 popup 状态，在合适帧调用 `ImGui::OpenPopup(...)` +- `SetValue(value)` + - 当传入非空且非空串时，使用 `strcpy_s` 写入缓冲区 + - 否则会把缓冲区首字符置零 +- `Clear()` + - 当前只清空文本缓冲区 + - 不会额外清掉内部 popup 请求状态 +- `Empty()` + - 通过检查首字符是否为 `'\0'` 判断内容是否为空 +- `Buffer()` / `BufferSize()` + - 供 `ImGui::InputText(...)` 一类 API 直接消费 + +## 设计含义 + +- 这个 helper 适合“打开 popup 后输入一段名字”的轻量对话框。 +- 它把常见的 `char buffer[N] + OpenPopup` 模式封装成可复用状态。 + +## 当前实现边界 + +- 容量是模板参数，调用方需要自己选择缓冲区大小。 +- 当前不提供校验、提交态或多字段表单状态。 + +## 相关文档 + +- [PopupState](PopupState.md) +- [DeferredPopupState](DeferredPopupState.md)