docs: align widgets and editor panel notes with refactor

2026-04-09 23:52:07 +08:00
parent cb3d558aaa
commit 4aaac9887e
5 changed files with 101 additions and 160 deletions
--- a/docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialState/MaterialInspectorMaterialState.md
+++ b/docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialState/MaterialInspectorMaterialState.md
@@ -2,61 +2,39 @@

 **命名空间**: `XCEngine::Editor`

-**类型**: `state structs`
+**类型**: `struct family`

 **源文件**: `editor/src/panels/MaterialInspectorMaterialState.h`

-**描述**: Material Inspector 的本地编辑状态模型，集中保存标签、keyword、属性、render-state 覆盖和加载/dirty/error 标志。
+**描述**: 材质 Inspector 编辑状态头文件，定义标签、关键字、属性以及整个材质资产编辑会话的内存态。

-## 概述
+## 公开声明

-`MaterialInspectorMaterialState.h` 不是一个 panel，而是 `InspectorPanel` 中材质资产编辑流程使用的状态容器集合。当前主要包括：
+| 声明 | 说明 |
+|------|------|
+| `MaterialTagEditRow` | 单条 tag 编辑行 |
+| `MaterialKeywordState` | 单个 shader keyword 的值与 serialized 标志 |
+| `MaterialPropertyState` | 单个材质属性的编辑状态 |
+| `MaterialAssetState` | 一整份材质资产在 Inspector 里的临时编辑状态 |

- `MaterialTagEditRow`
-  - 一行 tag 名/值编辑缓存。
- `MaterialKeywordState`
-  - 单个 shader keyword 的值和是否需要序列化。
- `MaterialPropertyState`
-  - 单个材质属性的编辑态，覆盖 float/int/bool/texture 等值。
- `MaterialAssetState`
-  - 整个材质资产当前在 Inspector 中的编辑快照。
+## 当前角色

-## 当前状态内容
+`MaterialInspectorMaterialState.h` 不负责文件读写，也不直接驱动 UI 绘制。
+它的职责是把材质编辑链路中需要长期驻留在面板里的状态统一收口，包括：

-`MaterialAssetState` 当前收口了：
+- 资产路径与展示名称
+- shader 路径文本
+- render queue / render state override
+- tags / keywords / properties 的 staged 值
+- 错误信息、dirty 标志和 loaded 标志

- 资产路径、全路径和显示名
- `shaderPath` 文本缓冲
- `renderQueue`
- `renderState` 与 `hasRenderStateOverride`
- `tags`
- `keywords`
- `properties`
- `errorMessage`
- `dirty`
- `loaded`
+## 关键语义

-这说明 Inspector 当前并不是直接把 `Material` 运行时对象原地当作 UI 状态使用，而是维护一份偏 authoring/editor 语义的独立快照。
-
-## Reset 语义
-
-`MaterialAssetState::Reset()` 当前会：
-
- 清空路径、名称和错误信息
- 把 `shaderPath` 缓冲归零
- 把 `renderQueue` 还原到 `Geometry`
- 清空 `renderState` override 标志和内容
- 清空 tags / keywords / properties
- 把 `dirty` 与 `loaded` 复位为 `false`
-
-## 当前使用位置
-
- `editor/src/panels/InspectorPanel.h`
- `editor/src/panels/InspectorPanel.cpp`
- [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md) 会基于这份状态做同步与序列化
+- `MaterialAssetState::Reset()` 会把整份编辑状态恢复到初始空态
+- `MaterialPropertyState` 同时覆盖 float/int/bool/texture 四类值槽位
+- `serialized` 标志用于区分“当前值是否显式存在于材质 authoring 文本中”

 ## 相关文档

 - [panels](../panels.md)
 - [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)
