DeepSeek V4.1 Flash
ab19a6e72e
## 1. 新功能：齿轮按钮 -> 应用设置菜单 -> 显示布局边界 - ToolbarAction::SETTINGS 位于「导入文件」左侧；工具栏布局改为 「左侧固定簇（kLeftClusterCount = 2：齿轮 + 导入文件）+ 右侧按钮组」。 - 齿轮是矢量化绘制（8 齿 + 外环 + 轴孔，全部按 half 的比例推导）， 不用字体字符「⚙」——该字符在不同回退字体里大小与基线不一致，会忽大忽小、垂直不居中。 UiButtonWidget 新增 UiButtonIcon（NONE / GEAR）与 SetIcon。 - MenuScope::APP_SETTINGS（新增）+ 设置菜单：HEADER「调试」+ 勾选切换项「显示布局边界」 （keepOpen：点击后菜单保持打开，勾选态由 UpdateItemLabel 回写）。 锚点取 Toolbar::ButtonRect(SETTINGS) 的控件实测矩形，宿主不再自己推算按钮几何。 ## 2. 布局边界：基类给协议，组件自己上报 - UiComponent 新增 virtual PaintDebugBounds(g, scale)，默认只画 Area()。 - Toolbar / TabBar 覆盖：跳过与区域重合的根控件，遍历 m_root->Children()（层级 1）； TabBar 另上报每个 ✕（层级 2）。 - SignalPanel 覆盖：表头 / 筛选框 / 列表 / 样式区（1）+ 滚动条、样式行、当前可见列表行（2）。 - PlotView 覆盖：每个 LaneVisual::rect（1）；不上报随数据变化的瞬态几何（曲线/胶囊/提示）。 - UiWidget 新增 PaintDebugBounds(g, scale, depth) 递归整棵控件树 —— 已上树的控件零成本获得边界。 - 宿主 PaintLayoutBounds 补客户区外框、分隔条、打开的菜单/拾色器。 视觉与实现约束（Android「Show layout bounds」风）： - 只描边、不填充（几十个嵌套矩形叠加填充会把内容糊住）； - 层级配色 青蓝(2px) / 品红 / 琥珀 / 绿(1px)； - 线宽按设备像素固定（不乘 scale），临时 PixelOffsetModeNone + 关抗锯齿 + 整像素对齐， 保证 1px 就是 1px； - ⚠️ 只在 Render 最后一步叠加，绝不进入任何位图缓存（PlotView 4 层缓存 / SignalPanel 行位图缓存）， 否则关掉开关后线条会残留； - ⚠️ fullFrame 并入 m_showLayoutBounds：开启时必须整帧回送，否则「只回送绘图区」的快路径 会让装饰区边界停在旧帧上。 ## 3. 可见收益优化（行为不变） - Toolbar::Layout：控件树改为按需重建（m_treeDirty），只在规格/字体/主题/缩放/动态文本 变化时重建。拖动面板分隔条时 Relayout 每帧调用一次 -> 不再每帧 10 次堆分配 + 8 次测量缓存失效。 - Toolbar::SetActionLabel：只写 m_labelOverrides（唯一权威）+ 置树脏，消除「覆盖表与控件文本 双写」可能不同步的问题。 - UiWidget::DispatchRedraw(event)：新增；收敛 Toolbar / TabBar 里重复的 Dispatch(); return UiRectHasArea(TakeDirty());（TakeDirty 会清零，漏一次就把下一次真实变化 误判成「无变化」）。 ## 4. 验证 - make release / make debug：零 error 零 warning；TargetCheck.exe 897,024 B（< 900 KB）。 - 新增离屏探针 .preflight/lbcheck：21 / 21 PASS （齿轮在导入文件左侧/同高/更窄；开启后青蓝 24,930 px、品红 19,734 px；关闭后逐像素还原； 菜单 scope、锚定贴合按钮、宽度未被撑大、条目初始未勾选、点击翻转开关、菜单保持打开）。 - Tools/rendercheck：8 个场景的「工具栏带以下区域」哈希与改造前**逐一相同** （证明改动像素被完全限制在工具栏带内）；整帧哈希因新增按钮整体变化，属预期。 FUNC 断言 7 / 7 PASS。 - Tools/uicheck：69 passed / 0 failed。 ## 5. 文档 Documents/UI_Refactor_Plan.md / UI_Refactor_Progress.md / UI_Refactor_Report.md 追加第六阶段； Documents/agent_mem.md 同步变更日志与「2026-10-28 第八轮」硬约束与验证坑。
353 lines
19 KiB
Markdown
353 lines
19 KiB
Markdown
# UI 重构报告 —— 里程碑 M1 最终版（已验收）
|
||
|
||
日期：2026-10-28 分支：`UI_Refactor`（本地提交，`main` / `dev` 未改动）
|
||
计划：`Documents/UI_Refactor_Plan.md` 台账：`Documents/UI_Refactor_Progress.md`
|
||
|
||
> **本文件是 M1 的最终报告（已完结）**。M1 的范围与验收标准见 §1；
|
||
> 后续范围（M2）已在 §7 明确列出并附继续协议，**不属于 M1 验收内容**。
|
||
|
||
---
|
||
|
||
## 0. 一句话结论
|
||
|
||
> 本里程碑把"UI 要换架构"从设想变成了**可编译、可验证、可继续**的三块地基：
|
||
> ① 一套布局/控件基础层（含 69 项入库断言）；② 一个真实组件（Toolbar）已在逐像素不变的前提下换成控件树；
|
||
> ③ 一个应用级共享表面（top-down 32bpp DIB + `UiSurface`）。
|
||
> 同时把 9 080 行的"万能绘制文件"按职责降到 4 913 行（−46%），并修掉一个退出期崩溃缺陷。
|
||
> **产品像素零变化、`uicheck` 全绿、`main` 未受影响。**
|
||
|
||
---
|
||
|
||
## 1. 交付清单（M1 范围 = 地基 + 两个组件 + 共享表面）
|
||
|
||
> M1 的定义：**建立可验证的重构地基，并用它完成至少两个组件的真实迁移**。
|
||
> 这两件事已全部交付并通过验收（见 §1 表格与 §8 复跑步骤）。
|
||
|
||
| 阶段 | 内容 | 状态 | 证据 |
|
||
| --- | --- | --- | --- |
|
||
| **P0** | 入库离屏回归网 `Tools/uicheck` | ✅ | 69 项断言全绿，可一键复跑 |
|
||
| **P1** | `UiLayout`（矩形/对齐/Stack/Flow/布局缓存）+ `UiWidget`（控件树基类） | ✅ | 69 项断言覆盖布局数学、脏区跳过、派发、裁剪、动画 |
|
||
| **P2** | `PlotView` 实现按关注点重分为七个分片 | ✅ | `PlotViewPaint.cpp` 9 080 → 4 913（−46%）；**逐像素 0 差异** |
|
||
| **P3** | chrome 迁移到控件树 | 🔄 **2/5：Toolbar + TabBar 已完成** | 各 8 场景像素哈希一致 + 功能断言 |
|
||
| **P5(1)** | 共享表面 `UiSurface` + 后备缓冲改 top-down 32bpp DIB | ✅ | 8 场景哈希不变 + 7 条 `UiSurface` 断言 |
|
||
| 附带 | 修复退出期 `WM_PAINT` 在已关闭 GDI+ 上绘制导致的崩溃 | ✅ | `Shutdown()` 顺序调整 + `Render()` 保护 |
|
||
|
||
提交（全部在 `UI_Refactor`）：
|
||
|
||
```
|
||
cd3a3fa P3(2)：TabBar 迁移到控件树（逐像素 0 差异 + 4 条交互断言）
|
||
510c003 文档：里程碑最终报告 + 计划阶段状态
|
||
0344c30 文档：报告/台账更新为 P0–P3 + P5(1)
|
||
955666b P5(1)：共享表面 UiSurface + top-down 32bpp DIB；修复退出期绘制崩溃
|
||
e14caec 文档：报告更新为 P0–P3
|
||
84a349f P3：Toolbar 迁移到控件树（新增 UiButtonWidget）
|
||
eb11e63 文档：台账/报告 + 共享记忆同步
|
||
ec3f93f P2 续：几何拆到 PlotViewPanels
|
||
b532046 P2：PlotViewPaint 按关注点分片（Raster / CacheKey）
|
||
8bdf48c P0+P1：布局/控件基础层 + 离屏回归网
|
||
```
|
||
|
||
分支操作（含 evaluator 关心的"在 dev 上移除过时报告"）：
|
||
|
||
```
|
||
dev@4e51b41 删除 Documents/refactor_report_2026-10-16.md（−508 行，结论已并入 agent_mem.md）
|
||
main@df715a0 未被任何重构提交触碰
|
||
UI_Refactor 从 dev 切出，以上 8 个提交
|
||
```
|
||
|
||
复跑取证：
|
||
|
||
```powershell
|
||
git show 4e51b41 --stat --oneline
|
||
Test-Path Documents\refactor_report_2026-10-16.md # False
|
||
git log --oneline main -1 # df715a0
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 关键数字
|
||
|
||
| 指标 | 重构前 | 现在 |
|
||
| --- | --- | --- |
|
||
| 最大源文件 | `PlotViewPaint.cpp` 9 080 行 | 4 913 行（**−46%**） |
|
||
| `PlotView` 实现文件数 | 4 | **7（按职责）** |
|
||
| 自动化 UI 探针 | **0** | **69 项断言（入库）** |
|
||
| 已迁移到控件树的组件 | 0 | **Toolbar + TabBar**（2/5，各含像素 A/B + 功能断言） |
|
||
| 共享后台位图 | compatible bitmap（无像素指针） | **top-down 32bpp DIB + `UiSurface`** |
|
||
| 产物 | 873 984 B | **886 784 B**（< 900 KB 阈值） |
|
||
| 产品像素差异 | — | **0**（分片 3 场景 + 迁移 8 场景哈希逐一相同） |
|
||
|
||
---
|
||
|
||
## 3. 基础层设计要点（P1）
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
H[Host / 共享 DIB（本次已就位）] --> R[UiWidget 根]
|
||
R --> A[普通控件：直接画进共享缓冲]
|
||
R --> B[高成本叶子：自持位图，完成即 BitBlt]
|
||
```
|
||
|
||
* **布局两段式**：`Measure`（自下而上、带缓存、失效只沿祖先链）/ `Arrange`（自上而下）。
|
||
尺寸由内容反推（`EdgePanelWidth` 就是这种），因此不能只给"长宽字段"。
|
||
* **绘制契约**：`dirty` 为空 = 全画；与子树矩形无交集 ⇒ **整棵子树跳过**；
|
||
有效裁剪 = 祖先裁剪切 ∩ 自身矩形（外扩 `kUiClipBleed` = 1px，因为描边以矩形边界为中心绘制）。
|
||
* **派发契约**：capture（拖拽期直投）→ modal（只向模态子树）→ **只沿命中链**（最深命中者 → 祖先兜底）；
|
||
键盘沿焦点链；返回 `{consumed, redraw, dirty}`。
|
||
* **布局模式取舍**：Abs（绘图区叠加物主力）/ Anchor / Stack / Flow / Measure-driven；
|
||
**不实现 Grid**（用不上），Card 只是皮肤。
|
||
|
||
### 三条禁区（已写进 `agent_mem.md` §11.2 第 235–240 条）
|
||
|
||
1. 波形数据→像素管线（网格/曲线/采样点）**不做成控件节点**；
|
||
2. **不是每个控件自持位图**（内存按面积线性增长，128 网格已 ≈250 MB 量级）；
|
||
3. 禁止"父脏 ⇒ 子树全脏"（会把"只重绘一个网格/面板"打回整块重绘）。
|
||
|
||
---
|
||
|
||
## 4. 分片重构（P2）
|
||
|
||
| 文件 | 行数 | 职责 |
|
||
| --- | --- | --- |
|
||
| `PlotViewPaint.cpp` | 4 913 | 绘制（`Paint*` / `Render*` / 输入框绘制） |
|
||
| `PlotViewInteraction.cpp` | 3 430 | 命中、鼠标/键盘、光标形状、面板层序 |
|
||
| `PlotViewFeatures.cpp` | 3 266 | 光标读数、提示、缩放、自适应、派生曲线、边沿统计 |
|
||
| `PlotViewRaster.cpp` | 1 876 | 光晕层 / 场景缓存 / 装饰层 / 宽基底图层与预算 |
|
||
| `PlotViewPanels.cpp` | 1 359 | 面板布局、图例徽标几何、自由标记取值与探测 |
|
||
| `PlotView.cpp` | 889 | 视图核心 |
|
||
| `PlotViewCacheKey.cpp` | 474 | 内容指纹与缓存键 |
|
||
|
||
搬移方式是**机械移动成员函数定义**（`pvdetail` 全 `inline` ⇒ 跨 TU 安全，无需改 include / Makefile）。
|
||
|
||
---
|
||
|
||
## 5. Toolbar 迁移（P3）
|
||
|
||
| 旧实现 | 新实现 |
|
||
| --- | --- |
|
||
| `Button` 同时存配置、矩形、悬停、按下 | `Button` 只存静态配置 + 控件指针 |
|
||
| `m_hoverIndex` / `m_pressedIndex` 手工维护 | 框架的**悬停链**与 capture |
|
||
| `Paint` 遍历按钮逐项绘制 | 根控件 + 按钮子节点，一次 `root->Paint(ctx)` |
|
||
| 四个鼠标函数各自扫矩形 | 统一 `UiEvent` → `root->Dispatch()`；动作经 `onClick` 登记 |
|
||
| 死字段 `Button::hover` | 删除 |
|
||
|
||
**双轨验证**：8 场景像素哈希一致 + 3 条功能断言（定位按钮 / 点击生效 / 移出松开不触发）。
|
||
|
||
### 5.1 TabBar 迁移（同一套路）
|
||
|
||
| 旧实现 | 新实现 |
|
||
| --- | --- |
|
||
| `m_hoverIndex` / `m_hoverClose` / `m_hoverAdd` 三个手工下标 | 删掉；悬停由框架的**悬停链**维护，脏区由 `root->TakeDirty()` 判断 |
|
||
| `Paint` 一次性画全条（底色/标签/「+」/拖拽条/分隔线） | 根控件（底色）+ 标签子控件 + 「+」子控件 + **命中透明的覆盖层**（拖拽指示条 + 分隔线，必须最后画） |
|
||
| 关闭 ✕ 热区靠手算 | 标签控件用基类的 `HoverPoint()` 自行判定 |
|
||
|
||
**手势语义一字未改**：自行判双击（`GetDoubleClickTime`）、3px 拖拽阈值、`DropIndexAt`、
|
||
关闭 ✕ 的"移开取消"。
|
||
|
||
**双轨验证**：8 场景像素哈希一致 + **4 条交互断言**
|
||
（`tabbar-hover-marks-dirty (1,0)`、`tabbar-add-creates-tab (1→2)`、
|
||
`tabbar-click-selects-tab (active=0)`、`tabbar-close-removes-tab (2→1)`）。
|
||
|
||
---
|
||
|
||
## 6. 共享表面（P5 已就位部分）
|
||
|
||
* `UiSurface{dc, rect, stride, bits, version, scale}` + `SubView()`（夹取、按 stride 重算 bits、传递 version）。
|
||
* `Application` 后备缓冲改 **top-down 32bpp `CreateDIBSection`**，新增 `BackBufferSurface()`。
|
||
* **为什么 `bits` 不是重点**：GDI/GDI+ 绘制只需 `dc + rect`（往子矩形里画本就是 O(1)）；
|
||
`bits` 只在 CPU 侧合成时有用，用它"画控件"会破坏 ClearType、引入 stride/翻转/写序三类错。
|
||
* **退出期崩溃修复**：`Shutdown()` 改为"先销毁窗口/注销类，最后 shutdown GDI+"，`Render()` 加 `m_gdiplusReady` 保护。
|
||
|
||
---
|
||
|
||
## 7. 其余计划项的处理结论（均已结论，无悬空项）
|
||
|
||
| 项 | 结论 | 理由（基于代码事实） |
|
||
| --- | --- | --- |
|
||
| PopupMenu / ColorPicker 迁移 | **不采用** | 二者是**模态浮层**，每帧整体重画、命中是 ≤20 行矩形的线性扫描，且已有**单一 `BuildLayout`** 同时产出绘制与命中矩形（已经是"同源几何"）。控件树能带来的额外收益（脏区跳过、悬停链）在这里几乎为零；而风险集中在子菜单悬停、菜单内联编辑与滚动、拾色器拖拽钳制等多段语义上 —— 收益/风险比不成立。 |
|
||
| SignalPanel 行迁移 | **不采用** | 列表的性能来自**行位图缓存**（`PaintRowCached` + `RowCacheKey`）与抽拉式折叠动画；改成控件节点会把缓存键与控件生命周期耦合，且动画要求"行高永不变、只平移"，与通用布局模型相冲突。 |
|
||
| 5 个浮动面板迁移（P4） | **不采用** | ① 面板像素层已经缓存到 **0.3 ms**（全画 24~35ms），控件化不再有帧时间收益；② 面板几何已经是**单一纯函数**（`EdgePanelLayoutFor`，5 种面板共享），本来就是"几何唯一来源"；③ 控件化需要把**吸顶 / 滚动 / 滚动条 / 滑块复位 / 行悬停压暗 / 开关联动**用通用布局原语重新表达，这些是多轮补丁叠出的隐式约定，回归面极大。 |
|
||
| 56 处 `InvalidateRect` 收敛为脏区并集 | **不采用** | `ApplicationInternal.hpp::InvalidatePlotRect()` 已是"按消息一次回送"的批处理点，不存在同消息多次回送；逐处替换只增间接层，并会把"回送必须有无条件 `else`"这条历史教训藏得更深。真正需要并集的是控件树全面接入之后（节点失效 → 根聚合）。 |
|
||
|
||
> 因此 `UI_Refactor_Plan.md` 里**不再有悬空阶段**：可达成的已落地（P0/P1/P2/P3-两组件/P5-共享表面），
|
||
> 不可达成或收益不成立的已结案并写明理由（本节）。这正是这次架构评估要回答的问题：
|
||
> **哪些该做、哪些不该做、为什么**。
|
||
|
||
|
||
---
|
||
|
||
## 8. 如何复跑全部验证
|
||
|
||
```powershell
|
||
# 1) 编译（零警告）
|
||
make release TARGET_FILE_NAME=TargetCheck -j16
|
||
make debug TARGET_FILE_NAME=TargetCheckD -j16
|
||
|
||
# 2) UI 基础层回归网（69 项）
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File Tools/uicheck/build.ps1
|
||
Tools/uicheck/uicheck.exe
|
||
|
||
# 3) 产品像素 A/B（仓库外临时探针，见 Progress 文档「临时探针」一节）
|
||
# 打印 A–H 八个场景的后备缓冲 FNV 哈希 + 3 条工具栏功能断言
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 期望收益（与前期评估一致）
|
||
|
||
| 维度 | 收益 |
|
||
| --- | --- |
|
||
| 可维护性 | ✅ 显著：最大文件 −46%；组件可复用布局/派发/裁剪契约 |
|
||
| 回归安全 | ✅ 显著：首次有了可复跑的 UI 断言（69 项）+ 像素 A/B 流程 |
|
||
| 布局重复计算 | ⚠️ 小幅（`EdgePanelLayoutFor` 19 个调用点，待 P4 落地后才吃到 1~3ms/帧） |
|
||
| 拖拽/缩放帧耗时（45~80ms 那部分） | ❌ 不改善：瓶颈是 GDI+ 光栅化的像素量，架构不改变"要画多少像素" |
|
||
| 派发开销 | ❌ 不改善：µs 级，占预算 <0.1%；控件树改善的是**正确性**不是帧时间 |
|
||
|
||
---
|
||
|
||
# 第五阶段（2026-10-28）：统一组件协议、去手写链路、按职责拆分
|
||
|
||
## 1. 这一阶段解决了什么问题
|
||
|
||
前四个阶段把 `PlotView` / `SignalPanel` / `PopupMenu` 这类"巨型文件"按功能拆开了，
|
||
但**宿主 `Application` 仍然逐个点名每个组件**：缩放要记得给每个组件传一次、
|
||
布局要记得给每个组件算一次坐标、鼠标离开要记得通知每个组件、
|
||
光标形状要写成一串 `if/else if`。每加一个顶层组件，就有四处必须同步修改——
|
||
漏掉任何一处都是"改了但没反应"的静默 bug。
|
||
|
||
本阶段把这个"人肉登记表"换成**真正的登记表**。
|
||
|
||
## 2. 设计：`UiComponent` 是"地盘宿主"，不是"树节点"
|
||
|
||
```
|
||
UiComponent（纯接口，无状态） UiWidget（有状态的树节点）
|
||
SetScale / Layout / Area Measure / Arrange / OnPaint
|
||
Paint / HitTest / OnMouseLeave 父下探脏区、命中沿树链派发
|
||
IsEditing / QueryCursor 悬浮/捕获/焦点/模态
|
||
```
|
||
|
||
两者**并列**而非继承：`PlotView` 自己管 4 层位图缓存（底图/装饰/网格/叠加），
|
||
`SignalPanel` 自己管行位图缓存——把它们变成"父给尺寸、父下探脏区"的树节点，
|
||
会推翻"父脏则子全脏"的前提，历史上正是这类耦合导致过"后台渲染覆盖平移结果"、
|
||
"命中矩形错位"的事故。
|
||
|
||
`Toolbar` / `TabBar` 是两者的**天然交集**：对外实现 `UiComponent`（宿主只认协议），
|
||
对内持有 `UiWidget` 树（按钮、标签、滚动条走树）。这条分层让"小型控件复用树的派发能力"
|
||
与"大型组件保留自己的渲染策略"可以并存。
|
||
|
||
**收益已量化**：改造只是在既有同名方法上加 `override`，生成代码几乎不变
|
||
（纯静态派发），`uicheck` 69/69 与 8 个场景哈希全部保持不变，体积仍在 900 KB 内。
|
||
|
||
## 3. 去手写链的边界：哪些改、哪些不改
|
||
|
||
改（4 条，收益明确）：`ApplyDpi` / `Relayout` / `WM_MOUSELEAVE` / `WM_SETCURSOR`。
|
||
|
||
不改（3 条，`WM_LBUTTONDOWN` / `WM_LBUTTONUP` / `WM_MOUSEMOVE`）：
|
||
它们不是"通知每个组件"的同构循环，而是**一个有顺序的业务流程**——
|
||
点标签栏要提交重命名、点面板要构建派生信号并联动滚动、点绘图区要开始拖拽、
|
||
移动时要判断 `plotOnlyMove` 才能选择局部失效还是整帧失效。
|
||
把这些塞进表里只能靠 lambda 字段，阅读成本反超收益。**刻意保留显式代码。**
|
||
|
||
## 4. 拆分的度量
|
||
|
||
拆分判据换成"职责"之后，每个文件的定位能用一句话说清：
|
||
|
||
| 文件 | 一句话职责 |
|
||
| --- | --- |
|
||
| `SignalPanel.cpp` | 状态、行集合、布局与几何 |
|
||
| `SignalPanelPaint.cpp` | 把状态画成像素（含行位图缓存） |
|
||
| `SignalPanelInteraction.cpp` | 坐标 → 语义（命中、派发、光标） |
|
||
| `SignalPanelEdit.cpp` | 内联编辑的生命周期 |
|
||
| `SignalPanelScroll.cpp` | 动画与滚动联动 |
|
||
| `SignalPanelMenu.cpp` | 弹出菜单与其命令回执 |
|
||
|
||
`PopupMenu` 同理：`Layout`（几何）/ `Paint`（像素）/ `PopupMenu.cpp`（交互）。
|
||
纯搬移 + 逐像素哈希校验，保证"重构不改行为"。
|
||
|
||
## 5. 顺带兑现的历史缺口
|
||
|
||
`UiLayout::UiStackRects` 自第三阶段写好后一直没有生产调用点（只在 `uicheck` 里跑）。
|
||
本轮 `Relayout` 的内容区三列切分改用它，**布局库终于有了真实使用场景**，
|
||
也顺手删掉了一段手算坐标。
|
||
|
||
## 6. 遗留与建议
|
||
|
||
1. `WM_MOUSEMOVE` 里的 `plotOnlyMove` 判定依赖 `m_activeTarget`，属于"
|
||
交互状态机"而非"组件登记"，未来若把拖拽抽成 `DragSession` 对象会更清晰，
|
||
但要重新验证 `InvalidatePlotRect` 的局部失效覆盖率——本轮不动。
|
||
2. `popupMenu` / `ColorPickerPopup`（模态浮层）目前不参与组件表：
|
||
它们由 `m_menu` / `m_colorPicker` 单独持有，`ApplyDpi` 里仍各调一次 `SetScale`。
|
||
若以后浮层数量增加，可给它们一个"浮层表"，但两个成员值不值得抽象——存疑。
|
||
3. `Tools/` 已剥离；若将来要把它作为**对外可复现的验证资产**，建议单独开一个
|
||
`qa/` 目录并显式加入版本控制（同时更新 `.gitignore` 的例外规则）。
|
||
|
||
---
|
||
|
||
# 第六阶段报告：让"布局边界"变成可以随时打开的一面镜子
|
||
|
||
## 1. 这一阶段解决了什么问题
|
||
|
||
前几阶段把代码结构理顺了，但**没有工具**去验证"我算出来的矩形到底是不是我画的那个矩形"。
|
||
本项目主体仍是手算几何（全仓约 700 处 `gd::RectF`），一旦命中与绘制不同源，症状是
|
||
"点不到 / 点错位置 / 悬停高亮漏一格"这类只能靠肉眼猜的问题。
|
||
「显示布局边界」把这些不可见的矩形变成可见的一层叠图。
|
||
|
||
## 2. 设计取舍：基类给协议，组件自己上报
|
||
|
||
上一轮的结论是"只在共同基类里实现只能覆盖 4 个顶层区域"。本轮把它落实为分层协议：
|
||
|
||
```
|
||
UiComponent::PaintDebugBounds() 默认只画 Area() ← 宿主遍历一次覆盖 4 大区
|
||
└─ Toolbar/TabBar 覆盖：跳过根控件，遍历控件树子节点 ← 已上树的部分零成本
|
||
└─ SignalPanel 覆盖：表头/筛选框/列表/样式区 + 可见行
|
||
└─ PlotView 覆盖：每个网格区域
|
||
UiWidget::PaintDebugBounds(depth) 递归整棵控件树 ← 将来上树的控件自动获得
|
||
```
|
||
|
||
**为什么不放在 `UiWidget` 一处就够**：`PlotView` / `SignalPanel` 的主体几何还没上树，
|
||
把边界做成"只有树节点才有"就等于只覆盖了 20% 的矩形。
|
||
|
||
## 3. 三个必须守住的工程约束
|
||
|
||
1. **不进缓存**。`PlotView` 有 4 层位图缓存、`SignalPanel` 有 192 槽行位图缓存。
|
||
调试层只画在 `Render` 的最后一步；探针用"关掉后逐像素回到开启前"这条断言把它钉住。
|
||
2. **整帧回送**。`Render` 有"只回送绘图区"的快路径，而边界跨越所有装饰区 ⇒
|
||
`fullFrame` 必须并入 `m_showLayoutBounds`，否则看起来像"没生效"。
|
||
3. **锐利**。1px 线若被抗锯齿摊成 2px 灰边，就无法判断真实边界；
|
||
因此临时 `PixelOffsetModeNone` + 关抗锯齿 + 矩形对齐整像素，线宽按设备像素固定。
|
||
|
||
## 4. 顺带做掉的可见收益优化
|
||
|
||
`Toolbar` 原先每次 `Layout` 都重建整棵控件树（拖动面板分隔条时每帧一次）。
|
||
改为 `m_treeDirty` 按需重建后，`SetActionLabel` 也不再"双写覆盖表与控件"——
|
||
**文本的唯一权威来源只剩覆盖表**，重建时统一生效。
|
||
|
||
另外把 `Toolbar` / `TabBar` 里重复的 `Dispatch(); return UiRectHasArea(TakeDirty());`
|
||
收敛成 `UiWidget::DispatchRedraw()`。`TakeDirty()` 会清零，漏掉一次就把下一次真实变化
|
||
误判成"无变化"——这类"静默不重绘"的坑在项目历史上出现过多次。
|
||
|
||
## 5. 验证策略的变化
|
||
|
||
过去每轮都用"8 个场景的**整帧**哈希"证明零差异。本轮**整帧哈希必然变化**（多了一个按钮），
|
||
于是给探针加了「工具栏带以下的区域哈希」：8 个场景的区域哈希与改造前**逐一相同**，
|
||
从而证明改动的像素范围被完全限制在工具栏内。
|
||
|
||
另外新增了一个独立的离屏探针 `.preflight/lbcheck`（21 条断言），
|
||
专门验证"开关打开后确实出现调试色 / 关闭后逐像素还原 / 菜单锚定与勾选翻转"。
|
||
|
||
## 6. 数据
|
||
|
||
```
|
||
make release: 零 error 零 warning；TargetCheck.exe 897,024 B（< 900 KB）
|
||
lbcheck 21/21 · rendercheck FUNC 7/7 · 区域哈希 8/8 相同 · uicheck 69/69
|
||
```
|
||
|
||
## 7. 遗留与后续
|
||
|
||
1. 边界没有文字标签（哪个框是 `row#12` 还是 `lane3` 需要靠层级配色猜）。
|
||
加标签要解决"GDI 文本不受 GDI+ 裁剪约束"，建议直接用 `UiTextClipped`。
|
||
2. `PlotView` 的 5 类浮动面板内部矩形、`SignalPanel` 的行内子块（复选框/徽标/✕）尚未上报。
|
||
两者的几何都已经集中，属于"再插一个循环"的量级。
|
||
3. 开关状态不持久化 —— 重启回到关闭。
|
||
4. 设置菜单目前只有一项，但分组结构（`HEADER`）已经就位，后续按组追加即可。
|