# 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)