- [Material](../../../Resources/Material/Material/Material.md)
--- a/docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md
+++ b/docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md
@@ -6,64 +6,34 @@

 **源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`

-**描述**: Material Inspector 状态与 shader/material/source text 之间的同步 helper，负责属性快照收集、schema 对齐、authoring presence 标记和材质文件文本生成。
+**描述**: 材质 Inspector 状态与 shader / authoring 文本之间的同步与序列化辅助函数集合。

-## 概述
+## 概览

-`MaterialInspectorMaterialStateIO` 把 Material Inspector 的几条关键数据流集中到一起：
+`MaterialInspectorMaterialStateIO.h` 是 [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
+的配套辅助层，负责三类工作：

-1. 从运行时 `Material` 收集可编辑属性状态
-2. 按 shader schema 把现有状态重排、补齐或丢弃
-3. 根据 source text 标记哪些 keyword / property / texture 真正来自作者输入
-4. 把编辑状态重新编码成材质资产文本
+- 从运行时 `Material` 收集属性状态
+- 根据 shader 元数据同步和重置状态
+- 根据当前状态重新生成材质资产文本

 ## 公开函数

 | 函数 | 说明 |
 |------|------|
-| [IsTextureMaterialPropertyType](IsTextureMaterialPropertyType.md) | 判断属性是否属于 texture/cubemap。 |
-| [CollectMaterialPropertyStates](CollectMaterialPropertyStates.md) | 从 `Material` 收集并排序属性编辑状态。 |
-| [SyncMaterialAssetStateWithShader](SyncMaterialAssetStateWithShader.md) | 以 shader schema 为准同步 keyword 与 property 列表，同时尽量保留兼容旧值。 |
-| [ResetMaterialPropertyStateToShaderDefault](ResetMaterialPropertyStateToShaderDefault.md) | 把指定属性恢复到 shader 默认值，并清除 serialized 标志。 |
-| [ApplyMaterialAuthoringPresenceToState](ApplyMaterialAuthoringPresenceToState.md) | 从原始 source text 判断哪些 keyword / property / texture 真正出现在 authoring 文本里。 |
-| [BuildMaterialAssetFileText](BuildMaterialAssetFileText.md) | 按当前状态生成材质资产 JSON 文本。 |
+| `IsTextureMaterialPropertyType(...)` | 判断某个属性类型是否按纹理处理 |
+| `CollectMaterialPropertyStates(...)` | 从 `Material` 抽取属性状态数组 |
+| `SyncMaterialAssetStateWithShader(...)` | 依据 shader 元数据补齐或修正状态 |
+| `ResetMaterialPropertyStateToShaderDefault(...)` | 把指定属性重置为 shader 默认值 |
+| `ApplyMaterialAuthoringPresenceToState(...)` | 根据 authoring 文本标记哪些字段已显式序列化 |
+| `BuildMaterialAssetFileText(...)` | 按当前状态生成材质资产文本 |

-## 当前实现行为
+## 当前角色

- `CollectMaterialPropertyStates(...)` 会优先按 shader property 顺序排序；没有 shader schema 时才退回名字排序。
- `SyncMaterialAssetStateWithShader(...)` 会保留“同名且类型兼容”的旧编辑值，同时丢弃陈旧属性。
- shader pass 里声明的 keyword 会被整理成 `MaterialKeywordState`；之前已启用的 keyword 会尽量保留 `serialized` 状态。
- `ApplyMaterialAuthoringPresenceToState(...)` 会区分：
-  - `properties`
-  - `textures`
-  - `keywords`
-  - `renderState`
-  这样 Inspector 可以知道某项是默认值，还是作者在材质文件里显式写过的覆盖。
- `BuildMaterialAssetFileText(...)` 会省略未序列化的默认项，只写当前确实需要落盘的字段。
- `BuildMaterialAssetFileText(...)` 同时负责把 `renderQueue`、tags、textures 和 `renderState` override 编码成最终 JSON。
-
-## 测试
-
- `tests/Editor/test_material_inspector_material_state_io.cpp` 当前覆盖：
-  - 只标记 source authored 的 entries
-  - 按 shader schema 保留兼容 override 并丢弃陈旧属性
-  - 把声明过的 keyword 补成 disabled entries
-  - 恢复 shader 默认值
-  - 省略未序列化默认值
-  - 写出 texture 与 render-state 覆盖
-
-## 相关函数页面
-
- [IsTextureMaterialPropertyType](IsTextureMaterialPropertyType.md)
- [CollectMaterialPropertyStates](CollectMaterialPropertyStates.md)
- [SyncMaterialAssetStateWithShader](SyncMaterialAssetStateWithShader.md)
- [ResetMaterialPropertyStateToShaderDefault](ResetMaterialPropertyStateToShaderDefault.md)
- [ApplyMaterialAuthoringPresenceToState](ApplyMaterialAuthoringPresenceToState.md)
- [BuildMaterialAssetFileText](BuildMaterialAssetFileText.md)
+这组函数把“面板里的 staged 状态”与“磁盘上的材质 authoring 文件”连接起来，
+因此它们是 Material Inspector 从查看模式走向可编辑模式的关键拼装层。

 ## 相关文档

 - [panels](../panels.md)
 - [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
- [Material](../../../Resources/Material/Material/Material.md)
- [Shader](../../../Resources/Shader/Shader/Shader.md)
--- a/docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md
+++ b/docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md
@@ -2,25 +2,33 @@

 **命名空间**: `XCEngine::Editor`

-**类型**: `historical page`
+**类型**: `legacy panel note`

-**描述**: 历史保留页，记录旧版 editor 曾存在的 XCUI demo panel。当前 `editor/src/panels` 源树里已经没有对应 header，因此这页不再作为 source-backed 的 active panel 文档。
+**描述**: 已退役的 XCUI 过渡演示面板说明页。当前源码树中不再存在 `editor/src/panels/XCUIDemoPanel.h/.cpp`。

 ## 当前状态

- 旧文档引用的 `editor/src/panels/XCUIDemoPanel.h` 已不在当前代码树中。
- 当前 `editor/src/panels` 更接近真实结构的新增 source-backed 页面是：
-  - [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
-  - [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)
- 因此这页应被理解为历史迁移记录，而不是当前 editor 面板目录的 canonical 入口。
+`XCUIDemoPanel` 对应的 panel 实现已经从当前 editor 源树移除，因此这里不再把它描述成“仍在运行中的当前面板”。

-## 保留原因
+## 历史角色

- 旧版文档树里它曾经用于说明 XCUI 到 ImGui 过渡渲染链的实验性 panel。
- 当前保留该页，主要是避免旧链接直接失效，并为后续文档重构提供迁移锚点。
+这个页面保留的原因，是它曾经承担过一段明确的过渡职责：
+
+- 在 editor 仍由 ImGui 承载主工作区时，给 XCUI draw data 提供一个演示入口
+- 通过 `ImGuiTransitionBackend` 把 `UIDrawData` 翻译为 ImGui `ImDrawList`
+- 用于验证 XCUI 绘制命令与编辑器旧前端之间的桥接链路
+
+## 当前替代关系
+
+在当前源码布局里，这条旧链路已经被拆散并下沉到更明确的部件：
+
+- XCUI demo runtime 声明收口到 [XCUIDemoRuntime](../../XCUIBackend/XCUIDemoRuntime/XCUIDemoRuntime.md)
+- 过渡渲染桥接逻辑收口到 [ImGuiTransitionBackend](../../XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md)
+- 通用绘制命令模型仍由 [DrawData](../../../UI/DrawData/DrawData.md) 描述

 ## 相关文档

 - [panels](../panels.md)
+- [XCUIDemoRuntime](../../XCUIBackend/XCUIDemoRuntime/XCUIDemoRuntime.md)
 - [ImGuiTransitionBackend](../../XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md)
 - [DrawData](../../../UI/DrawData/DrawData.md)
--- a/docs/api/XCEngine/UI/Widgets/UIDragDropInteraction/UIDragDropInteraction.md
+++ b/docs/api/XCEngine/UI/Widgets/UIDragDropInteraction/UIDragDropInteraction.md
@@ -2,50 +2,47 @@

 **命名空间**: `XCEngine::UI::Widgets`

-**类型**: `header-only state model + free functions`
+**类型**: `enums + structs + inline free functions`

 **头文件**: `XCEngine/UI/Widgets/UIDragDropInteraction.h`

-**描述**: XCUI 拖放交互 helper，定义拖放 payload、source/target 描述、会话状态与一组纯头文件状态迁移函数。
+**描述**: XCUI 拖放交互 helper，公开拖放操作枚举、source/target/state/result 结构以及整套 begin/update/end/cancel 规则。

 ## 概览

-当前公开声明可以分成四层：
+`UIDragDropInteraction.h` 当前是纯头文件内联实现。
+它把拖放交互拆成四层：

 - `UIDragDropOperation`
-  - `Copy / Move / Link` 三种操作位，以及 `|`、`&`、`|=` 辅助运算。
- `UIDragDropPayload` / `UIDragDropSourceDescriptor` / `UIDragDropTargetDescriptor`
-  - 描述拖拽源、目标和 payload 类型约束。
- `UIDragDropState` / `UIDragDropResult`
-  - 保存拖放会话当前状态，以及每一步更新后回传给调用方的快照结果。
- 一组状态迁移函数
-  - `BeginUIDragDrop(...)`
-  - `UpdateUIDragDropPointer(...)`
-  - `UpdateUIDragDropTarget(...)`
-  - `EndUIDragDrop(...)`
-  - `CancelUIDragDrop(...)`
+  - Copy / Move / Link 能力位
+- 描述符
+  - `UIDragDropSourceDescriptor`
+  - `UIDragDropTargetDescriptor`
+- 运行时状态
+  - `UIDragDropState`
+- 一次交互步骤的输出
+  - `UIDragDropResult`

-## 当前实现行为
+## 当前交互流

- `BeginUIDragDrop(...)` 要求 `ownerId != 0` 且 `allowedOperations != None`，否则直接失败。
- 拖放开始后先进入 `armed` 状态；只有指针移动距离达到 `activationDistance`，`UpdateUIDragDropPointer(...)` 才会把它提升为 `active`。
- `DoesUIDragDropPayloadTypeMatch(...)` 在 `acceptedPayloadTypes` 为空时会把目标视为“接受任意类型”。
- `ResolveUIDragDropOperation(...)` 只会在 source 允许集和 target 接受集的交集中选择操作，并优先满足 target 的 preferred operation。
- `UpdateUIDragDropTarget(...)` 在拖拽未激活、target 为空或类型/操作不匹配时，会清空当前 target 解析结果。
- `EndUIDragDrop(...)` 只有在 `active == true` 且 target 已解析完成时才返回 `completed = true`；否则统一记为 `cancelled = true`。
- 这些 helper 不依赖具体 widget 类型，本质上只是在维护一份 UI 拖放状态机。
+1. `BeginUIDragDrop(...)`
+   - armed 状态建立，但还未 active
+2. `UpdateUIDragDropPointer(...)`
+   - 指针移动距离超过 `activationDistance` 后进入 active
+3. `UpdateUIDragDropTarget(...)`
+   - 根据 payload type、允许操作和 target 偏好解析 preview operation
+4. `EndUIDragDrop(...)`
+   - 若 active 且 target 已解析，则 `completed = true`
+   - 否则 `cancelled = true`

-## 测试与调用链
+## 关键规则

- `tests/UI/Core/unit/test_ui_drag_drop_interaction.cpp` 当前覆盖：
-  - payload type 匹配与操作解析
-  - activation distance 门槛
-  - target 接受/拒绝后的状态快照一致性
-  - 完成与取消路径的结果回填
- `tests/UI/Core/integration/shared/src/DragDropValidationScene.h` 当前直接包含这组 helper，作为交互验证场景的一部分。
+- `acceptedPayloadTypes` 为空时，目标默认接受所有 payload type
+- `PickUIDragDropOperation(...)` 优先尝试 preferred operation，再回退到 Move / Copy / Link
+- `ClearUIDragDropTarget(...)` 只清 target 侧信息，不会取消整个拖放
+- `CancelUIDragDrop(...)` 与 `EndUIDragDrop(...)` 都会把状态整体清零

 ## 相关文档

 - [Widgets](../Widgets.md)
- [UISelectionModel](../UISelectionModel/UISelectionModel.md)
- [UIScreenDocumentHost](../../Runtime/UIScreenDocumentHost/UIScreenDocumentHost.md)
+- [UIScrollModel](../UIScrollModel/UIScrollModel.md)
--- a/docs/api/XCEngine/UI/Widgets/UIScrollModel/UIScrollModel.md
+++ b/docs/api/XCEngine/UI/Widgets/UIScrollModel/UIScrollModel.md
@@ -2,49 +2,37 @@

 **命名空间**: `XCEngine::UI::Widgets`

-**类型**: `free functions + result struct`
+**类型**: `struct + free functions`

 **头文件**: `XCEngine/UI/Widgets/UIScrollModel.h`

 **源文件**: `engine/src/UI/Widgets/UIScrollModel.cpp`

-**描述**: XCUI 纵向/横向滚动的纯函数模型，负责 overflow 计算、offset 裁剪、滚轮步进和“保证某个项可见”的偏移修正。
+**描述**: 轻量滚动模型 helper，提供 overflow 计算、offset 裁剪、滚轮应用和可见区域修正逻辑。

 ## 概览

-当前公开声明包括：
+`UIScrollModel.h` 当前不是一个持久状态类，而是一组围绕滚动 offset 的纯函数 helper。
+这套接口适合列表、树和滚动视图等控件复用同一套基础滚动规则。

- `UIScrollWheelResult`
-  - 返回滚轮处理前后 offset、overflow 和是否真的发生变化。
- `ComputeUIScrollOverflow(...)`
-  - 计算 `contentExtent - viewportExtent` 的有效溢出。
- `ClampUIScrollOffset(...)`
-  - 把 offset 约束到 `[0, overflow]`。
- `ApplyUIScrollWheel(...)`
-  - 把鼠标滚轮 delta 映射到新的滚动偏移。
- `EnsureUIScrollOffsetVisible(...)`
-  - 让指定 item 区间滚进当前 viewport。
+## 公开声明

-## 当前实现行为
+| 声明 | 说明 |
+|------|------|
+| `UIScrollWheelResult` | 一次滚轮应用后的结果快照 |
+| `ComputeUIScrollOverflow(...)` | 计算内容超出 viewport 的距离 |
+| `ClampUIScrollOffset(...)` | 把 offset 限制在合法范围内 |
+| `ApplyUIScrollWheel(...)` | 按滚轮增量更新 offset |
+| `EnsureUIScrollOffsetVisible(...)` | 让指定 item 保证落入当前 viewport |

- `ComputeUIScrollOverflow(...)` 使用 `max(0, contentExtent - viewportExtent)`，没有负溢出概念。
- `ClampUIScrollOffset(...)` 总是把结果限制在 `0` 到 `overflow` 之间。
- `ApplyUIScrollWheel(...)` 以 `120` 为一个标准滚轮单位，默认 `wheelStep = 48.0f`。
- 当 `overflow <= 0`、`fabs(wheelDelta) <= epsilon` 或 `wheelStep <= 0` 时，滚轮处理会直接返回 no-op。
- `ApplyUIScrollWheel(...)` 会先裁剪传入 offset，再计算变化，因此返回结果始终基于有效滚动区间。
- `EnsureUIScrollOffsetVisible(...)` 会把 item 的 `[itemStart, itemStart + itemExtent]` 区间推回 viewport 内，但最终仍会再次 clamp。
+## 当前语义

-## 测试与调用链
-
- `tests/UI/Core/unit/test_ui_scroll_model.cpp` 当前覆盖：
-  - overflow 与 clamp 的边界
-  - 默认滚轮步长 `48`
-  - 被裁剪的 no-op 返回
-  - `EnsureUIScrollOffsetVisible(...)` 的可见性修正
- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前直接包含这组 helper，用于 runtime 文档宿主的滚动计算。
+- overflow 始终按 `max(0, contentExtent - viewportExtent)` 计算
+- offset 始终被裁剪到 `[0, overflow]`
+- 滚轮步长默认 `48.0f`，一格滚轮按 `wheelDelta / 120.0f` 换算
+- `EnsureUIScrollOffsetVisible(...)` 只做“向前滚到 itemStart”或“向后滚到 itemEnd - viewportExtent”这两类修正

 ## 相关文档

 - [Widgets](../Widgets.md)
- [UIKeyboardNavigationModel](../UIKeyboardNavigationModel/UIKeyboardNavigationModel.md)
- [UIScreenDocumentHost](../../Runtime/UIScreenDocumentHost/UIScreenDocumentHost.md)
+- [UIDragDropInteraction](../UIDragDropInteraction/UIDragDropInteraction.md)