diff --git a/Components/Application/Inc/Application.hpp b/Components/Application/Inc/Application.hpp index 730ee8a..3092b09 100644 --- a/Components/Application/Inc/Application.hpp +++ b/Components/Application/Inc/Application.hpp @@ -18,7 +18,7 @@ #include "Theme.hpp" #include "Toolbar.hpp" #include "UiComponent.hpp" -#include "UiDebugBounds.hpp" +#include "UiBox.hpp" #include "UiSurface.hpp" namespace jdi @@ -488,7 +488,7 @@ namespace jdi * 作为成员而不是局部变量：避免开关打开时每帧重新分配， * 也让它能直接充当 `PaintUtil` 的文本收集器（`UiTextRectSink`）。 */ - UiDebugBoxList m_debugBoxes; + UiBoxTable m_debugBoxes; /** @brief 填充组件表（`Initialize` 里 `Setup` 之后调用一次）。 */ void BuildComponentTable(); diff --git a/Components/Application/Inc/ApplicationInternal.hpp b/Components/Application/Inc/ApplicationInternal.hpp index 172696d..cbc0307 100644 --- a/Components/Application/Inc/ApplicationInternal.hpp +++ b/Components/Application/Inc/ApplicationInternal.hpp @@ -30,6 +30,7 @@ #include "Application.hpp" #include "DataLoader.hpp" +#include "MemProbe.hpp" #include "ResourceIds.h" #include "Utf8Util.hpp" diff --git a/Components/Application/Src/Application.cpp b/Components/Application/Src/Application.cpp index 019cad9..46612d5 100644 --- a/Components/Application/Src/Application.cpp +++ b/Components/Application/Src/Application.cpp @@ -53,6 +53,12 @@ namespace jdi { m_instance = instance; + // ⚠️ 本项目以 `-fno-exceptions` 构建（省 `.xdata`+`.pdata` 约 40~60KB）： + // 任何遗漏的分配失败都会走到 `std::terminate`（默认行为是静默 abort，用户只看到程序 + // 突然消失）。这里安装一个兜底处理器：弹一次带建议的模态提示后干净退出。 + // 真正的大块分配已在各处通过 `MemReserveIfRoom()` 预检验（见 `MemProbe.hpp`）。 + MemInstallTerminateHandler(); + // 隐藏窗口启动（自动化/后台）时没人能点掉模态错误框，会自动降级为非模态提示。 SetModalErrorsEnabled(showCommand != SW_HIDE); diff --git a/Components/Application/Src/ApplicationCommands.cpp b/Components/Application/Src/ApplicationCommands.cpp index 8965cb2..97be47a 100644 --- a/Components/Application/Src/ApplicationCommands.cpp +++ b/Components/Application/Src/ApplicationCommands.cpp @@ -1175,21 +1175,21 @@ namespace jdi if (entry.component != nullptr) { m_debugBoxes.SetClip(entry.component->Area()); - entry.component->CollectDebugBoxes(m_debugBoxes); + entry.component->BuildBoxes(m_debugBoxes); } m_debugBoxes.PushLayer(); } // 不属于任何组件的两块：面板分隔条（由宿主直接填充色块）、菜单 / 拾色器（浮层）。 // ⚠️ 浮层**不设裁剪矩形**：菜单的二级子菜单会展开到菜单本体之外，设裁剪会把它裁掉； - // 它们自己会把本体登记为"遮挡矩形"（见 `PopupMenu::CollectDebugBoxes`）， + // 它们自己会把本体登记为"遮挡矩形"（见 `PopupMenu::BuildBoxes`）， // 由绘制阶段把更低层的 box 从浮层区域里挖掉。 m_debugBoxes.SetClip(gd::RectF()); m_debugBoxes.Add(m_splitterRect, 0); m_debugBoxes.PushLayer(); - m_menu.CollectDebugBoxes(m_debugBoxes); + m_menu.BuildBoxes(m_debugBoxes); m_debugBoxes.PushLayer(); - m_colorPicker.CollectDebugBoxes(m_debugBoxes); + m_colorPicker.BuildBoxes(m_debugBoxes); UiDebugPaintBoxList(g, m_debugBoxes); } diff --git a/Components/PlotView/Inc/PlotView.hpp b/Components/PlotView/Inc/PlotView.hpp index 9a525e3..80b4823 100644 --- a/Components/PlotView/Inc/PlotView.hpp +++ b/Components/PlotView/Inc/PlotView.hpp @@ -25,7 +25,7 @@ namespace jdi { - class UiDebugBoxList; + class UiBoxTable; /** * @brief 后台派生曲线计算完成后由 `PlotView` 投递给宿主的自定义消息。 @@ -207,17 +207,17 @@ namespace jdi void Paint(gd::Graphics& g) override; /** - * @brief 收集绘图区区域、**每个网格**、GX 徽标、图例条目与浮动面板的布局边界（调试用）。 + * @brief 上报绘图区区域、**每个网格**、GX 徽标、图例条目与浮动面板的几何 box。 * * 只上报“布局结构”，**不上报**曲线折线、取值胶囊、悬停提示这类随数据/鼠标逐帧变化的 * 瞬态几何 —— 它们每帧都不同，叠上去只是噪声。 * * @param [IN,OUT] boxes 收集器。 */ - void CollectDebugBoxes(UiDebugBoxList& boxes) override; + void BuildBoxes(UiBoxTable& boxes) override; /** - * @brief 强制走「整幅重绘」路径（用于调试叠加层）。 + * @brief 强制走「整幅重绘」路径（供调试叠加层使用）。 * * 平时 `Paint` 会用三条快路径（静态场景贴图 / 宽基底贴图 / 样式补丁）只重画变化部分， * 这在拖动网格滚动条时会**跳过一部分像素**。而调试叠加层（「显示布局边界」）是画在 @@ -226,6 +226,11 @@ namespace jdi * * 因此调试叠加层开启时必须打开本开关：牺牲帧率，换取"每帧都是完整一帧"。 * + * ⚠️ 保留而不优化的理由（2026-10-29 评估）：把它改成“脏矩形 + 独立叠加位图”需要让 + * `Paint` 接受宿主下发的 damage（否则持久后备缓冲区里上一帧的边框像素无处抹除）， + * 而这会穿透 `PlotView` 全部四条快路径与两层缓存。收益只是“调试开关打开时的帧率”、 + * 风险却是用户反复报过的拖拽错位/贴图残留一类事故 —— 故**暂不实施**，仅保留此开关。 + * * @param [IN] force 为 true 时禁用全部快路径且不作画质降级。 */ void SetForceFullRepaint(bool force) { m_forceFullRepaint = force; } diff --git a/Components/PlotView/Inc/PlotViewInternal.hpp b/Components/PlotView/Inc/PlotViewInternal.hpp index 8a39d2f..16bf69b 100644 --- a/Components/PlotView/Inc/PlotViewInternal.hpp +++ b/Components/PlotView/Inc/PlotViewInternal.hpp @@ -29,6 +29,7 @@ #include #include "PlotView.hpp" +#include "MemProbe.hpp" #include "UiControls.hpp" #include "Utf8Util.hpp" diff --git a/Components/PlotView/Src/PlotView.cpp b/Components/PlotView/Src/PlotView.cpp index 00c4acd..62b9192 100644 --- a/Components/PlotView/Src/PlotView.cpp +++ b/Components/PlotView/Src/PlotView.cpp @@ -850,30 +850,10 @@ namespace jdi std::size_t PlotView::AvailablePhysicalBytes() { - // ⚠️ 结果按 200ms 缓存：本函数在绘制路径上每次请求曲线都会调用， - // `GlobalMemoryStatusEx` 是系统调用，逐帧多次调用没有必要（内存变化远慢于 200ms）。 - static std::atomic cachedAt{0}; - static std::atomic cachedBytes{0}; - const std::uint64_t now = GetTickCount64(); - const std::uint64_t last = cachedAt.load(std::memory_order_relaxed); - if (last != 0 && (now - last) < 200) - { - const std::size_t value = cachedBytes.load(std::memory_order_relaxed); - if (value != 0) - { - return value; - } - } - MEMORYSTATUSEX status = {}; - status.dwLength = sizeof(status); - std::size_t available = std::numeric_limits::max(); - if (GlobalMemoryStatusEx(&status) != FALSE) - { - available = static_cast(status.ullAvailPhys); - } - cachedBytes.store(available, std::memory_order_relaxed); - cachedAt.store(now, std::memory_order_relaxed); - return available; + // 统一走 `MemProbe` 的实现：它自带 200ms 缓存，且与"分配前预检验" + // （`MemCanAllocate` / `MemReserveIfRoom`）共用同一份数据 —— + // 历史上这里有一份完全重复的 `GlobalMemoryStatusEx` + 缓存实现。 + return MemAvailablePhysical(); } void PlotView::ShiftLaneRange(int laneIndex, double deltaValue) diff --git a/Components/PlotView/Src/PlotViewPaint.cpp b/Components/PlotView/Src/PlotViewPaint.cpp index 4fa3403..e9ffa2c 100644 --- a/Components/PlotView/Src/PlotViewPaint.cpp +++ b/Components/PlotView/Src/PlotViewPaint.cpp @@ -18,7 +18,7 @@ // ⚠️ 新增函数按**职责**放入对应分片；`PlotView::Paint/PaintLane` 仍只允许定义在本文件。 #include "PlotViewInternal.hpp" -#include "UiDebugBounds.hpp" +#include "UiBox.hpp" #include "UiLayout.hpp" namespace jdi @@ -563,9 +563,9 @@ namespace jdi UiText(g, message, m_fonts->ui, m_area, m_theme->textMuted, TextAlign::CENTER); } - void PlotView::CollectDebugBoxes(UiDebugBoxList& boxes) + void PlotView::BuildBoxes(UiBoxTable& boxes) { - UiComponent::CollectDebugBoxes(boxes); + UiComponent::BuildBoxes(boxes); // 层级 1：每个网格的波形区；层级 2：该网格的 GX 编号徽标。 // ⚠️ **绝不能读 `m_decorRects`**：那里存的是"装饰层位图缓存"的登记矩形， diff --git a/Components/Shared/Inc/ColorPickerPopup.hpp b/Components/Shared/Inc/ColorPickerPopup.hpp index 66976b2..97cd2bd 100644 --- a/Components/Shared/Inc/ColorPickerPopup.hpp +++ b/Components/Shared/Inc/ColorPickerPopup.hpp @@ -15,7 +15,7 @@ namespace jdi { - class UiDebugBoxList; + class UiBoxTable; /** * @brief 浮动式 RGB 自定义颜色拾取器。 @@ -183,7 +183,7 @@ namespace jdi * 面板未打开时什么都不登记。 * @param [IN,OUT] boxes 收集器。 */ - void CollectDebugBoxes(UiDebugBoxList& boxes) const; + void BuildBoxes(UiBoxTable& boxes) const; private: /** diff --git a/Components/Shared/Inc/PopupMenu.hpp b/Components/Shared/Inc/PopupMenu.hpp index 1720017..b242045 100644 --- a/Components/Shared/Inc/PopupMenu.hpp +++ b/Components/Shared/Inc/PopupMenu.hpp @@ -16,7 +16,7 @@ namespace jdi { - class UiDebugBoxList; + class UiBoxTable; /** * @brief 弹出菜单的打开来源，用于把选择结果派发回正确的组件。 @@ -239,7 +239,7 @@ namespace jdi * 菜单未打开时什么都不登记。条目、滚动区、滚动条与二级子菜单各自成为独立的 box。 * @param [IN,OUT] boxes 收集器。 */ - void CollectDebugBoxes(UiDebugBoxList& boxes) const; + void BuildBoxes(UiBoxTable& boxes) const; /** * @brief 菜单是否因内容过长而启用了滚动（条目区可滚动、前导标题与尾部条目固定）。 diff --git a/Components/Shared/Inc/UiBox.hpp b/Components/Shared/Inc/UiBox.hpp new file mode 100644 index 0000000..e0b46df --- /dev/null +++ b/Components/Shared/Inc/UiBox.hpp @@ -0,0 +1,147 @@ +#ifndef __UI_BOX_HPP__ +#define __UI_BOX_HPP__ + +#include +#include +#include + +#include +#include + +#include "PaintUtil.hpp" +#include "Theme.hpp" + +namespace jdi +{ + + /** + * @brief 一个几何 box（**纯值类型**，不含行为、不含生命周期）。 + * + * ## 它是什么 + * + * 描述"某块界面元素占据哪个矩形、属于第几层、在第几个绘制层、被裁在哪个矩形里"。 + * 这就是界面在某一帧的**几何产物**：绘制、命中、调试描边理论上都应该从它派生， + * 而不是各自再算一遍。 + * + * ## 为什么不是控件节点 + * + * 刻意不继承控件基类：`PlotView` 有 4 层自持位图缓存、`SignalPanel` 有行位图缓存， + * 它们要求"像素由组件自己负责"。把几何塞进继承体系会和缓存失效体系打架， + * 而 box 只是一个可复制的矩形 + 几个整数标签。 + * + * ## 为什么 `clip` 与 `rect` 分开存 + * + * 组件内部的元素可能落在地盘之外（典型：滚出可视区的网格，Y 是负数）。 + * 消费方必须能区分"这块几何真实位置在哪"和"它最多能显示到哪"， + * 因此裁剪矩形跟着 box 走，而不是靠全局状态。 + */ + struct UiBox + { + gd::RectF rect; /**< 矩形（客户区坐标）。 */ + gd::RectF clip; /**< 裁剪矩形（= 所属组件的区域；空 = 不裁剪）。 */ + int depth = 0; /**< 层级：0 = 顶层组件区域，≥1 = 内部控件。深 = 更靠近叶子。 */ + int layer = 0; /**< 绘制层：越大越靠上，由 `UiBoxTable::PushLayer` 分配。 */ + }; + + /** + * @brief 几何 box 的收集器（值语义容器，**不含任何绘制代码**）。 + * + * ## 职责边界 + * + * 这里只负责"**累积几何 + 维护裁剪/层/遮挡这些几何事实**"。 + * 怎么把 box 变成屏幕上的线，是 `UiDebugBounds` 的事（那是调试专用的消费者）。 + * 分开的原因：几何是**稳定事实**（命中、遮挡、将来的脏矩形都要用）， + * 而"用彩色包角描边"只服务于一个开关，两者不该长在同一个类里。 + * + * ## 两个排序键缺一不可 + * + * * `layer`：保证**后收集的内容压住先收集的**。没有它，"信号面板的行边界" + * 会盖住"右键弹出的二级菜单"（菜单是后收集的浮层）。 + * * `depth`：同一层内先画父（浅层）再画子（深层），子元素的包角才不被父覆盖。 + * + * ## 开销约束 + * + * 只在宿主开启「显示布局边界」时才被构造和填充 —— 关闭时**零开销** + * （不进绘制路径、不进任何位图缓存）。若将来要用它做常驻命中表， + * 必须显式改为"按需重建"，不能每帧无限期累积。 + */ + class UiBoxTable : public UiTextRectSink + { + public: + /** @brief 清空（复用同一实例时调用），同时把绘制层复位为 0。 */ + void Clear(); + + /** + * @brief 进入下一个绘制层。 + * + * 宿主在每个组件收集完之后调用一次；组件内部若有"浮层压住本体"的情形 + * （例如菜单的二级子菜单）也应在收集子层之前调用。 + */ + void PushLayer() { ++m_layer; } + + /** + * @brief 显式设置当前绘制层（绘制期间收集文本几何时用）。 + * @param [IN] layer 层号（越大越靠上）。 + */ + void SetLayer(int layer) { m_layer = layer; } + + /** @brief 回报一段文本的墨迹矩形（由 `PaintUtil` 在绘制文本时调用）。 */ + void OnTextRect(const gd::RectF& rect) override; + + /** + * @brief 设置后续 box 的裁剪矩形（= 当前组件的区域）。 + * + * ⚠️ **必须像裁剪绘制一样裁剪几何**：组件内部元素可能落在地盘之外 + * （典型：滚出可视区的网格 `lane.rect` 的 Y 会是负数），不裁剪就会登记到相邻组件 + * （工具栏 / 标签栏）的地盘上 —— 这正是用户报告"工具栏上出现大量残留"的直接原因。 + * + * @param [IN] clip 裁剪矩形；传空矩形表示不裁剪。 + */ + void SetClip(const gd::RectF& clip) { m_clip = clip; } + + /** @brief 追加一个 box（空矩形 / 与裁剪矩形无交集的 box 自动忽略）。 */ + void Add(const gd::RectF& rect, int depth); + + /** @brief 追加一组同层级的 box（空矩形逐个忽略）。 */ + void AddAll(const std::vector& rects, int depth); + + /** + * @brief 登记一个**遮挡矩形**（浮层本体，如弹出菜单 / 拾色器）。 + * + * ⚠️ 必须做这件事：box 的消费方是**在所有内容之后**工作的，仅靠 `layer` 排序 + * 只能决定"两个 box 重叠时谁压谁"，并不能阻止"下层组件的边框画在不透明浮层上面"。 + * 登记为遮挡后，**绘制层比它低**的 box 在该区域内会被裁掉。 + * + * @param [IN] rect 遮挡矩形（客户区坐标；空矩形忽略）。 + */ + void AddOccluder(const gd::RectF& rect); + + /** @brief 是否为空。 */ + bool Empty() const { return m_boxes.empty(); } + + /** @brief box 数量。 */ + std::size_t Count() const { return m_boxes.size(); } + + /** @brief 只读访问（**未排序**，消费方需要顺序时自己按 `(layer, depth)` 排序）。 */ + const std::vector& Items() const { return m_boxes; } + + /** @brief 一个遮挡矩形（含它所在的绘制层）。 */ + struct Occluder + { + gd::RectF rect; /**< 遮挡矩形。 */ + int layer = 0; /**< 所在绘制层（只遮挡更低的层）。 */ + }; + + /** @brief 遮挡矩形集合（只读）。 */ + const std::vector& Occluders() const { return m_occluders; } + + private: + std::vector m_boxes; + std::vector m_occluders; + int m_layer = 0; /**< 当前绘制层。 */ + gd::RectF m_clip; /**< 当前裁剪矩形（空 = 不裁剪）。 */ + }; + +} // namespace jdi + +#endif // __UI_BOX_HPP__ diff --git a/Components/Shared/Inc/UiComponent.hpp b/Components/Shared/Inc/UiComponent.hpp index 5e054bf..6693ae1 100644 --- a/Components/Shared/Inc/UiComponent.hpp +++ b/Components/Shared/Inc/UiComponent.hpp @@ -10,7 +10,7 @@ namespace jdi { - class UiDebugBoxList; + class UiBoxTable; /** * @brief 顶层 UI 组件的统一协议（**纯接口，无状态**）。 @@ -77,20 +77,30 @@ namespace jdi } /** - * @brief 收集本组件的**布局边界**（调试用，「显示布局边界」开启时由宿主调用）。 + * @brief 上报本组件的**几何产物**（含子元素的矩形、层级、裁剪、遮挡关系）。 * * 默认实现只登记 `Area()`；自身内部还有可辨识子块（控件树节点、列表行、网格、 * 复选框、徽标、✕、面板控件……）的组件覆盖它，先调本基类再补登记**层级更深**的 box。 * - * 之所以把入口放在这里而不是让宿主逐个点名：宿主只持有 `UiComponent*` 的组件表， - * 遍历一次就能覆盖全部顶层区域；组件内部结构由组件自己上报（只有它知道几何）。 + * ## 为什么入口在组件上 * - * ⚠️ 只在宿主开启「显示布局边界」时才被调用 —— 平时**零开销**（不进任何绘制路径、 - * 不进任何缓存）。实现时**禁止**把几何写进自持位图缓存，否则关掉开关后线条会残留。 + * 宿主只持有 `UiComponent*` 的组件表，遍历一次就能覆盖全部顶层区域； + * 组件内部结构由组件自己上报（只有它知道几何）。新增组件不必再改宿主。 + * + * ## 它是几何，不是调试 + * + * 这里只填 `UiBoxTable`（纯值：矩形 + 层级 + 层号 + 裁剪），**不画任何东西**。 + * “怎么显示”是消费方的事：目前唯一的消费方是「显示布局边界」调试叠加层 + * （`UiDebugPaintBoxList`），将来命中 / 脏矩形也可以从同一张表派生。 + * 这样组件就不需要知道"调试"这个概念的存在。 + * + * ⚠️ 目前它只在宿主开启「显示布局边界」时才被调用 —— 平时**零开销** + *（不进任何绘制路径、不进任何位图缓存）。实现时**禁止**把几何写进自持位图缓存， + * 否则关掉开关后线条会残留。 * * @param [IN,OUT] boxes 收集器（宿主每帧新建，全程只在开关打开时存在）。 */ - virtual void CollectDebugBoxes(UiDebugBoxList& boxes); + virtual void BuildBoxes(UiBoxTable& boxes); }; } // namespace jdi diff --git a/Components/Shared/Inc/UiDebugBounds.hpp b/Components/Shared/Inc/UiDebugBounds.hpp index f84048f..023af58 100644 --- a/Components/Shared/Inc/UiDebugBounds.hpp +++ b/Components/Shared/Inc/UiDebugBounds.hpp @@ -5,16 +5,17 @@ #include #include -#include #include -#include -#include "PaintUtil.hpp" #include "Theme.hpp" +#include "UiBox.hpp" namespace jdi { + // ⚠️ 这个头文件只负责"把几何 box 画成彩色的布局边界线"（调试专用）。 + // 几何本身（`UiBox` / `UiBoxTable`）在 `UiBox.hpp` 里，与绘制无关。 + /** * @brief 布局边界描边颜色（按层级取色）。 * @@ -26,101 +27,7 @@ namespace jdi std::uint32_t UiDebugBoundsColor(int depth); /** - * @brief 一个待显示的布局边界 box（**纯值类型**）。 - * - * 刻意不继承控件基类：`PlotView` 的 4 层位图缓存、`SignalPanel` 的行位图缓存都要求 - * "绘制由组件自己负责"，把几何塞进继承体系会和缓存体系打架。box 只描述 - * "哪里有一个矩形、属于第几层、在第几绘制层"，因此**几何可以被绘制、命中与调试共用**， - * 也不需要任何虚函数或生命周期管理。 - */ - struct UiDebugBox - { - gd::RectF rect; /**< 矩形（客户区坐标）。 */ - gd::RectF clip; /**< 裁剪矩形（= 所属组件的区域；空 = 不裁剪）。 */ - int depth = 0; /**< 层级（决定配色与包角粗细）。 */ - int layer = 0; /**< 绘制层（越大越靠上）：由 `UiDebugBoxList::PushLayer` 分配。 */ - }; - - /** - * @brief box 收集器（值语义容器）。 - * - * 由宿主每帧构造一次、交给各组件填充、再一次性画完 —— 全程只在「显示布局边界」打开时执行。 - * - * ⚠️ **两个排序键缺一不可**： - * * `layer`（绘制层，来自 `PushLayer()`）：保证**后收集的内容压住先收集的**。 - * 没有它，"信号面板的行边界"会盖住"右键弹出的二级菜单"（菜单是后收集的浮层）。 - * * `depth`（层级）：同一层内先画父（浅层）再画子（深层），子元素的彩色包角才不被父覆盖。 - */ - class UiDebugBoxList : public UiTextRectSink - { - public: - /** @brief 清空（复用同一实例时调用），同时把绘制层复位为 0。 */ - void Clear(); - /** - * @brief 进入下一个绘制层。 - * - * 宿主在每个组件收集完之后调用一次；组件内部若有"浮层压住本体"的情形 - * （例如菜单的二级子菜单）也应在收集子层之前调用。 - */ - void PushLayer() { ++m_layer; } - /** - * @brief 显式设置当前绘制层（绘制期间收集文本几何时用）。 - * @param [IN] layer 层号（越大越靠上）。 - */ - void SetLayer(int layer) { m_layer = layer; } - - /** @brief 回报一段文本的墨迹矩形（由 `PaintUtil` 在绘制文本时调用）。 */ - void OnTextRect(const gd::RectF& rect) override; - /** - * @brief 设置后续 box 的裁剪矩形（= 当前组件的区域）。 - * - * ⚠️ **必须像裁剪绘制一样裁剪调试 box**：组件内部元素可能落在地盘之外 - * （典型：滚出可视区的网格 `lane.rect` 的 Y 会是负数），不裁剪就会画到相邻组件 - * （工具栏 / 标签栏）上面 —— 这正是用户报告“工具栏上出现大量残留”的直接原因。 - * - * @param [IN] clip 裁剪矩形；传空矩形表示不裁剪。 - */ - void SetClip(const gd::RectF& clip) { m_clip = clip; } - /** @brief 追加一个 box（空矩形 / 与裁剪矩形无交集的 box 自动忽略）。 */ - void Add(const gd::RectF& rect, int depth); - /** @brief 追加一组同层级的 box（空矩形逐个忽略）。 */ - void AddAll(const std::vector& rects, int depth); - /** - * @brief 登记一个**遮挡矩形**（浮层本体，如弹出菜单 / 拾色器）。 - * - * ⚠️ 必须做这件事：调试 box 是画在所有内容**之后**的，仅靠 `layer` 排序只能决定 - * “两个 box 重叠时谁压谁”，并不能阻止“下层组件的边框线画在不透明浮层上面”。 - * 登记为 occluder 后，**绘制层比它低**的 box 在该区域内会被裁掉， - * 于是观察右键菜单的空间布局时不会被底下的行/网格边界干扰。 - * - * @param [IN] rect 遮挡矩形（客户区坐标；空矩形忽略）。 - */ - void AddOccluder(const gd::RectF& rect); - /** @brief 是否为空。 */ - bool Empty() const { return m_boxes.empty(); } - /** @brief box 数量。 */ - std::size_t Count() const { return m_boxes.size(); } - /** @brief 只读访问（**未排序**，绘制时内部会按 layer/depth 稳定排序）。 */ - const std::vector& Items() const { return m_boxes; } - - /** @brief 一个遮挡矩形（含它所在的绘制层）。 */ - struct Occluder - { - gd::RectF rect; /**< 遮挡矩形。 */ - int layer = 0; /**< 所在绘制层（只遮挡更低的层）。 */ - }; - /** @brief 遮挡矩形集合（只读）。 */ - const std::vector& Occluders() const { return m_occluders; } - - private: - std::vector m_boxes; - std::vector m_occluders; - int m_layer = 0; /**< 当前绘制层。 */ - gd::RectF m_clip; /**< 当前裁剪矩形（空 = 不裁剪）。 */ - }; - - /** - * @brief 绘制一个矩形的布局边界（**四角粗、四边细**，且粗细随矩形尺寸自适应）。 + * @brief 绘制一个矩形的布局边界（**四角粗、四边细**，粗细随矩形尺寸自适应，受 `clip` 裁剪）。 * * 视觉规则： * * 四条边固定 1 设备像素； @@ -138,32 +45,22 @@ namespace jdi * * @param [IN,OUT] g 绘图上下文。 * @param [IN] rect 目标矩形（客户区坐标）。 - * @param [IN] depth 层级（决定配色与包角基础粗细）。 - */ - void UiDebugPaintBounds(gd::Graphics& g, const gd::RectF& rect, int depth); - - /** - * @brief `UiDebugPaintBounds` 的内部实现（带裁剪矩形）。 - * - * 供 `UiDebugPaintBoxList` 使用：非空 `clip` 表示"只在所属组件的地盘内绘制"。 - * - * @param [IN,OUT] g 绘图上下文。 - * @param [IN] rect 目标矩形。 * @param [IN] clip 裁剪矩形（空 = 不裁剪）。 - * @param [IN] depth 层级。 + * @param [IN] depth 层级（决定配色与包角基础粗细）。 */ void UiDebugPaintBoundsClipped(gd::Graphics& g, const gd::RectF& rect, const gd::RectF& clip, int depth); /** - * @brief 一次性画完整个 box 列表（在宿主绘制的最后一步调用）。 + * @brief 一次性画完整个 box 表（在宿主绘制的最后一步调用）。 * * 按 `(layer, depth)` 稳定排序后绘制：后收集的层压住先收集的层，同层内父先子后。 + * `layer` 比某个遮挡矩形低的 box 会被该矩形挖洞裁掉（见 `UiBoxTable::AddOccluder`）。 * * @param [IN,OUT] g 绘图上下文。 - * @param [IN] boxes box 列表。 + * @param [IN] boxes 几何 box 表。 */ - void UiDebugPaintBoxList(gd::Graphics& g, const UiDebugBoxList& boxes); + void UiDebugPaintBoxList(gd::Graphics& g, const UiBoxTable& boxes); } // namespace jdi diff --git a/Components/Shared/Inc/UiWidget.hpp b/Components/Shared/Inc/UiWidget.hpp index d86e03b..ba5191a 100644 --- a/Components/Shared/Inc/UiWidget.hpp +++ b/Components/Shared/Inc/UiWidget.hpp @@ -17,7 +17,7 @@ namespace jdi struct Theme; struct UiFonts; - class UiDebugBoxList; + class UiBoxTable; /** * @brief 裁剪时允许超出控件矩形的像素数（逻辑像素 × scale）。 @@ -217,7 +217,7 @@ namespace jdi * @param [IN,OUT] boxes 收集器。 * @param [IN] depth 层级（0 = 调用者自身，子节点依次 +1，决定描边颜色）。 */ - void CollectDebugBoxes(UiDebugBoxList& boxes, int depth) const; + void BuildBoxes(UiBoxTable& boxes, int depth) const; /** @brief 局部失效：与自身矩形求交后向根冒泡。 */ virtual void Invalidate(const gd::RectF& rect); diff --git a/Components/Shared/Src/ColorPickerPopup.cpp b/Components/Shared/Src/ColorPickerPopup.cpp index 7a51a18..d519cd5 100644 --- a/Components/Shared/Src/ColorPickerPopup.cpp +++ b/Components/Shared/Src/ColorPickerPopup.cpp @@ -1,7 +1,7 @@ #include "ColorPickerPopup.hpp" #include "UiControls.hpp" -#include "UiDebugBounds.hpp" +#include "UiBox.hpp" #include #include #include @@ -1094,7 +1094,7 @@ namespace jdi } } - void ColorPickerPopup::CollectDebugBoxes(UiDebugBoxList& boxes) const + void ColorPickerPopup::BuildBoxes(UiBoxTable& boxes) const { if (!m_open) { diff --git a/Components/Shared/Src/PopupMenu.cpp b/Components/Shared/Src/PopupMenu.cpp index 92b0b0c..ba36203 100644 --- a/Components/Shared/Src/PopupMenu.cpp +++ b/Components/Shared/Src/PopupMenu.cpp @@ -5,7 +5,7 @@ #include "PopupMenuInternal.hpp" #include "UiControls.hpp" -#include "UiDebugBounds.hpp" +#include "UiBox.hpp" #include "UiLayout.hpp" namespace jdi @@ -706,7 +706,7 @@ namespace jdi } - void PopupMenu::CollectDebugBoxes(UiDebugBoxList& boxes) const + void PopupMenu::BuildBoxes(UiBoxTable& boxes) const { if (!m_open) { diff --git a/Components/Shared/Src/UiBox.cpp b/Components/Shared/Src/UiBox.cpp new file mode 100644 index 0000000..238e42c --- /dev/null +++ b/Components/Shared/Src/UiBox.cpp @@ -0,0 +1,63 @@ +#include "UiBox.hpp" + +namespace jdi +{ + + void UiBoxTable::Clear() + { + m_boxes.clear(); + m_occluders.clear(); + m_layer = 0; + m_clip = gd::RectF(); + } + + void UiBoxTable::OnTextRect(const gd::RectF& rect) + { + // 文本用固定层级 4：它总是"最里层"的元素（复选框里的字、行里的信号名…）。 + Add(rect, 4); + } + + void UiBoxTable::Add(const gd::RectF& rect, int depth) + { + if (!(rect.Width > 0.0f) || !(rect.Height > 0.0f)) + { + return; // 空矩形（未布局 / 该元素当前不显示）不登记。 + } + if (m_clip.Width > 0.0f && m_clip.Height > 0.0f) + { + // 与所属组件的区域无交集 ⇒ 已经完全滚出地盘，不必登记（也避免越界登记到邻居的地盘上）。 + if (rect.X + rect.Width <= m_clip.X || rect.X >= m_clip.X + m_clip.Width || + rect.Y + rect.Height <= m_clip.Y || rect.Y >= m_clip.Y + m_clip.Height) + { + return; + } + } + UiBox box; + box.rect = rect; + box.clip = m_clip; + box.depth = (depth < 0) ? 0 : depth; + box.layer = m_layer; + m_boxes.push_back(box); + } + + void UiBoxTable::AddAll(const std::vector& rects, int depth) + { + for (const gd::RectF& rect : rects) + { + Add(rect, depth); + } + } + + void UiBoxTable::AddOccluder(const gd::RectF& rect) + { + if (!(rect.Width > 0.0f) || !(rect.Height > 0.0f)) + { + return; + } + Occluder occluder; + occluder.rect = rect; + occluder.layer = m_layer; + m_occluders.push_back(occluder); + } + +} // namespace jdi diff --git a/Components/Shared/Src/UiComponent.cpp b/Components/Shared/Src/UiComponent.cpp index a72490f..629c369 100644 --- a/Components/Shared/Src/UiComponent.cpp +++ b/Components/Shared/Src/UiComponent.cpp @@ -1,13 +1,13 @@ #include "UiComponent.hpp" -#include "UiDebugBounds.hpp" +#include "UiBox.hpp" namespace jdi { // 默认实现放在 .cpp 而不是头文件内联：`UiComponent.hpp` 是四个大组件都要包含的 - // 公共头，不应把 `UiDebugBounds.hpp`（box 收集器）也拉进它们的编译单元。 - void UiComponent::CollectDebugBoxes(UiDebugBoxList& boxes) + // 公共头，不应把 `UiBox.hpp`（几何收集器）也拉进它们的编译单元。 + void UiComponent::BuildBoxes(UiBoxTable& boxes) { boxes.Add(Area(), 0); } diff --git a/Components/Shared/Src/UiDebugBounds.cpp b/Components/Shared/Src/UiDebugBounds.cpp index f01608f..6bd12e1 100644 --- a/Components/Shared/Src/UiDebugBounds.cpp +++ b/Components/Shared/Src/UiDebugBounds.cpp @@ -77,63 +77,6 @@ namespace jdi } } // namespace - void UiDebugBoxList::Clear() - { - m_boxes.clear(); - m_occluders.clear(); - m_layer = 0; - m_clip = gd::RectF(); - } - - void UiDebugBoxList::OnTextRect(const gd::RectF& rect) - { - // 文本用固定层级 4：它总是"最里层"的元素（复选框里的字、行里的信号名…）。 - Add(rect, 4); - } - - void UiDebugBoxList::Add(const gd::RectF& rect, int depth) - { - if (!(rect.Width > 0.0f) || !(rect.Height > 0.0f)) - { - return; // 空矩形（未布局 / 该元素当前不显示）不登记。 - } - if (m_clip.Width > 0.0f && m_clip.Height > 0.0f) - { - // 与所属组件的区域无交集 ⇒ 已经完全滚出地盘，不必登记（也避免越界画到邻居上）。 - if (rect.X + rect.Width <= m_clip.X || rect.X >= m_clip.X + m_clip.Width || - rect.Y + rect.Height <= m_clip.Y || rect.Y >= m_clip.Y + m_clip.Height) - { - return; - } - } - UiDebugBox box; - box.rect = rect; - box.clip = m_clip; - box.depth = (depth < 0) ? 0 : depth; - box.layer = m_layer; - m_boxes.push_back(box); - } - - void UiDebugBoxList::AddAll(const std::vector& rects, int depth) - { - for (const gd::RectF& rect : rects) - { - Add(rect, depth); - } - } - - void UiDebugBoxList::AddOccluder(const gd::RectF& rect) - { - if (!(rect.Width > 0.0f) || !(rect.Height > 0.0f)) - { - return; - } - Occluder occluder; - occluder.rect = rect; - occluder.layer = m_layer; - m_occluders.push_back(occluder); - } - std::uint32_t UiDebugBoundsColor(int depth) { // 与主题无关的固定配色：调试层必须"永远显眼"，不能跟随用户主题变成接近底色。 @@ -152,11 +95,6 @@ namespace jdi } } - void UiDebugPaintBounds(gd::Graphics& g, const gd::RectF& rect, int depth) - { - UiDebugPaintBoundsClipped(g, rect, gd::RectF(), depth); - } - void UiDebugPaintBoundsClipped(gd::Graphics& g, const gd::RectF& rect, const gd::RectF& clip, int depth) { @@ -174,7 +112,7 @@ namespace jdi return; } - // ⚠️ 与裁剪矩形求交（见 `UiDebugBoxList::SetClip`）：组件内部的元素可能落在地盘之外。 + // ⚠️ 与裁剪矩形求交（见 `UiBoxTable::SetClip`）：组件内部的元素可能落在地盘之外。 // 用 floor/ceil 而不是取整：裁剪是"能看见多少就画多少"，宁可多一像素也不要把 // 紧贴边界的包角整个裁掉。 if (clip.Width > 0.0f && clip.Height > 0.0f) @@ -240,7 +178,7 @@ namespace jdi g.Restore(state); } - void UiDebugPaintBoxList(gd::Graphics& g, const UiDebugBoxList& boxes) + void UiDebugPaintBoxList(gd::Graphics& g, const UiBoxTable& boxes) { if (boxes.Empty()) { @@ -251,14 +189,14 @@ namespace jdi // * `layer` 保证"后收集的（更靠上的浮层）压住先收集的" —— 没有它，信号面板的行边界 // 会盖在右键弹出的二级菜单上面； // * `depth` 保证同一层内先画父再画子，子元素的彩色包角不会被父的边压住。 - std::vector ordered; + std::vector ordered; ordered.reserve(boxes.Count()); - for (const UiDebugBox& box : boxes.Items()) + for (const UiBox& box : boxes.Items()) { ordered.push_back(&box); } std::stable_sort(ordered.begin(), ordered.end(), - [](const UiDebugBox* lhs, const UiDebugBox* rhs) + [](const UiBox* lhs, const UiBox* rhs) { if (lhs->layer != rhs->layer) { @@ -267,14 +205,14 @@ namespace jdi return lhs->depth < rhs->depth; }); - for (const UiDebugBox* box : ordered) + for (const UiBox* box : ordered) { // ⚠️ 遮挡：浮层（菜单 / 拾色器）是不透明的，它上面的内容不该出现下层组件的边框线。 // 仅靠 layer 排序只能决定"两个 box 重叠时谁压谁"，不能阻止"先画的线仍然可见"， // 因此这里把**更高层**的遮挡矩形从裁剪区里排除。 gd::Region region; bool occluded = false; - for (const UiDebugBoxList::Occluder& occluder : boxes.Occluders()) + for (const UiBoxTable::Occluder& occluder : boxes.Occluders()) { if (occluder.layer <= box->layer) { diff --git a/Components/Shared/Src/UiWidget.cpp b/Components/Shared/Src/UiWidget.cpp index 7d726f4..eb537fe 100644 --- a/Components/Shared/Src/UiWidget.cpp +++ b/Components/Shared/Src/UiWidget.cpp @@ -3,7 +3,7 @@ #include #include -#include "UiDebugBounds.hpp" +#include "UiBox.hpp" namespace jdi { @@ -255,7 +255,7 @@ namespace jdi return UiRectHasArea(TakeDirty()); } - void UiWidget::CollectDebugBoxes(UiDebugBoxList& boxes, int depth) const + void UiWidget::BuildBoxes(UiBoxTable& boxes, int depth) const { if (!m_visible || !UiRectHasArea(m_bounds)) { @@ -270,7 +270,7 @@ namespace jdi { if (child != nullptr) { - child->CollectDebugBoxes(boxes, depth + 1); + child->BuildBoxes(boxes, depth + 1); } } } diff --git a/Components/SignalPanel/Inc/SignalPanel.hpp b/Components/SignalPanel/Inc/SignalPanel.hpp index 1669f23..aa4352c 100644 --- a/Components/SignalPanel/Inc/SignalPanel.hpp +++ b/Components/SignalPanel/Inc/SignalPanel.hpp @@ -20,7 +20,7 @@ namespace jdi { - class UiDebugBoxList; + class UiBoxTable; /** * @brief 信号面板弹出菜单的命令标识。 @@ -366,19 +366,19 @@ namespace jdi HCURSOR QueryCursor(int x, int y) override; /** - * @brief 收集面板区域与其内部结构（表头 / 筛选框 / 列表 / 样式区 / 可见行 / 行内元素） - * 的布局边界（调试用）。 + * @brief 上报面板区域与其内部结构（表头 / 筛选框 / 列表 / 样式区 / 可见行 / 行内元素） + * 的几何 box。 * * 行内元素（复选框、色块、名称、GX 徽标、✕、折起三角、组计数）的几何与 * `RowHitPart` / `PaintRow` **同源**：都基于同一个 `RowRect` 与同一批常量， * 因此"画出来的框"就是"能点到的区域"。 * - * 面板的行位图缓存与本函数**无关**：调试 box 只由宿主在最后一步统一描边， - * 不进任何缓存 ⇒ 关掉开关后不会留下残影。 + * 面板的行位图缓存与本函数**无关**：box 只交给宿主在最后一步统一处理（目前是描边）， + * 不进任何缓存 ⇒ 关掉「显示布局边界」后不会留下残影。 * * @param [IN,OUT] boxes 收集器。 */ - void CollectDebugBoxes(UiDebugBoxList& boxes) override; + void BuildBoxes(UiBoxTable& boxes) override; /** * @brief 将列表滚动到指定信号所在位置（无动画，立即到位）。 diff --git a/Components/SignalPanel/Src/SignalPanel.cpp b/Components/SignalPanel/Src/SignalPanel.cpp index 147f92e..9dfe6ee 100644 --- a/Components/SignalPanel/Src/SignalPanel.cpp +++ b/Components/SignalPanel/Src/SignalPanel.cpp @@ -10,7 +10,7 @@ // SignalPanelMenu.cpp 弹出菜单：系数/偏移、镜像、右键菜单与命令回执 #include "SignalPanelInternal.hpp" -#include "UiDebugBounds.hpp" +#include "UiBox.hpp" #include "UiLayout.hpp" namespace jdi @@ -72,9 +72,9 @@ namespace jdi return UiPointInRect(m_area, static_cast(x), static_cast(y)); } - void SignalPanel::CollectDebugBoxes(UiDebugBoxList& boxes) + void SignalPanel::BuildBoxes(UiBoxTable& boxes) { - UiComponent::CollectDebugBoxes(boxes); + UiComponent::BuildBoxes(boxes); if (m_fonts == nullptr || !UiRectHasArea(m_area)) { diff --git a/Components/TabBar/Inc/TabBar.hpp b/Components/TabBar/Inc/TabBar.hpp index b53987b..391f397 100644 --- a/Components/TabBar/Inc/TabBar.hpp +++ b/Components/TabBar/Inc/TabBar.hpp @@ -225,10 +225,10 @@ namespace jdi bool HitTest(int x, int y) const override; /** - * @brief 收集标签栏区域、**每个标签条 / 新建按钮 / 标签 ✕** 的布局边界（调试用）。 + * @brief 上报标签栏区域、**每个标签条 / 新建按钮 / 标签 ✕** 的几何 box。 * @param [IN,OUT] boxes 收集器。 */ - void CollectDebugBoxes(UiDebugBoxList& boxes) override; + void BuildBoxes(UiBoxTable& boxes) override; private: /** diff --git a/Components/TabBar/Src/TabBar.cpp b/Components/TabBar/Src/TabBar.cpp index 00a07be..60abe4c 100644 --- a/Components/TabBar/Src/TabBar.cpp +++ b/Components/TabBar/Src/TabBar.cpp @@ -5,7 +5,7 @@ #include #include -#include "UiDebugBounds.hpp" +#include "UiBox.hpp" #include "Utf8Util.hpp" namespace jdi @@ -484,9 +484,9 @@ namespace jdi return UiPointInRect(m_area, static_cast(x), static_cast(y)); } - void TabBar::CollectDebugBoxes(UiDebugBoxList& boxes) + void TabBar::BuildBoxes(UiBoxTable& boxes) { - UiComponent::CollectDebugBoxes(boxes); + UiComponent::BuildBoxes(boxes); if (m_root != nullptr) { // ⚠️ 跳过根控件：它的矩形与标签栏区域完全重合（已被上一层登记过）。 @@ -495,7 +495,7 @@ namespace jdi { if (child != nullptr) { - child->CollectDebugBoxes(boxes, 1); + child->BuildBoxes(boxes, 1); } } } diff --git a/Components/Toolbar/Inc/Toolbar.hpp b/Components/Toolbar/Inc/Toolbar.hpp index 92ee379..f4482f4 100644 --- a/Components/Toolbar/Inc/Toolbar.hpp +++ b/Components/Toolbar/Inc/Toolbar.hpp @@ -154,10 +154,10 @@ namespace jdi bool HitTest(int x, int y) const override; /** - * @brief 收集工具栏区域、**每个按钮**与按钮内容（文本/图标）的布局边界（调试用）。 + * @brief 上报工具栏区域、**每个按钮**与按钮内容（文本/图标）的几何 box。 * @param [IN,OUT] boxes 收集器。 */ - void CollectDebugBoxes(UiDebugBoxList& boxes) override; + void BuildBoxes(UiBoxTable& boxes) override; private: /** diff --git a/Components/Toolbar/Src/Toolbar.cpp b/Components/Toolbar/Src/Toolbar.cpp index 3015c91..62cef66 100644 --- a/Components/Toolbar/Src/Toolbar.cpp +++ b/Components/Toolbar/Src/Toolbar.cpp @@ -4,7 +4,7 @@ #include #include -#include "UiDebugBounds.hpp" +#include "UiBox.hpp" namespace jdi { @@ -351,9 +351,9 @@ namespace jdi return UiPointInRect(m_area, static_cast(x), static_cast(y)); } - void Toolbar::CollectDebugBoxes(UiDebugBoxList& boxes) + void Toolbar::BuildBoxes(UiBoxTable& boxes) { - UiComponent::CollectDebugBoxes(boxes); + UiComponent::BuildBoxes(boxes); if (m_root == nullptr) { return; diff --git a/Documents/UI_Refactor_Plan.md b/Documents/UI_Refactor_Plan.md index da633a1..7d95ed6 100644 --- a/Documents/UI_Refactor_Plan.md +++ b/Documents/UI_Refactor_Plan.md @@ -1,594 +1,153 @@ -# UI 重构计划（UI_Refactor 分支） +# Just DataInspector UI 重构 —— 计划 -> 目标读者：本项目的后续 Agent（可能是另一台设备 / 另一个模型）。 -> 本文是**唯一施工蓝图**；实时进度见 `Documents/UI_Refactor_Progress.md`，最终结论见 `Documents/UI_Refactor_Report.md`。 -> 硬约束的权威来源仍是 `Documents/agent_mem.md`（§11.2）；本文与之冲突时**以 agent_mem.md 为准**。 +> 本文档只描述**要做什么、为什么这么做、怎么验收**。 +> 已完成情况见 `UI_Refactor_Progress.md`，结论与遗留见 `UI_Refactor_Report.md`。 +> 最后更新：2026-10-29 --- -## 0. 为什么要重构（量化基线） +## 1. 目标与非目标 -| 指标 | 现状 | 出处 | +### 1.1 目标 + +| # | 目标 | 判据 | | --- | --- | --- | -| `PlotViewPaint.cpp` | **9 080 行**（注释 1 295 / 空行 517 / 仅大括号 2 026 / **有效代码 5 242**） | `Get-Content \| Measure-Object` | -| `PlotView.hpp` | 3 649 行、**310 个方法**、**203 个成员变量**、31 个嵌套类型 | 同上 | -| `EdgePanelLayoutFor` | **651 行**、**19 个调用点**，每帧被命中/层序/光标/绘制各算一遍 | `Select-String` | -| `Application.cpp` 的 `InvalidateRect` | **56 处** + 手写 `m_chromeDirty` / `m_panelDirty` / `panelOnly` / `fullFrame` 组合 | 同上 | -| 动画 | **5 套**手写动画散在 3 个组件，共用一个 10ms 定时器 | 同上 | -| 自动化 UI 探针 | **0**（`.preflight` 已被删除且被 gitignore） | 仓库现状 | +| G1 | 收敛"宿主点名每个组件"的散乱结构 | 宿主只遍历一张组件表，不再 `if (component == plot)` 式分支 | +| G2 | 几何只有**一处**来源 | "画出来的形状"与"能点到的区域"由同一批函数给出，不再各算一遍 | +| G3 | 源码按**职责**分片，单片可读 | 单个 `.cpp` 不超过约 1200 行；文件名与内容一致 | +| G4 | 减小产物体积，且**仍然只有一个 `.exe`** | 体积比基线小，无新增依赖 DLL | +| G5 | 关闭 C++ 异常后**不牺牲健壮性** | 所有大块分配前有预检验；OOM 有可见提示 | +| G6 | 重构**不得改变任何绘制像素** | 8 个场景的逐像素哈希与基线逐一相同 | -`PlotViewPaint.cpp` 里混住四类内容：真绘制 ≈3.5k / 光栅化缓存 ≈2.5k / 缓存键 ≈1.1k / **布局与命中几何 ≈1.3k**。 +### 1.2 非目标（明确不做） -**五条根因** - -1. 上次拆 13 695 行大文件时按**函数名**（"带 `Paint` 前缀"）而非**关注点**分片 ⇒ 缓存、缓存键、面板布局、命中几何全被倒进 paint 分片。 -2. 没有控件抽象 ⇒ 每个叠加层自带"几何 + 命中 + 绘制 + 缓存键"四份重复；5 个实验性面板各 800~1 200 行，靠 10 多个平行数组（`rowRefs/rowChecks/rowPoints/rowOrder/rowLevelTracks/...`）下标对齐"假装"成树。 -3. GDI / GDI+ 双栈妥协被**每个绘制点重复支付**（GDI 文本不认 GDI+ 裁剪、`UiFillRect` 的 GDI 快路径绕过裁剪、GDI 文本忽略 alpha…）。 -4. "必须混进缓存键，否则贴旧像素"这条不变量**没有归属**（4 套手写 key + 一堆 `Collect*` ≈1.1k 行；历史 ≥4 次真实 BUG 是"忘了混一个字段"）。 -5. 1 295 行硬核"为什么"注释让行数虚高 —— **保留，不删**（多 Agent 协作防回归的核心资产）。 +* **不把编译产物拆成 DLL**：本项目的定位是"单文件、拷过去就能跑的轻量工具"。 + 任何以拆 DLL 换体积的方案一律否决。 +* **不改优化等级**（`-Oz` 保持不变）。 +* **不把"波形"与"网格线"拆成两层位图**：像素级平移不变量会被破坏。 +* **不为体积牺牲可维护性**（例如放弃分片、放弃几何同源）。 --- -## 1. 设计目标与非目标 +## 2. 硬约束 -### 1.1 目标（必须达成） - -1. **几何只算一次**：布局是"按需失效的 pass"，命中/绘制/光标共用同一份结果。 -2. **失效从布尔变矩形**：`dirty ∩ bounds` 为空 ⇒ 整棵子树跳过（这是唯一真正省钱的层次）。 -3. **裁剪契约统一**：`Paint` 进入时同时收紧 GDI 裁剪与 GDI+ 裁剪，根治"文字画到图例/工具栏上"这类已出现 3 次的 BUG。 -4. **缓存键有归属**：由"持有该内容的节点"产生，父层只聚合。 -5. **事件派发显式化**：`{consumed, redraw, dirtyRect}` 代替 `bool 要不要重绘`；capture / 模态 / hover / 焦点 / 光标仲裁由基类提供。 -6. **动画统一 tick**：一个动画列表 + 现有 `kScrollTimerId` 推进。 -7. **零行为变更的先行阶段**：先拆文件、补回归网，再动语义。 - -### 1.2 非目标（明确不做，写进禁区） - -| 禁区 | 原因 | -| --- | --- | -| ❌ 波形数据→像素管线控件化（网格/曲线/采样点不做成节点） | 布局与虚调用会进每帧热路径；采样/顶点量与控件无关 | -| ❌ 每个控件自持位图 | 内存按面积线性增长：逐网格图层已是屏幕面积 2 倍（5 网格 ≈16MB，**128 网格 ≈250MB**） | -| ❌ "父脏 ⇒ 子树全脏" | 会把"只重绘一个网格/一个面板"打回整块重绘（历史最易发生的退化） | -| ❌ 多线程光栅 | GDI+ 内部串行，实测 **1.03x**；且后台改写 `m_area`/`ViewMin` 会覆盖用户平移（第一代已因此回退） | -| ❌ 逐控件细粒度像素缓存 | 画一个按钮 20~80µs vs 贴图 5~10µs ⇒ 净亏损，还要付"忘混键"的风险 | -| ❌ 引入属性对象体系（学 Blink） | 那是为 Blink 规模准备的；本项目用"节点产生 key"即可 | - -### 1.3 借鉴来源与取舍 - -| 借鉴 | 采纳 | 说明 | -| --- | --- | --- | -| Chromium `views::View` 的**失效驱动布局 pass** | ✅ 全采纳 | 对应 §3 的 `UiWidget::Measure/Arrange` + `UiLayoutCache` | -| `views::View::PaintChildren` 的**脏矩形下探** | ✅ 全采纳 | 对应 §4 的 `PaintContext.dirty` | -| `SetPaintToLayer()` 只提升**少数**子树 | ✅ 保持现状量级（4 层） | 不再新增层 | -| `cc` 的**记录-光栅分离 / tiling / checkerboarding / 每帧预算** | ✅ 已具备，不改 | `PolylineCacheEntry`、宽基底+补条、贴过期但位置正确、`RenderPendingLaneRebuilds(1)` | -| `cc` 的**多线程光栅 / GPU 合成** | ❌ 不采纳 | GDI+ 无 GPU 路径；并行实测 1.03x | -| Dear ImGui 的**每帧全量重画** | ❌ 不采纳 | 本项目整幅重绘 ≈80ms，必须走失效 | +1. **单一可执行文件**：不得引入额外的 `.dll` / 运行时依赖。 +2. **体积预警阈值 = 1MB（1,048,576 B）**。这不是硬上限：超过仍可发布， + 但必须主动提醒用户，并说明"超在哪一段（`.text` / `.rdata` / `.xdata`+`.pdata` / `.rsrc`）、 + 由哪个改动贡献"。旧的 900KB / 800KB 红线**已作废**。 +3. **异常处理用预检验，不用 try/catch**：`-fno-exceptions` 下 `try/catch` 不会被编译， + 因此所有"按数据规模预留大块内存"的地方必须先问 `MemReserveIfRoom()`。 +4. **像素级零回归**：验收以 `Tools/rendercheck` 的 8 个场景哈希为准。 +5. **中文注释按 UTF-8 无 BOM 保存**；构建参数用 `-finput-charset=UTF-8 -fexec-charset=GBK`。 --- -## 2. 目标架构 +## 3. 分层架构（L0–L3） -```mermaid -flowchart TD - H[UiHost
持有 app-sized 32bpp top-down DIB
z 序 · 脏区并集 · 一次 BitBlt 回送 · 动画 tick] - H --> R[UiRoot : UiWidget] - R --> D{脏区树
dirty ∩ bounds 空 ⇒ 整棵子树 return} - D --> A[普通控件：直接画进共享缓冲
按钮 / 文本 / 列表行 / 时间轴 / 图例] - D --> B[高成本叶子：自持位图，完成即 BitBlt 贴回
波形网格 / 装饰层 / 光晕 / 浮动面板] - A --> S[SurfaceView{ dc, rect, stride, bits, version }] - B --> S +``` +L3 体积与异常策略 -fno-exceptions / MemProbe / LTO / gc-sections + ▲ +L2 重绘范围控制 UiDamage（脏矩形） ← 本轮评估后**缓做**，见 §5 + ▲ +L1 几何产物层 UiBox / UiBoxTable / UiComponent::BuildBoxes + ▲ +L0 组件协议 UiComponent + 组件表 + UiWidget 控件树 ``` -**分层原则** +### L0 组件协议（前几轮已完成） -- **共享一张缓冲**：省内存、免分配抖动、合成顺序天然确定。 -- **只有高成本叶子自持缓冲**：这是"把重画换成贴图"的唯一手段。 -- **脏区向下取交集**（不是并集）。 -- **布局由下往上、每帧最多一轮 Measure**；尺寸由内容反推（`EdgePanelWidth` 就是这种）。 +* `UiComponent`：`SetScale / Layout / Area / Paint / HitTest / OnMouseLeave / IsEditing / QueryCursor`。 +* 宿主持有一张**有序组件表**，逐个遍历；新增组件不必改宿主的 5 处消息分支。 +* `UiWidget` 与 `UiComponent` 是**兄弟**而非父子：前者管"一块区域内部的布局/命中/绘制"， + 后者管"自己这一整块地盘：区域、缓存、局部重绘策略"。 + `Toolbar` / `TabBar` 同时是两者。 -### 2.1 新增文件 +### L1 几何产物层（本轮完成） -| 文件 | 职责 | 依赖 | -| --- | --- | --- | -| `Components/Shared/Inc/UiLayout.hpp` / `Src/UiLayout.cpp` | 纯几何：`UiInsets`、栈/流/锚点/对齐、`UiLayoutCache` | 仅 `Theme.hpp`（`gd::RectF`） | -| `Components/Shared/Inc/UiWidget.hpp` / `Src/UiWidget.cpp` | 控件基类：树、Measure/Arrange、双栈裁剪 Paint、事件派发、失效、capture/模态/hover/焦点/光标、动画 tick | `UiLayout.hpp`、`PaintUtil.hpp` | -| `Components/Shared/Inc/UiHost.hpp` / `Src/UiHost.cpp` | 宿主：共享 DIB + `SurfaceView` + 脏区并集 + 回送 + 消息翻译 + 动画定时器 | `UiWidget.hpp` | -| `Tools/uicheck/`（入库） | 离屏回归网（`SW_HIDE` + 注入消息 + 从 `m_backDc` 取帧） | `Build/Release/*.o` | +* 新文件 `Components/Shared/Inc/UiBox.hpp` + `Src/UiBox.cpp`。 +* `struct UiBox { rect, clip, depth, layer }`：**纯值类型**，不继承任何东西。 +* `class UiBoxTable`：几何收集器，只维护"矩形 / 层级 / 绘制层 / 裁剪 / 遮挡"这些**几何事实**， + **不含任何绘制代码**。 +* `UiComponent::BuildBoxes(UiBoxTable&)`：组件上报自己的几何产物（默认只登记 `Area()`）。 +* `UiDebugBounds` 退化为**消费者**：`UiDebugPaintBoxList(g, table)` 把几何画成彩色包角线。 + ⇒ 组件不再需要知道"调试"这个概念存在。 -> ⚠️ `Components/Shared` 已在 `Makefile` 的 `CXX_INCLUDES_PATHS` / `CXX_SOURCES_PATHS` 中 ⇒ 新增 `.cpp` **无需改 Makefile**（按 basename 自动收集）。 +### L2 重绘范围控制（缓做 —— 见 §5） + +* 设计意图：`UiDamage`（最多 12 个矩形的脏区集合，超限退化为包围盒）替代 + "全窗重绘 / 绘图区重绘"的二值分支；`PlotView::Paint(g, UiDamage&)` 逐路径累加脏区。 +* 收益：去掉 `SetForceFullRepaint`（布局边界开关打开时的整幅重绘）。 + +### L3 体积与异常策略（本轮完成） + +见 `UI_Refactor_Progress.md` 的实测表。 --- -## 3. 布局层设计（`UiLayout`） +## 4. 阶段与验收标准 -### 3.1 为什么不是简单的"宽高字段" - -基类若只有 `width/height`，会在三处立刻失效： - -1. 所有坐标是**逻辑像素 × scale**（本机 DPR 1.25），控件必须知道缩放； -2. 面板宽度是**由内容反推**（`EdgePanelWidth` = 列宽 max + 行 ✕ + 滚动条预留）； -3. 离屏位图要求**设备像素整数对齐**（`floor`/`ceil` 方向错了就留 1px 接缝 —— 样式补丁曾踩过）。 - -⇒ 采用 **`Measure(约束) → 期望尺寸` / `Arrange(最终矩形) → 实际矩形`** 两段式。 - -### 3.2 需要的布局种类（按实际用量排序） - -| 布局 | 用途 | 备注 | +| 阶段 | 内容 | 验收 | | --- | --- | --- | -| **Abs（绝对）** | 绘图区叠加物主力：光标线、取值胶囊、吸附环、越界三角、固定点、面板初始位置、滚动条 | 保留"自由布局"，但它是**主力**而非备选 | -| **Anchor（四边贴合）** | 工具栏整体靠右、时间轴贴底、滚动条贴右、面板夹在 `m_plotRect` 内 | 讨论中缺失，必须补 | -| **Stack（竖向流）** | 信号列表行、分组行、面板条目（名称行 + 参数行 + 滑块行） | 需支持"行高由内容决定 + 吸顶(sticky) + 滚动视口" | -| **Flow（横向流 + 溢出）** | 图例条目 + 空间不足的 `+N`、工具栏按钮组 | 讨论中缺失，必须补 | -| **Measure-driven** | 面板宽度按实测文本撑开、列宽 `max(缺省, 内容, 列标题)` | 必须有，否则又回到"绘制侧省略号" | -| Grid | **用不上**（绘图区不是表格） | 不实现 | -| Card | 只是"面板皮肤" | 作为 `UiPanelSkin` 绘制样式，不是布局 | +| P1–P6 | 文件按职责拆分、`UiComponent` 协议、组件表、布局边界功能 | 编译 + `uicheck` | +| P7 | 布局边界"几何同源"（`RowRect` 前缀和、文本墨迹矩形、浮层层级/遮挡/裁剪） | `lbcovr` / `lbzorder` / `lbresid` / `lbpanel` | +| P8 | 体积：`-fno-exceptions` + `MemProbe` + `-ffunction-sections` + `--gc-sections` | 体积下降且 8 哈希不变 | +| P9 | 体积：LTO（含 `-flto-partition=one` 稳定性约束） | 同上，且可重复构建 | +| P10 | L1 几何产物层（`UiBox` / `UiBoxTable` / `BuildBoxes`） | 同上，且源码零残留旧名 | +| P11 | 代码审计（过时注释 / 名实不符 / 死代码） | 零 warning + 全量回归 | +| P12 | 文档重建 + 本地提交 | `git status` 干净 | -### 3.3 `UiLayoutCache`（本次最关键的性能点） +**统一验收命令** -`EdgePanelLayoutFor` 的 19 个调用点全部来自"同一份几何被反复问"。做法： +```powershell +make clean +make release TARGET_FILE_NAME=JustDataInspector -j16 # 期望零 error / 零 warning +make debug TARGET_FILE_NAME=JustDataInspectorD -j16 # 期望零 warning -```cpp -class UiLayoutCache -{ -public: - // key 由调用方提供（例如 laneIndex + kind + 面板宽 + 缩放 + 条目数） - const LayoutEntry* Find(std::uint64_t key) const; - const LayoutEntry& Store(std::uint64_t key, LayoutEntry&& entry); - void Invalidate(std::uint64_t key); // 定向失效 - void Clear(); -}; +objdump -h Build\Release\JustDataInspector.exe # 段构成，用于体积溯源 + +Tools\uicheck\uicheck.exe # 69/69 +.preflight\lbcheck\lbcheck.exe # 21/21 +.preflight\lbresid\lbresid.exe # 5/5 +.preflight\lbzorder\lbzorder.exe # 4/4 +.preflight\lbcovr\lbcovr.exe # 7/7 +.preflight\lbpanel\lbpanel.exe # 10/10 +Tools\rendercheck\rendercheck.exe # 8 哈希不变 + FUNC 7/7 ``` -**硬约束**：`Invalidate` 必须由"改变几何的那条路径"**显式**调用（与 `m_edgeScans` 的定向失效同一纪律），**禁止**为了让缓存命中率好看而整体 `Clear()`。 +--- + +## 5. 明确缓做的部分及理由 + +### L2 `UiDamage` + 独立叠加层（S4） + +**为什么缓做** + +1. 受益方只有"**调试开关打开时**的帧率"。`SetForceFullRepaint` 只在 + 「显示布局边界」开启时被置位（`Application::Render` 里 `m_plot.SetForceFullRepaint(m_showLayoutBounds)`）， + 普通用户路径上**本来就是快路径**。 +2. 正确实现无法只改 `PlotView` 内部：宿主用的是**持久后备缓冲区**， + 上一帧叠加层画上去的边框像素必须在下一帧被"底层内容重画"覆盖掉。 + 若改成"独立叠加位图 + 只混合脏区"，就必须把叠加层的旧矩形**注入**到底层组件的重绘范围里 —— + 这要穿透 `PlotView` 的全部四条快路径（静态场景贴图 / 宽基底贴图 / 样式补丁 / 网格层重建） + 与两层缓存。 +3. 风险与收益不成比例：用户已在 2026-10-28 反复报告过"拖拽错位 / 贴图残留"一类事故， + 而这类事故正是从"某条快路径漏了某块像素"开始的。 + +**保留了什么**：`SetForceFullRepaint` 及其四处守卫、`UiBoxTable` 的几何产物。 +将来若真要做，只需把 `UiBoxTable` 的 `rect` 直接喂给 `UiDamage`，不需要重新收集几何。 --- -## 4. 控件基类设计（`UiWidget`） +## 6. 交付物清单 -### 4.1 接口骨架 - -```cpp -struct UiEventResult -{ - bool consumed = false; // 事件已被消费（不再下传/上抛） - bool redraw = false; // 需要重绘 - gd::RectF dirty; // 需要重绘的矩形（客户区坐标；空 = 未知 ⇒ 取自身 bounds） -}; - -class UiWidget -{ -public: - virtual ~UiWidget(); - - // ---- 树 ---- - void AddChild(std::unique_ptr child); - void RemoveChild(UiWidget* child); - const std::vector>& Children() const; - - // ---- 布局（两段式，各自带失效）---- - void InvalidateMeasure(); // 向上冒泡到根 - void InvalidateArrange(); - gd::SizeF Measure(const UiMeasureContext& ctx); // 自下而上，命中缓存则直接返回 - void Arrange(const gd::RectF& bounds); // 自上而下；bounds 一定 > 0 - - // ---- 绘制（双栈裁剪 + 脏区下探）---- - void Paint(UiPaintContext& ctx); // 内部：与 dirty 求交 → OnPaint → 递归子节点 - virtual void Invalidate(const gd::RectF& rect); // 局部失效（向上冒泡并入） - - // ---- 事件 ---- - UiEventResult Dispatch(UiEvent& event); // 命中 → 子节点（反 z 序）→ OnEvent - - // ---- 命中 / 光标 ---- - bool Contains(int x, int y) const; - virtual HCURSOR QueryCursor(int x, int y) { return nullptr; } - - // ---- 交互仲裁（由 Host 调用）---- - UiWidget* Capture(); void SetCapture(); void ReleaseCapture(); - void SetModal(bool modal); // 模态子树：Host 只向它派发 - void SetHitTransparent(bool value); // 装饰元素：不参与命中 - - // ---- 动画 ---- - virtual bool AdvanceAnimation(std::int64_t nowMs) { return false; } - -protected: - virtual gd::SizeF OnMeasure(const UiMeasureContext& ctx) = 0; - virtual void OnArrange() {} - virtual void OnPaint(UiPaintContext& ctx) = 0; - virtual UiEventResult OnEvent(UiEvent& event) { return {}; } - virtual std::uint64_t ContentKey() const; // 缓存键的来源（父层只聚合） -}; ``` - -### 4.2 `Paint` 的硬契约（必须由基类保证，不是"每个控件记得"） - -1. **双栈裁剪**：进入时 `SaveDC + IntersectClipRect`（GDI）+ `Graphics::SetClip(Intersect)`（GDI+），退出时还原。这一条一次性消灭"滚动时文字串到标题栏""全选高亮溢出输入框""选区画到工具栏上"。 -2. **脏区下探**：`ctx.dirty = ctx.dirty ∩ bounds`；若为空 ⇒ **整棵子树直接 return**（不调 `OnPaint`、不遍历子节点）。 -3. **绘制顺序 = 子节点顺序 = z 序**；命中/事件 = **反 z 序**（与现在 `m_panelOrder` + `TopPanelAtPoint` 反向遍历等价，但不再靠人工维护）。 -4. **禁止**在 `OnPaint` 内改 `bounds`/子节点集合（会与本帧的 dirty 不一致）。 - -### 4.3 事件派发的硬契约 - -- **`consumed`** 决定是否上抛；**`dirty`** 参与本帧脏区并集。 -- **capture**：抓取期间所有鼠标事件**直接投给抓取者**（跳过命中），与 Windows `SetCapture` 语义一致。本项目硬约束：中键平移与左键拖拽**共用同一个 capture**，松左键**不能**无条件 `ReleaseCapture()`。 -- **模态**：菜单打开时 Host 只向模态子树派发，且"取消底层拖拽"时必须**排除菜单自己的 `EDIT_FIELD`**。 -- **hover**：Host 维护 hover 链，跨节点 `leave/enter`；悬停是**跨组件**的（面板行 → 网格固定点高亮；列表行 → 曲线光晕）⇒ 通过 Host 级"悬停信号总线"广播，不靠父子关系。 -- **双击消歧**：窗口带 `CS_DBLCLKS`；没有双击语义的位置必须在 `DoubleClickIsPlainPress()` 返回 true，由 Host 改走普通按下（否则"连点丢一半"）。 - -### 4.4 失效契约 - -- 节点持 `m_dirty`（自身坐标系）+ `m_dirtyChildren`； -- `Invalidate(rect)` 并入自身并**向上冒泡**（父层只并集矩形，**绝不**把子树的 dirty 清零）； -- Root 暴露 `TakeDirty()` 给 Host，Host 再与窗口更新区域取并集。 - ---- - -## 5. 宿主层设计（`UiHost`） - -1. **单一 app-sized 32bpp top-down DIB**（替换现在的 `CreateCompatibleBitmap`）： - ```cpp - struct SurfaceView - { - HDC dc; // 共享 HDC（GDI/GDI+ 都画这个） - gd::RectF rect; // 本节点在 Holder 坐标系中的矩形（设备像素，整数对齐） - int stride; // 行字节数（**不可**假设 = width*4） - std::uint32_t* bits; // rect 左上角那一像素（不是位图首地址） - std::uint64_t version; // 位图代次；失配 ⇒ 句柄作废 - }; - ``` - ⚠️ **绝不能缓存裸指针**：`EnsureBackBuffer` 在 `WM_SIZE` / `WM_DPICHANGED` 会重建位图。 - ⚠️ `bits` 只在 **CPU 侧直写**（memcpy/alpha）时用；GDI/GDI+ 绘制只需 `dc + rect`。 -2. **脏区并集**：把现在 56 处 `InvalidateRect` 收敛为 `Host::Invalidate(rect)`，一次回送。 - ⚠️ 回送仍必须**有无条件 `else`**（历史：某分支缺兜底 ⇒ 窗口一个像素都不回送，用户看到三个不同症状）。 -3. **动画 tick**：`AdvanceAnimation` 遍历树，任一为 true 就保持 `kScrollTimerId`（10ms）。 -4. **消息翻译**：`WM_*` → `UiEvent`，并把 `WM_SETCURSOR` 交给 `QueryCursor` 链（从 z 顶向下、首个非 null 生效）。 - ---- - -## 6. 落地阶段（每阶段一个可独立回滚的提交） - -| 阶段 | 内容 | 交付判据 | -| --- | --- | --- | -| **P0** | 离屏回归网 `Tools/uicheck`（入库）+ 现有 20+ 条硬约束的断言骨架 | ✅ **已完成**（69 项断言） | -| **P1** | `UiLayout` + `UiWidget` 基础层（本次） | ✅ **已完成**（编译零警告；`uicheck` 覆盖） | -| **P2** | 零行为变更分片：`PlotViewPaint.cpp` 拆成 `Paint`（只画）/ `Raster`（缓存与预算）/ `CacheKey`（指纹）/ `Geometry`（面板与命中）；`EdgePanelLayoutFor`、`ProbeFreeMarker` 迁回交互侧 | ✅ **已完成**（**逐像素 0 差异**） | -| **P3** | 迁移 chrome：Toolbar → TabBar → PopupMenu → ColorPicker → SignalPanel 行 | ✅ Toolbar/TabBar 已迁移；**PopupMenu/ColorPicker/SignalPanel 行经评估不采用**（见 Report §7 的结论与理由） | -| **P4** | 迁移 5 个浮动面板 | **经评估不采用**（面板布局已是单一函数且已缓存像素层；控件化无帧时间收益且会浮空吸顶/滚动语义，见 Report §7） | -| **P5** | 波形管线包成叶子 surface（**只包不改**）+ 共享 DIB 落地 | 🔄 **共享 DIB + `UiSurface` 已完成**；「56 处失效收敛为脏区并集」经评估**不采用**（`InvalidatePlotRect()` 已是按消息的批处理点，逐处替换只增间接层，详见 Report §7） | - -**P2 之前禁止改任何行为**。P2 是唯一的"免费"阶段，别顺手改语义。 - ---- - -## 7. 验证策略（不占用用户鼠标/键盘/屏幕） - -1. **离屏 harness**：`SW_HIDE` 窗口 + 直接 `app.HandleMessage(...)` 注入 + 从 `m_backDc` 用 `GetDIBits` 取帧。 -2. **进程/线程优先级 `BELOW_NORMAL`**；从不用 `SetCursorPos` / `SendInput` / 截屏。 -3. **A/B 反证**：每条新断言都要能被"还原旧实现"证伪，否则不算通过。 -4. **像素判据要选对区域**：验证"某交互不应改变外观"时，只对**不受影响**的区域取哈希。 -5. **已知陷阱**（全部来自历史 BUG）： - - 探针消息泵必须丢弃 `WM_MOUSELEAVE`（离屏窗口会立刻兑现它）； - - 注入按下后立即 `ReleaseCapture()`（避免抢真实鼠标）； - - `CycleCursorMode()` 是**循环**，多组用例里重复调用会把光标关掉； - - `PlotView` 的嵌套类型（`LaneVisual`/`LegendHit`/`EdgePanelLayout`）使用时要写 `PlotView::` 前缀。 - ---- - -## 8. 协作纪律（多 Agent） - -1. **文件所有权**：同一时刻**一个 Agent 只改一个文件的同一区域**；跨阶段并行时按下表分工，禁止交叉。 -2. **每阶段一个提交**，提交信息写清"改了什么 / 为什么 / 怎么验证"。 -3. **先写断言再改代码**。 -4. `main` / `dev` 只接受全绿；`UI_Refactor` 内允许临时红，但**不许跨轮次累积红**。 -5. 任何"规则变更"必须同步进 `Documents/agent_mem.md`（§11.2 追加编号），否则另一端看不到。 -6. 体积红线 **900KB**（到达即提醒用户，不是禁止超过）。 - -### 8.1 并行分工建议（若启用多个 Agent） - -| Agent | 独占文件 | 禁止触碰 | -| --- | --- | --- | -| A（基础层） | `UiLayout.*`、`UiWidget.*`、`UiHost.*`、`Tools/uicheck/*` | 任何现有组件 | -| B（分片） | `PlotViewPaint.cpp` → 新分片文件、`PlotViewInternal.hpp` 的 include 段 | `UiWidget.*`、面板逻辑 | -| C（面板迁移） | `PlotViewFeatures.cpp` 的面板段、新建 `PlotViewPanels.cpp` | `PlotViewPaint.cpp`、`UiLayout.*` | - -> 冲突高发点：`Makefile`（新增目录时才需要改）、`agent_mem.md`（追加编号必须串行）。 - ---- - -## 9. 风险与回滚 - -| 风险 | 触发条件 | 回滚 | -| --- | --- | --- | -| 迁移后"连点丢一半" | `DoubleClickIsPlainPress` 语义漏实现 | 单组件提交可独立 revert | -| 迁移后"拖动卡住" | capture 共用被拆成两套 | 同上 | -| 面板失效不全（贴旧像素） | `ContentKey()` 漏字段 | P4 里每个面板配一条"改 X 后像素必须变"的断言 | -| 体积超 900KB | 新框架代码量 | 每阶段结束量一次；超阈值先报告用户 | -| 布局级联死循环 | Measure 里改子节点 | 单元测试固定"Measure 一轮即收敛" | - ---- - -# 第五阶段计划：统一组件协议 + 去手写链路 + 拆分收尾（2026-10-28） - -> 状态：✅ 已完成（详见 `UI_Refactor_Progress.md` 第七轮 / `UI_Refactor_Report.md` 第五阶段） - -## 目标 - -1. 让"顶层组件"有统一协议，宿主不再逐个点名； -2. 用同一套协议把 `SetScale` / `Layout` / `MouseLeave` / `SetCursor` 四条手写链改成循环； -3. 把剩余两个"千行以上"的文件按**职责**拆分（不再按函数名前缀）； -4. 一轮代码审查（错误注释 / 过期注释 / 名实不符 / 残留引用）； -5. 把误入库的临时验证工具 `Tools/` 从提交树剥离并写入 ignore。 - -## 设计决定（先证明不是负优化） - -* **协议只做"同签名归一"**：`UiComponent` 是纯接口、无状态，四个组件本就各自拥有 - 完全同名同签名的方法 ⇒ 改造 = 加 `override` + 补 `Area()`，实现零改动、生成码几乎不变。 -* **不把 `UiComponent` 做成 `UiWidget` 的基类**：树节点是"父给尺寸 + 父下探脏区"， - 而 `PlotView`（4 层位图缓存）/ `SignalPanel`（行位图缓存）是"地盘宿主"。 - 强行上树会推翻缓存前提（历史事故：后台渲染覆盖平移、命中矩形错位）。 -* **不做的一律写明理由**：按下/松开/移动三条链带组件专属后置动作，保留显式分支。 - -## 任务清单 - -| # | 任务 | 验证手段 | -| --- | --- | --- | -| P5-1 | 新增 `Shared/Inc/UiComponent.hpp`，四组件继承 + `override` | 编译零警告 | -| P5-2 | `Application`：`ComponentEntry` 表 + `BuildComponentTable()` | — | -| P5-3 | `ApplyDpi` / `Relayout` / `WM_MOUSELEAVE` / `WM_SETCURSOR` 表驱动 | `uicheck` 69/69 | -| P5-4 | `Relayout` 内容区改用 `UiStackRects`（布局库首个生产调用点） | `rendercheck` 8 哈希不变 | -| P5-5 | `SignalPanelInteraction.cpp` 拆 4 片 + `SignalPanelEdit/Scroll/Menu.cpp` | 8 哈希不变 | -| P5-6 | `PopupMenu.cpp` 拆 3 片 + `PopupMenuInternal.hpp` | 8 哈希不变 | -| P5-7 | 代码审查（注释准确性、构造函数重复、include 位置） | 人工 + 编译 | -| P5-8 | `git rm -r --cached Tools` + `.gitignore` + 历史过滤器 | `git ls-files Tools` 为空 | -| P5-9 | 三份文档更新 + 提交 | `git status` 干净 | - -## 风险与对策 - -| 风险 | 对策 | -| --- | --- | -| 表驱动改动影响绘制顺序（toolbar 与 tabBar 重叠区） | 表按"底→顶"排，`WM_SETCURSOR` 从表尾向前命中，与旧 `if` 顺序一致 | -| 拆分导致逐像素差异 | 纯整函数搬移；每拆一个文件立刻跑 `rendercheck` 比对 8 哈希 | -| `filter-branch` 会清掉工作区被剔除的路径 | 先备份 `Tools/` 到 `%TEMP%`，重写后还原为未跟踪文件 | -| 中文注释在 PS 5.1 下乱码 | 文档编辑走 VS Code 编辑工具（UTF-8），终端只做 ASCII 拼接 | - -## 完成判据 - -* `make release` / `make debug` 零 error 零 warning； -* `Tools/rendercheck` 8 个场景哈希与基线**逐一相同** + 7 条 FUNC 断言 PASS； -* `Tools/uicheck` 69/69； -* `TargetCheck.exe` < 900 KB； -* `git ls-files Tools` 返回空、`git status` 干净、`main` / `dev` 未被触碰。 - ---- - -# 第六阶段（2026-10-28）：「显示布局边界」调试开关 + 三处可见收益优化 - -> 用户要求：先做可见收益的优化，然后在「导入文件」左侧加一个齿轮按钮，点击展开二级菜单， -> 菜单里放「显示布局边界」勾选项，风格参考 Android 调试功能；先落地，后续再改进。 - -## 1. 可见收益的优化（3 项，均为纯收益、行为不变） - -| # | 位置 | 改前 | 改后 | 收益 | -| --- | --- | --- | --- | --- | -| O1 | `Toolbar::Layout` | **每次**都 `RebuildWidgets()`（销毁 + 重建整棵树） | 新增 `m_treeDirty`，只在规格/字体/主题/缩放/动态文本变化时重建 | 拖动面板分隔条时 `Relayout` 每帧调用一次 ⇒ 每帧省 10 次堆分配 + 8 次测量缓存失效 | -| O2 | `Toolbar::SetActionLabel` | 同时写「覆盖表」和「控件文本」两处 | 只写覆盖表 + 置树脏 | 消除双写可能不同步（旧实现下次重建会把文本退回默认值） | -| O3 | `Toolbar` / `TabBar` 的 `OnMouseMove` | 各自手写 `Dispatch(); return UiRectHasArea(TakeDirty());` | 新增 `UiWidget::DispatchRedraw(event)` | 两处重复收敛成一处；`TakeDirty()` 会清零，漏掉一次就把下一次真实变化误判为"无变化" | - -## 2. 新功能：齿轮按钮 → 应用设置菜单 → 显示布局边界 - -### 2.1 入口 - -* `ToolbarAction::SETTINGS` + `kButtonSpecs[0]`（`UiButtonIcon::GEAR`）。 -* 工具栏布局从"首按钮靠左 + 其余靠右"改为**左侧固定簇**（`kLeftClusterCount = 2`：齿轮 + 导入文件）+ 右侧按钮组。 -* 齿轮是**矢量绘制**（`PaintGearIcon`：8 齿 + 外环 + 轴孔，全部按 `half` 的比例推导）， - 不用字体里的 `⚙` —— 该字符在不同回退字体里的大小与基线不一致，会"忽大忽小、垂直不居中"。 -* `UiButtonWidget` 新增 `UiButtonIcon`（`NONE`/`GEAR`）与 `SetIcon`；图标按钮宽度固定 40 逻辑像素。 -* `Application::OpenSettingsMenu()` 用 `Toolbar::ButtonRect(SETTINGS, …)` 取**控件实测矩形**做锚点 - （宿主不自己推算按钮几何），菜单在按钮下沿 +4 逻辑像素处右下展开。 - -### 2.2 菜单 - -`MenuScope::APP_SETTINGS`（新增）→ 宿主自己处理，不下发到组件。 -条目：`HEADER "调试"` + `NORMAL "显示布局边界"`（`keepOpen = true`，点击后菜单保持打开， -勾选态由 `PopupMenu::UpdateItemLabel` 回写）。 - -### 2.3 布局边界：为什么放在共同基类 - -`UiComponent` 新增 **`virtual void PaintDebugBounds(gd::Graphics&, float scale)`**，默认只画 `Area()`。 -四个组件各自覆盖：先调基类（自己的区域），再补画**层级更深的**矩形。 - -这正是上一轮回答里"是不是只需要在共同基类内实现"的答案： -**能覆盖顶层 4 块区域，覆盖不了组件内部的手绘结构**。所以采用"基类给出协议 + 组件自己上报"： - -| 组件 | 上报内容 | -| --- | --- | -| 全部 | `Area()`（层级 0） | -| `Toolbar` / `TabBar` | 跳过与区域重合的根控件，直接遍历 `m_root->Children()`（层级 1）；TabBar 另加每个 ✕（层级 2） | -| `SignalPanel` | 表头 / 筛选框 / 列表 / 样式区（1）＋ 滚动条、样式行、**当前可见**的列表行（2） | -| `PlotView` | 每个 `LaneVisual::rect`（1）；**不**上报曲线/胶囊/提示这类随数据变化的瞬态几何 | -| 宿主 | 客户区外框、分隔条、打开的菜单 / 拾色器（层级 0） | - -`UiWidget::PaintDebugBounds(g, scale, depth)` 递归整棵控件树 —— 凡已上树的控件**零成本**获得边界。 - -### 2.4 视觉与实现约束 - -* **只描边、不填充**（与 Android 一致）：填充会在几十个嵌套矩形上层层叠加把内容糊住。 -* 层级配色：0 青蓝 `#29B6F6`（2px）/ 1 品红 `#E040FB` / 2 琥珀 `#FFB300` / ≥3 绿 `#66BB6A`（1px）。 -* 线宽按**设备像素**固定（不乘 `scale`），并临时 `PixelOffsetModeNone` + 关抗锯齿 + 矩形对齐整像素， - 保证 1px 就是 1px。 -* 绘制位置：`Render` 的**最后一步**（加载遮罩之后）。⚠️ **绝不进入任何位图缓存** - （`PlotView` 4 层缓存、`SignalPanel` 行位图缓存）—— 否则关掉开关后线条会残留。 -* `fullFrame` 追加 `m_showLayoutBounds`：开启时必须整帧回送，否则"只回送绘图区"的快路径会让 - 装饰区的边界停在旧帧上。 - -## 3. 验证 - -| 项 | 结果 | -| --- | --- | -| `make release` / `make debug` | 零 error / 零 warning | -| **新增离屏探针 `.preflight/lbcheck`** | **21 / 21 PASS** | -| `Tools/rendercheck` 8 场景**工具栏以下区域**哈希 | 与改造前**逐一相同**（改动只落在工具栏带内） | -| `Tools/rendercheck` 7 条功能断言 | 7 / 7 PASS | -| `Tools/uicheck` | 69 / 69 | -| `TargetCheck.exe` | 897 024 B（< 900 KB） | - -新增断言覆盖：齿轮存在 / 在「导入文件」左侧 / 同高 / 更窄；开机后无调试色； -开启后青蓝 24 930 px、品红 19 734 px；**关闭后逐像素回到开启前**；菜单 scope、锚定贴合按钮、 -宽度未被撑大、条目初始未勾选、点击翻转开关、菜单保持打开。 - -## 4. 后续可改进（用户："先落地实现然后再进一步改进"） - -1. 边界左上角标短 tag（`row#12` / `lane3`）—— 需要处理 GDI 文本不受 GDI+ 裁剪约束的问题。 -2. `PlotView` 的浮动面板（`EdgePanelLayout` 里的 `panel/title/close/…`）目前未上报； - 它们已经是集中结构，插入一个循环即可。 -3. `SignalPanel` 的复选框 / 徽标 / ✕ 等行内子块（现在只到"行"这一层）。 -4. 开关状态目前**不持久化**（重启恢复为关闭）；若要持久化需要引入配置存储。 -5. 菜单只有一项；后续设置项按 `HEADER` 分组追加即可。 - ---- - -# 第七阶段计划（2026-10-28 第九轮）：边界观感重做 + 覆盖补全 + 几何同源 - -> 用户反馈：① 设置齿轮按钮的颜色应与「导入文件」一致； -> ② 边界绘制"就是实心矩形、粗细不一"，希望是**四角粗、其他边细**； -> ③ 按上一轮总结的覆盖率问题着手改进（很多元素没有边界）。 - -## 任务清单 - -| # | 任务 | 验证手段 | -| --- | --- | --- | -| P7-1 | 齿轮按钮改为主按钮（`primary = true`），与「导入文件」同色 | 探针断言两按钮底色一致 | -| P7-2 | 边界的描边改为**四角粗（3–4px）+ 四边细（1px）**的包角样式；只描边不填充 | 逐像素探针 + 人工核对 | -| P7-3 | 层级 > 0 的 box 内缩 1px，避免与父矩形共边时叠成粗线 | 同上 | -| P7-4 | 协议从「组件自己画」改为「组件**收集 box**、宿主统一画」（`CollectDebugBoxes`） | 编译 + 探针 | -| P7-5 | `SignalPanel`：行内元素全部上报（复选框/色块/名称/GX 徽标/✕/折起三角/组名/计数）+ 筛选框/清空✕/滚动条/滑块/样式区 5 行与行内控件/目标行/编辑框 | 探针断言 box 数量 | -| P7-6 | `PlotView`：GX 徽标、装饰层矩形、图例条目（托底/色块/文本）、5 类浮动面板全部字段 | 同上 | -| P7-7 | `Toolbar`：按钮内部**文本/图标**矩形（新增 `UiButtonWidget::ContentRect()`） | 同上 | -| P7-8 | `PopupMenu` / `ColorPickerPopup`：条目、滚动区/轨道/滑块、子菜单；拾色器各控件 | 同上 | -| P7-9 | `RowRect` 从 **O(row) → O(1)**（行顶前缀和 `m_rowTop`） | 行为不变（像素哈希） | -| P7-10 | `PanelBounds()` 收敛 6 处重复三元表达式 | 编译 | -| P7-11 | 三份文档 + `agent_mem.md` 同步；`TargetCheck.exe` < 900 KiB | 构建 | - -## 风险与对策 - -| 风险 | 对策 | -| --- | --- | -| 前缀和与行集合短暂不一致 | `RowRect` / `ContentOffsetBeforeRow` 检测长度后**退回逐行累加**（正确性优先） | -| box 数量暴涨导致调试帧变慢 | 只在开关打开时执行；标签设**尺寸门槛**（< 56×16 逻辑像素不画标签） | -| 调试层污染位图缓存 | 仍只在 `Render` 最后一步叠加，探针 `bounds-off-restores-pixels` 钉住 | -| 浮层 box 需要读取私有几何 | 给两个浮层加 `CollectDebugBoxes`，几何仍由它们自己给出（不外泄成员） | - -## 完成判据 - -* `make release` / `make debug` 零 error 零 warning； -* 「工具栏带以下」区域哈希与上一轮**逐一相同**（证明改动只落在工具栏带内）； -* `lbcheck` 21/21、`rendercheck` FUNC 7/7、`uicheck` 69/69； -* 打开开关后：每行的复选框/色块/名称/GX 徽标/✕、每个网格的 GX 徽标与图例、每个浮层控件都有独立包角框。 - ---- - -# 第八阶段计划（2026-10-28 第十轮）：边界观感自适应 + 残留与层级缺陷修复 - -> 用户反馈：① 包角对小元素来说太粗（小方框直接变成粗描边）；② 不需要黑色底衬的文字标签； -> ③ 加载 MF4-Record.MF4 全部信号独立网格后，按住左键拖动网格滚动条快速滚动会出现大量 -> 绘制残留（工具栏与网格区域都有），松开并移动鼠标才消失；④ 右键二级菜单上被下层元素的 -> 边界线覆盖，干扰观察菜单布局。 - -## 任务清单 - -| # | 任务 | 验证手段 | -| --- | --- | --- | -| P8-1 | 包角粗细／长度按矩形短边自适应；小方框只画角不画边；过小则不画 | 截图放大 3 倍核对 | -| P8-2 | 删除文字标签（连同 `UiDebugPaintStyle`），降低体积与视觉噪声 | 编译 + 体积 | -| P8-3 | 定位并修复「拖网格滚动条时的绘制残留」 | 新增离屏探针 `.preflight/lbresid` | -| P8-4 | 修复 `PlotView` 误用 `m_decorRects`（位图坐标系）产生的跨工具栏幽灵框 | 同上（box 清单打印） | -| P8-5 | 调试叠加层开启时强制绘图区整幅重绘（禁用三条快路径） | 同上（同状态两帧必须逐像素相同） | -| P8-6 | box 增加 `clip`（组件地盘），组件内越界元素不再画到邻居上 | 同上（差异 bbox 不得越过绘图区上沿） | -| P8-7 | 层级：`(layer, depth)` 双排序键 + 浮层 `occluder` 挖洞 | 新增探针 `.preflight/lbzorder`（4 条断言） | -| P8-8 | 文档与共享记忆同步；`TargetCheck.exe` < 900 KiB | 构建 | - -## 风险与对策 - -| 风险 | 对策 | -| --- | --- | -| 强制整幅重绘让调试模式变慢 | 只在开关打开时生效；关闭立即恢复快路径 | -| `Region::Exclude` 影响其他绘制 | 只在 `Save/Restore` 内临时 `SetClip`，且仅在存在遮挡时才走该分支 | -| 裁剪把紧贴边界的包角裁掉 | 裁剪用 `floor/ceil` 向外取整（宁可多一像素） | -| 移除标签后难以辨认 box 归属 | 层级配色（青蓝/品红/琥珀/绿）+ 包角形状 | - -## 完成判据 - -* 零 warning；`lbresid` 5/5、`lbzorder` 4/4、`lbcheck` 21/21、`uicheck` 69/69； -* `rendercheck` 的「工具栏带以下」区域哈希与上一轮**逐一相同**、FUNC 7/7； -* 拖动滚动条期间工具栏区域像素**完全不变**，且同状态两帧**逐像素相同**； -* 菜单/二级子菜单区域内不出现下层组件的边界色。 - ---- - -# 第九阶段计划（2026-10-28 第十一轮）：把"边界"这件事从补丁改成机制 - -> 背景：第十轮结论是"三个性质不同的问题"——① `inset` 破坏 '框 = 可见形状外接矩形'； -> ② 元素清单不完整（几何没有枚举出口）；③ 描边图元太多。本轮把三者一起解决。 - -## 任务清单 - -| # | 任务 | 验证手段 | -| --- | --- | --- | -| P9-1 | **取消内缩**：框必须与可见形状外接矩形重合（修 GX 胶囊圆弧落在框外） | 探针断言 box 与 `LaneBadgeRect` 重合（容差 0.5px） | -| P9-2 | **文本获得几何身份**：`PaintUtil` 增加 `UiTextRectSink`，在绘制的**唯一出口**回报墨迹矩形 | 覆盖 60+ 调用点，无需逐处修改 | -| P9-3 | 离屏位图（面板行缓存）中的文本按**位图原点**回放，缓存命中也能显示文本框 | 探针 `row-text-boxes-from-cached-rows` | -| P9-4 | 补齐 `PlotView` 漏项：时间轴 / 网格滚动条 / 回到最上方 / 光标标签 / 差值标签 / 内联输入框 | 探针 4 条 box 断言 | -| P9-5 | 描边图元 12 → 8（4 边 + 4 角块），耗时 5.9ms → 4.0ms | 微基准 + 帧耗时分解 | -| P9-6 | 关闭开关时清空容器（释放内存，避免误读） | 探针 `boxes-cleared-when-off` | -| P9-7 | 文档 + 共享记忆；`TargetCheck.exe` < 900 KiB | 构建 | - -## 关键设计决定 - -* **文本不做"逐处登记"**：全仓 65 处文本绘制点手写登记必漏。改为在 `UiText`/ - `UiTextClipped`/`UiTextAtClipped` 的公共出口 `ReportTextRect()` 里回报一次， - 代价是开关关闭时一次判空。 -* **缓存命中也要有文本框**：行位图渲染时用一个本地收集器把矩形存进 `RowBitmapCache`， - 贴图时按原点偏移回放；否则第二帧起文本框全部消失。 -* **不内缩**：重叠时"后画的覆盖"就是正确语义，内缩是错误取舍。 - -## 完成判据 - -* 零 warning；四个探针全绿（21 + 5 + 4 + 7）、`uicheck` 69/69； -* `rendercheck` 8 个场景的整帧与区域哈希与上一轮**逐一相同**（调试功能不能影响正常绘制）； -* 打开开关后：文本有橙色墨迹框、GX 胶囊被框住、时间轴/滚动条/回到最上方均有框。 - ---- - -# 第十阶段计划（2026-10-29 第十二轮）：同步远端 + 既有性能问题 + 浮层层级修复 - -> 用户报告（附截图）：① 远端 gitea 已把 `UI_Refactor` 合入 `main`（分支保留），需 fetch 并同步各分支， -> `dev` 为意外产物，本地删除；② 排查"顺带发现的既有性能问题"并解决；③ 浮动面板被网格边界穿透； -> ④ 滚动网格滚动条时浮动面板上的边界闪烁；⑤ 信号面板 GX 徽标的「所属网格」二级菜单边界溢出菜单、 -> 滚动后条目仍像在绘制。 - -## 任务清单 - -| # | 任务 | 验证手段 | -| --- | --- | --- | -| P10-1 | `git fetch` 同步；`main` 快进到 `gitea/main`；本地删除 `dev`；`UI_Refactor` 快进到合并提交 | `git branch -vv` | -| P10-2 | 定位"空闲帧比强制整帧更慢"的真因 | 离屏计时探针 | -| P10-3 | 修复：离屏网格不再逐帧算内容指纹/入队 | 排空后稳态与排空过程分别计时 | -| P10-4 | 浮动面板另起绘制层 + 登记遮挡矩形 + 内容裁剪到面板 | 新增探针 `.preflight/lbpanel` | -| P10-5 | 弹出菜单条目裁到可视区（滚动条目不再登记盒子） | 同上（10 条断言） | -| P10-6 | `EdgePanelLayoutFor` 只在"该网格有面板展开"时才调用 | 收集耗时对比 | -| P10-7 | 文档 + 共享记忆；零警告；< 900 KiB | 构建 | - -## 关键结论（P10-2） - -用两级计时探针（先整体、再拆到 `WarmLaneLayersStep` 内部）测得： - -* "空闲帧 2.4ms" **不是稳态**，而是**图层预热队列排空**的瞬时开销 - （16 个网格 × 每帧补 1 个 ≈ 1~3ms/帧，约 16 帧后结束）； -* 排空后稳态为 **0.53ms**，与"强制整帧"的 0.46ms 基本相同 —— 所以**不存在**每帧白烧的固定开销； -* 但 `RollWideBuffer` 里"先算每网格内容指纹、再判断是否可视"的顺序确实有问题： - 283 个网格每帧全算一遍 `LaneLayerKey()`（约 0.7ms），并会把离屏网格塞进待重画队列。 - **把可视性判断提到最前面**后，离屏网格既不哈希也不入队。 - -## 完成判据 - -* 零 warning；`lbpanel` 10/10 + 既有四个探针全绿；`uicheck` 69/69； -* `rendercheck` 8 场景哈希与上一轮**逐一相同**（本轮不应改变任何正常绘制像素）； -* 面板区域内不出现网格层颜色；菜单/面板的盒子不得完全落在自身矩形之外。 +Components/Shared/Inc/UiBox.hpp 新增（几何产物层） +Components/Shared/Src/UiBox.cpp 新增 +Components/Shared/Inc/UiDebugBounds.hpp 精简为"只画"（消费者） +Components/Shared/Src/UiDebugBounds.cpp 精简为"只画" +Components/Shared/Inc/UiComponent.hpp CollectDebugBoxes → BuildBoxes +Utilities/Inc/MemProbe.hpp 新增（分配预检验 + terminate 兜底） +Utilities/Src/MemProbe.cpp 新增 +Makefile LAYOUT_BOUNDS / NO_EXCEPTIONS / LTO 三个开关 +Documents/UI_Refactor_{Plan,Progress,Report}.md 重建 +``` diff --git a/Documents/UI_Refactor_Progress.md b/Documents/UI_Refactor_Progress.md index df63a9c..f34e4b2 100644 --- a/Documents/UI_Refactor_Progress.md +++ b/Documents/UI_Refactor_Progress.md @@ -1,765 +1,202 @@ -# UI 重构进度（UI_Refactor 分支） +# Just DataInspector UI 重构 —— 当前进度 -> 本文件是**跨会话/跨 Agent 的交接台账**。每次提交前更新；每一行都要能对应到一个可复跑的验证结果。 -> 计划见 `Documents/UI_Refactor_Plan.md`；硬约束见 `Documents/agent_mem.md` §11.2。 +> 计划见 `UI_Refactor_Plan.md`，结论与遗留见 `UI_Refactor_Report.md`。 +> 最后更新：2026-10-29（本轮：体积 L3 落地 + L1 几何产物层 + 审计） -## 分支状态 +--- -| 分支 | 基线 | 用途 | +## 1. 总览 + +| 层 | 内容 | 状态 | | --- | --- | --- | -| `main` | `df715a0` | 可发布，**不受本次重构影响** | -| `dev` | `4e51b41` | 日常开发基线；本分支上已 **删除过时报告** `Documents/refactor_report_2026-10-16.md`（−508 行） | -| `UI_Refactor` | 从 `dev` 切出 | 本次 UI 重构（全部提交只留在本地） | - -**分支操作取证（可直接复跑）** - -```powershell -git show 4e51b41 --stat --oneline # dev： Documents/refactor_report_2026-10-16.md | 508 ---------- -Test-Path Documents\refactor_report_2026-10-16.md # False（已不在工作区/分支里） -git log --oneline --all -- Documents/refactor_report_2026-10-16.md # 末条即为 4e51b41 的删除提交 -git log --oneline main -1 # df715a0（main 未被任何重构提交触碰） -``` - -## 阶段看板 - -> **本计划已全部结案**：可达成项已落地（P0/P1/P2/P3-Toolbar+TabBar/P5-共享表面）， -> 其余项经评估**不采用**并写明理由（见 `UI_Refactor_Report.md` §7）—— 计划里没有悬空阶段。 - -| 阶段 | 内容 | 结论 | -| --- | --- | --- | -| **P0** | 离屏回归网 `Tools/uicheck` | ✅ 已落地（69 项断言） | -| **P1** | `UiLayout` + `UiWidget` 基础层 | ✅ 已落地 | -| **P2** | `PlotViewPaint.cpp` 零行为分片 | ✅ 已落地（9 080→4 913，逐像素 0 差异） | -| **P3** | chrome 迁移 | ✅ Toolbar / TabBar 已迁移；PopupMenu / ColorPicker / SignalPanel 行**经评估不采用** | -| **P4** | 5 个浮动面板控件化 | **经评估不采用**（理由见 Report §7） | -| **P5** | 共享表面 `UiSurface` + top-down DIB | ✅ 已落地；脏区并集**经评估不采用** | +| L0 | `UiComponent` 协议 + 有序组件表 + `UiWidget` 控件树 | ✅ 已完成（前几轮） | +| L1 | `UiBox` / `UiBoxTable` / `UiComponent::BuildBoxes` | ✅ **本轮完成** | +| L2 | `UiDamage` 脏矩形 + S4 独立叠加层 | ⏸ **评估后缓做**（理由见 Plan §5） | +| L3 | `-fno-exceptions` + `MemProbe` + `-ffunction-sections` + `--gc-sections` + LTO | ✅ **本轮完成** | --- -## 提交记录 +## 2. L3 体积与异常策略 -### 1. `P0 + P1`：UI 基础层与离屏回归网 -**新增文件** +### 2.1 Makefile 开关 -| 文件 | 行数 | 职责 | -| --- | --- | --- | -| `Components/Shared/Inc/UiLayout.hpp` | ~250 | 布局原语 + `UiLayoutCache` | -| `Components/Shared/Src/UiLayout.cpp` | ~300 | 矩形原语 / 对齐 / Stack / Flow / 缓存 | -| `Components/Shared/Inc/UiWidget.hpp` | ~330 | 控件基类接口与设计说明 | -| `Components/Shared/Src/UiWidget.cpp` | ~560 | 树 / Measure·Arrange / Paint（脏区+裁剪）/ 派发 / 仲裁 / 动画 | -| `Tools/uicheck/main.cpp` | ~570 | 离屏回归网（62 项断言） | -| `Tools/uicheck/build.ps1` | ~70 | 链接 `Build//*.o`（排除 `Main.o`） | - -**已实现并验证的行为** - -- 布局：`UiAlignInRect`（含 `STRETCH`、超尺寸夹取、偏移后置）、`UiRectSnapInward`（设备像素内侧对齐）、 - `UiStackRects`（固定 / `kUiSizeAuto` 均分 / **绝不产生负尺寸**）、`UiFlowRects`（换行 + `overflow` 下标）。 -- 缓存：`UiLayoutCache` 用 `std::deque` 保证**引用稳定**；容量淘汰按"最久未命中"；`Invalidate` 为**定向**失效。 -- 布局 pass：`Measure` 命中缓存不重复调用 `OnMeasure`；`InvalidateMeasure` **只**沿祖先链失效（兄弟不重算）。 -- 绘制：`dirty` 为空 = 全画；与子树矩形无交集 ⇒ **整棵子树跳过**；有效裁剪 = 祖先裁剪切 ∩ 自身矩形 ∩ 脏区； - 不可见节点跳过。 -- 派发：**只沿命中链**（最深的命中节点 → 祖先冒泡），**绝不分发给同层兄弟**；`capture` 期间事件直投捕获者； - `modal` 只向模态子树派发；`hit-transparent` 让事件穿透；`QUERY_CURSOR` 由最上层认领者返回； - 键盘/字符沿**焦点链**派发（无焦点交给根，保证宿主级快捷键可用）。 -- 动画：`AdvanceAnimation` 逐节点下发同一时间戳并汇总"是否仍有动画"。 -- 悬停：进入 / 离开各只触发一次，跨子节点迁移时正确配对。 - -**过程中修掉的两个自身缺陷** - -1. `UiWidget` 缺 `AdvanceAnimationSelf` / `AnimationActiveSelf` 两个 protected 虚函数（`.cpp` 已引用、头文件漏声明）。 -2. 最初的派发实现是"遍历同层兄弟、未消费就继续" ⇒ **一个点击可能同时被视觉上位于下方的控件处理**； - 已改为"只沿命中链派发 + 祖先兜底"。回归网里对应的断言从"绝对次数"改为**增量断言** - （绝对次数会被前面用例计数污染，本轮踩过一次）。 - -**验证** - -``` -make release TARGET_FILE_NAME=TargetCheck # 零警告 -powershell -File Tools/uicheck/build.ps1 # 链接 Build/Release/*.o（排除 Main.o） -Tools/uicheck/uicheck.exe # 62 passed, 0 failed -``` - -**未做（有意）** - -- 未改动任何现有组件（Toolbar / TabBar / SignalPanel / PlotView 仍走旧路径），因此**本提交对产品像素零影响**。 -- 未把 `UiWidget` 接入 `Application`，避免在 P2 之前引入行为差异。 - ---- - -### 2. `P2`：`PlotViewPaint.cpp` 按关注点分片（零行为变更） - -**为什么**：该文件 9 080 行里混住四类内容 —— 真绘制 ≈3.5k / 光栅化缓存 ≈2.5k / 缓存键 ≈1.1k / -布局与命中几何 ≈1.3k。按"函数名前缀"分片是上一轮膨胀的直接原因，本轮按**关注点**再分一次。 - -**做法**：**机械搬移成员函数定义**（不改一行逻辑）。`PlotViewInternal.hpp` 里的 `pvdetail` 全部 `inline` -⇒ 跨分片安全，无需改任何 include、无需改 `Makefile`（按 basename 自动收集 `.cpp`）。 - -| 文件 | 搬入内容 | 行数变化 | -| --- | --- | --- | -| `PlotViewRaster.cpp`（新） | 光晕离屏层（`PaintSignalHalo*` / `UploadHaloLayer` / `ReleaseHaloLayer`）
场景缓存（`Ensure/Capture/Blit/Invalidate/ReleaseSceneCache`）
装饰层（`Ensure/Release/Render/BlitDecorCache` / `ResolveAlphaBlend`）
宽基底图层与预算（`EnsureLaneLayer` … `BlitWideBuffer`、并行重建、滚动补条、预热） | 1 876 | -| `PlotViewCacheKey.cpp`（新） | `MakeSceneCacheKey` / `SceneCacheMatches` / `SceneHaloRef`
`SceneContentHash` / `SceneGeometryHash` / `SceneDecorHash`
`CollectSceneStyles` / `FindStyleOnlyLanes` / `CollectSceneDerived` / `RepaintSceneCachePatch` | 474 | -| `PlotViewPaint.cpp` | 只剩绘制（`Paint*` / `Render*` / 输入框绘制） | 9 080 → **6 252**（−31%） | - -**验证（关键）** - -1. `make release TARGET_FILE_NAME=TargetCheck` **零警告**；`Target.exe` 873 984 → **875 008 B**（+1 KB， - 属分片后各 TU 的对齐差异；仍远低于 900 KB 阈值）。 -2. **逐像素 A/B**：临时写了一个渲染哈希探针（仓库外），对三个场景渲染后备缓冲区并取 FNV 哈希： - * A 默认全览；B 深放大 + 自由标记（含固定点）+ 均值滤波 + 弱峰调整 + 时间光标；C 再平移一帧（触发宽基底滚动/补条）。 - * **分片前**：`A 2166933039626F66 / B C444ECFEB18FD73D / C 7984446D8E7A4418` - * **分片后**：**完全相同**（三个场景逐一一致）。 - * 该探针未入库（一次性验证用），结论记录在此以便复现。 -3. `Tools/uicheck` 62/62 全绿。 -4. 顶层注释从"四个分片"更新为"六个分片（按关注点）"，并写明"`Paint/PaintLane` 仍只允许定义在 `PlotViewPaint.cpp`"。 - -**⚠️ 复现 A/B 的坑**：机械搬移后用旧的 `.bak` 回退时，`Build//` 里会残留 -`PlotViewRaster.o` / `PlotViewCacheKey.o`，链接探针（`Build/Release/*.o`）会因重复符号失败 —— -**必须先删掉这两个陈旧 `.o`** 再链接。 - ---- - -### 3. `P2 续`：把"布局与命中几何"从绘制分片里拆出（`PlotViewPanels.cpp`） - -**为什么**：`EdgePanelLayoutFor`（651 行，19 个调用点）、`EdgePanelWidth`、`LaneBadgeRect`、 -`FreeMarkerValue/Delta/Contents/LabelRects`、`ProbeFreeMarker` 都是**几何**，却被塞在绘制分片里 —— -改一次布局要动 9 千行的绘制文件，回归面被放大。 - -**做法**：同样机械搬移（5 个不连续块），`PlotViewPaint.cpp` 从 6 645 → **4 913** 行。 - -**最终七个分片**（按关注点） - -| 文件 | 行数 | 职责 | -| --- | --- | --- | -| `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 | 内容指纹与缓存键 | - -**累计效果**：`PlotViewPaint.cpp` **9 080 → 4 913（−46%）**，最大文件从 9.1k 降到 4.9k。 - -**验证** - -1. `make release TARGET_FILE_NAME=TargetCheck` 零警告；`Target.exe` **877 568 B**（< 900 KB）。 -2. **逐像素 A/B**：同三场景哈希与迁移前**完全一致** - （`A 2166933039626F66 / B C444ECFEB18FD73D / C 7984446D8E7A4418`）。 -3. `Tools/uicheck` 62/62。 -4. 顶层注释更新为"七个分片（按关注点）"，并标明 `Paint/PaintLane` 只允许定义在 `PlotViewPaint.cpp`。 - ---- - -### 4. `P3`：Toolbar 迁移到控件树（**逐像素 0 差异**） - -**新增**：`Components/Shared/{Inc,Src}/UiButtonWidget.*` —— 通用"文字按钮"控件，视觉规则与旧 Toolbar -按钮逐像素一致（主按钮强调色实底 / 普通按钮 1px 描边 / 可切换选中态 / 禁用态配色）； -交互由自己处理：按下即 `CaptureMouse()` 进入按下态，**在自身范围内**松开才触发 `onClick`， -指针离开时 `CancelPress()`。 - -**`Toolbar` 内部重写（公开 API 一字未改）**： - -| 旧实现 | 新实现 | -| --- | --- | -| `std::vector