110 lines
6.5 KiB
Markdown
110 lines
6.5 KiB
Markdown
# UI
|
||
|
||
**命名空间**: `XCEngine::Editor::UI`
|
||
|
||
**类型**: `submodule`
|
||
|
||
**描述**: 编辑器基于 Dear ImGui 的 UI 基础设施层，负责会话、主题 token、面板 chrome、树视图、属性布局和通用控件封装。
|
||
|
||
## 概述
|
||
|
||
`XCEngine::Editor::UI` 不是单个 widget 库，而是一组逐层叠加的编辑器 UI 基建。它的目标是把 Dear ImGui 这种非常自由、非常底层的即时模式 API 收束成一套可维护的“编辑器内建控件层”。
|
||
|
||
当前源码里，这一层大致可以分成四层：
|
||
|
||
1. **会话与后端层**
|
||
负责 ImGui 上下文、ini 持久化、后端桥接和纹理描述符分配。
|
||
2. **主题与设计 token 层**
|
||
负责颜色、尺寸、间距、dock host 风格与常用视觉常量。
|
||
3. **chrome 与布局层**
|
||
负责面板窗口、工具栏、树视图、splitter、divider、属性行布局和自定义 dock 标签栏。
|
||
4. **语义化控件层**
|
||
负责属性网格、资产卡片、面包屑、弹窗、组件折叠段和各种编辑器专用小部件。
|
||
|
||
这类分层方式非常接近商业级游戏引擎编辑器的组织方式。原因很简单：如果每个面板都直接拼原始 ImGui 调用，代码很快就会变成不可维护的样式杂糅体；而先建设统一 UI 层，后续任何面板重构、主题调整和交互升级都会容易很多。
|
||
|
||
## 聚合头文件
|
||
|
||
**源文件**: `editor/src/UI/UI.h`
|
||
|
||
`UI.h` 当前是一个标准的 umbrella header。它的职责是把 Editor UI 常用 helper 聚合到同一个入口，而不是声明新的运行时类型。
|
||
|
||
因此这页文档直接承担 `UI.h` 的说明职责，不再额外创建一个重复的类型页。
|
||
|
||
## 当前架构重点
|
||
|
||
结合当前 `editor/src/UI/**` 与最近一次 Editor UI 重构，以下几层是现在最值得读的核心：
|
||
|
||
- `ImGuiSession + ImGuiBackendBridge`
|
||
管理 ImGui 上下文、DPI、SRV 描述符与窗口后端对接。
|
||
- `BaseTheme + StyleTokens + DockHostStyle`
|
||
管理设计 token 和 dock host 外观，是全局视觉风格的起点。
|
||
- `Core + DividerChrome + SplitterChrome + DockTabBarChrome + PanelChrome`
|
||
管理窗口 chrome、底边线、拖拽分隔条与自定义 dock 标签栏。
|
||
- `TreeView + BuiltInIcons`
|
||
管理层级树 / 目录树的共享节点表现与图标前缀。
|
||
- `PropertyLayout + ScalarControls + VectorControls + PropertyGrid`
|
||
管理 Inspector 的属性布局、标量控件、向量控件和高层属性编辑入口。
|
||
- `Widgets + PopupState + SceneStatusWidget + AboutEditorDialog`
|
||
提供更接近编辑器业务语义的通用 widget。
|
||
|
||
这次重构里，`TreeView`、`PropertyLayout`、`BuiltInIcons` 和 `DockTabBarChrome` 是最明显的新基础设施，它们共同把原先分散在具体面板中的 UI 技巧沉淀成了复用层。
|
||
|
||
## 设计说明
|
||
|
||
如果把它和 Unity 一类成熟编辑器对照，可以把 `Editor::UI` 理解成“编辑器内部控件系统”，而不是游戏运行时 UI 框架：
|
||
|
||
- 它面向工具开发，不面向游戏内 HUD。
|
||
- 它可以为编辑器体验服务而使用较强约束的 helper。
|
||
- 它允许把某些风格、布局和交互策略写死在共享层，以换取整个工具界面的统一性。
|
||
|
||
这种设计的好处是：
|
||
|
||
- 面板作者写的代码更接近业务语义，而不是样式拼装。
|
||
- 主题、间距、树视图和 Inspector 布局能在全局范围内保持一致。
|
||
- 面板之间可以共享拖拽、上下文菜单、资产卡片、树节点前缀等成熟模式。
|
||
|
||
代价也很明确：
|
||
|
||
- 当前 UI 层明显偏 Editor 私有实现，不是面向外部插件的稳定 ABI。
|
||
- 很多 helper 仍然是 header-only inline 形式，接口演化速度会比较快。
|
||
- 当前实现强依赖 Windows + D3D12 + Dear ImGui 的编辑器运行路径。
|
||
|
||
## 头文件
|
||
|
||
- [AboutEditorDialog](AboutEditorDialog/AboutEditorDialog.md) - `AboutEditorDialog.h`，关于对话框相关 UI。
|
||
- [BaseTheme](BaseTheme/BaseTheme.md) - `BaseTheme.h`，编辑器基础主题安装。
|
||
- [BuiltInIcons](BuiltInIcons/BuiltInIcons.md) - `BuiltInIcons.h`，内置资源/对象图标系统。
|
||
- [ConsoleFilterState](ConsoleFilterState/ConsoleFilterState.md) - `ConsoleFilterState.h`，Console 过滤状态。
|
||
- [ConsoleLogFormatter](ConsoleLogFormatter/ConsoleLogFormatter.md) - `ConsoleLogFormatter.h`，Console 日志格式化。
|
||
- [Core](Core/Core.md) - `Core.h`，底层 ImGui helper 与 popup chrome 包装。
|
||
- [DividerChrome](DividerChrome/DividerChrome.md) - `DividerChrome.h`，统一分隔线绘制。
|
||
- [DockHostStyle](DockHostStyle/DockHostStyle.md) - `DockHostStyle.h`，dock host 风格压栈。
|
||
- [DockTabBarChrome](DockTabBarChrome/DockTabBarChrome.md) - `DockTabBarChrome.h`，自定义 dock 标签栏。
|
||
- [ImGuiBackendBridge](ImGuiBackendBridge/ImGuiBackendBridge.md) - `ImGuiBackendBridge.h`，ImGui 与 D3D12 之间的桥接层。
|
||
- [ImGuiSession](ImGuiSession/ImGuiSession.md) - `ImGuiSession.h`，ImGui 会话生命周期。
|
||
- [PanelChrome](PanelChrome/PanelChrome.md) - `PanelChrome.h`，面板窗口 / 工具栏 / 内容区 RAII 外壳。
|
||
- [PopupState](PopupState/PopupState.md) - `PopupState.h`，延迟弹窗与目标型弹窗状态。
|
||
- [PropertyGrid](PropertyGrid/PropertyGrid.md) - `PropertyGrid.h`，Inspector 级属性编辑入口。
|
||
- [PropertyLayout](PropertyLayout/PropertyLayout.md) - `PropertyLayout.h`，属性行几何布局层。
|
||
- [ScalarControls](ScalarControls/ScalarControls.md) - `ScalarControls.h`，标量属性控件。
|
||
- [SceneStatusWidget](SceneStatusWidget/SceneStatusWidget.md) - `SceneStatusWidget.h`，场景状态部件。
|
||
- [SplitterChrome](SplitterChrome/SplitterChrome.md) - `SplitterChrome.h`，分隔条交互与绘制。
|
||
- [StyleTokens](StyleTokens/StyleTokens.md) - `StyleTokens.h`，Editor UI 设计 token 中心。
|
||
- [TreeView](TreeView/TreeView.md) - `TreeView.h`，树视图共享基础设施。
|
||
- [VectorControls](VectorControls/VectorControls.md) - `VectorControls.h`，向量属性控件。
|
||
- [Widgets](Widgets/Widgets.md) - `Widgets.h`，资产卡片、面包屑、组件折叠段等通用 widget。
|
||
|
||
## 当前实现边界
|
||
|
||
- 这是 Editor 应用层 UI，不是运行时 `engine/include/XCEngine` 风格的公共引擎 API。
|
||
- 当前很多接口仍然直接暴露 ImGui 类型，如 `ImDrawList`、`ImVec2`、`ImGuiID`。
|
||
- 自定义 dock 标签栏、树视图和图标系统都明显面向当前编辑器产品形态，而不是通用 GUI 框架。
|
||
|
||
## 相关文档
|
||
|
||
- [Editor](../Editor.md)
|
||
- [Layout](../Layout/Layout.md)
|
||
- [ComponentEditors](../ComponentEditors/ComponentEditors.md)
|
||
- [Editor Architecture And Workflow](../../../_guides/Editor/Editor-Architecture-And-Workflow.md)
|