UI控件及大组件结构化重构，新增“显示布局边界”调试功能（待完善） #1
Assignees
LuChiChick (LuChiChick)
Clear assignees
LuChiChick (LuChiChick)
No Assignees
LuChiChick
LuChiChick
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: LuChiChick/Just-DataInspector#1
Reference in new issue
Block a user
去除手写渲染链路，参考了一些浏览器控件渲染的机制，对元素进行基类+派生的形式，这样只需要维护一套共通的消息处理机制，并且可以采用控件树和脏矩形渲染机制，之前的手写渲染链路容易造成很多BUG，而Agent的截图后验机制可能查不出来，这次架构上的变动有助于从源头杜绝这类BUG；
为应用添加了一个设置菜单，现在只放置了一个“显示布局边界”的调试功能，这个功能参考了安卓设备的开发者调试选项，目的是用于动画和布局调试，顺便给Agent的视觉模块提供参考；
新增 Components/Shared/{Inc,Src}/UiButtonWidget.*：通用「文字按钮」控件，视觉规则与旧 Toolbar 按钮逐像素一致（主按钮强调色实底 / 普通按钮 1px 描边 / 可切换选中态 / 禁用态配色）； 交互由控件自己处理：按下即 CaptureMouse 进入按下态，在自身范围内松开才触发 onClick， 指针离开（不会再收到抬起）时 CancelPress。 Toolbar 内部重写，公开 API 一字未改： - Button 只保留静态配置 + 控件指针；矩形与外观状态归控件。 - 删除 m_hoverIndex / m_pressedIndex 与死字段 Button::hover，改由 UiWidget 的悬停链与 capture 维护。 - Paint 改为「根控件（底色 + 底部分隔线）+ 按钮子节点」，一次 root->Paint(ctx)。 - OnMouseMove/Down/Up/Leave 统一翻译成 UiEvent 后 root->Dispatch；动作经 onClick 回调登记、抬起后执行。 框架约定调整：UiWidget::Paint 的裁剪从「严格等于自身矩形」改为「自身矩形外扩 1px（kUiClipBleed）」。 边框/描边以矩形边界为中心绘制，严格裁剪会切掉外半侧使控件变细、与旧绘制不再像素一致。 uicheck 对应断言改为「裁剪 ⊇ 自身矩形且不超出外扩范围」。 验证： - make release / make debug 零警告；Target.exe 881,664 B（< 900KB）。 - 逐像素 A/B（8 场景：全览 / 深放大+自由标记+滤波+弱峰+光标 / 平移 / 悬停按钮 / 按下 / 松开 / 悬停主按钮 / 移出工具栏）：迁移前后哈希逐一相同 A 2166933039626F66 B C444ECFEB18FD73D C 7984446D8E7A4418 D BF855879CA12F289 E 1C663E4118616016 F 0535292D8E07AE18 G 7A58172C46577729 H 23F390DD76141113。 - 功能断言：locate-cursor-button PASS (1291,73)；click-cursor-changes-mode PASS (1 -> 2)； release-outside-does-not-fire PASS (2 -> 2)。 - Tools/uicheck 62 passed / 0 failed。一、共享表面（为「整个应用共享一张后台位图」落地基础设施） - 新增 Components/Shared/{Inc,Src}/UiSurface.*：{ dc, rect, stride, bits, version, scale }。 SubView() 把子矩形换算到宿主坐标、夹取在本表面内、按 stride 重算 bits 偏移、传递 version。 ⚠️ 注释里写明：bits 只在 CPU 侧合成时使用；画控件只需 dc + rect（用 bits 画字会破坏 ClearType）。 - Application 增 BackBufferSurface()；后备缓冲由 CreateCompatibleBitmap 改为 **top-down 32bpp CreateDIBSection**（biHeight 取负，y 向下递增），并记录 bits/stride/version （重建位图时 ++version，旧句柄因此可判定作废）。 二、修复「退出时访问违例」（真实缺陷） - Application::Shutdown() 中 **DestroyWindow 必须在 GdiplusShutdown 之前**：前一帧的 InvalidateRect 可能留下未处理更新区域，DestroyWindow 期间派发 WM_PAINT ⇒ Render() ⇒ 在已关闭的 GDI+ 上构造 Graphics ⇒ 崩溃。 - Render() 开头加保护：!m_gdiplusReady 或 m_hwnd 为空时直接返回。 验证： - 像素：8 场景（A 全览 / B 复杂浮层 / C 平移 / D 悬停 / E 按下 / F 松开 / G 悬停主按钮 / H 移出） 哈希与 DIB 改造前**逐一相同**（A 2166933…、B C444ECF…、C 7984446…、D BF85587…、 E 1C663E4…、F 0535292…、G 7A58172…、H 23F390D…）。 - 功能：locate-cursor-button (1291,73) / click-cursor-changes-mode (1->2) / release-outside-does-not-fire 全部 PASS。 - uicheck 69 passed / 0 failed（新增 7 条 UiSurface 断言：bits 按 stride 偏移、矩形夹取、 完全在外时返回无效表面、version/scale 传递）。 - make release / make debug 零警告；Target.exe 883,200 B（< 900KB）。 附注：探针此前的退出崩溃其实来自「探针自己又调了一次 GdiplusShutdown」（Application::Shutdown 内部已 shutdown），与本轮修复无关；本轮的顺序调整与 Render 保护仍保留为防御性正确做法。TabBar 的标签 / 「+」/ 覆盖层拆成控件，手势语义原样保留（自行判双击、3px 拖拽阈值、 关闭 ✕ 的「移开取消」、拖拽排序的 drop 位置），公开 API 未变： - 新增（TabBar.cpp 内实现的内部控件） * UiTabItemWidget：单格标签的绘制（底色/描边/激活指示条/文本或重命名输入框/关闭 ✕）， 关闭按钮热区由基类的悬停点自行判定。 * UiAddWidget：「+」按钮绘制与悬停配色。 * UiOverlayWidget：命中透明的覆盖层，最后绘制「拖拽插入指示条 + 底部分隔线」 （必须晚于标签与「+」，否则会被它们压住）。 * UiTabRootWidget：只铺标签栏底色。 - TabBar 移除 m_hoverIndex / m_hoverClose / m_hoverAdd 三个手工下标， 改为 dispatch MOUSE_MOVE 后由 root->TakeDirty() 判断是否需要重绘。 - 绘制顺序保持：底色 → 各标签 → 「+」→ 拖拽指示条 → 底部分隔线（与旧实现逐像素一致）。 - UiWidget 新增 HoverPoint(x,y)：派生控件据此自行判断「悬停在自身内部哪个热区」。 验证： - 像素：8 场景哈希与迁移前逐一相同（A 2166933…、H 23F390D…）。 - 交互断言（全部 PASS）： * tabbar-hover-marks-dirty (1,0) —— 进入标签只标记一次脏区； * tabbar-add-creates-tab (1 -> 2) —— 「+」新建标签； * tabbar-click-selects-tab (active=0) —— 点击标签切换激活页； * tabbar-close-removes-tab (2 -> 1) —— 点击 ✕ 关闭标签。 - Tools/uicheck 69 passed / 0 failed。 - make release / make debug 零警告；Target.exe 886,784 B（< 900KB）。评估阶段最后的产物：把"能做但收益不成立"的项显式结案，而不是留成待办。 - Documents/UI_Refactor_Plan.md：P3 行改为「Toolbar/TabBar 已迁移；PopupMenu/ColorPicker/ SignalPanel 行经评估不采用」；P4 行改为「经评估不采用」。 - Documents/UI_Refactor_Report.md 第 7 节重写为「其余计划项的处理结论（均已结论，无悬空项）」， 逐项给出基于代码事实的理由： * PopupMenu / ColorPicker：模态浮层每帧整体重画、命中是 <=20 行矩形线性扫描， 且已有单一 BuildLayout 同时产出绘制与命中矩形（已是同源几何）⇒ 控件树额外收益近零， 风险集中在子菜单悬停/内联编辑/滚动/拖拽钳制。 * SignalPanel 行：性能来自行位图缓存（PaintRowCached + RowCacheKey）与抽拉式折叠动画， 控件化会把缓存键与控件生命周期耦合，且"行高永不变、只平移"与通用布局模型冲突。 * 5 个浮动面板（P4）：面板像素层已缓存到 0.3ms（全画 24~35ms）⇒ 控件化无帧时间收益； 几何已是单一纯函数（5 种面板共享）；控件化需重写吸顶/滚动/滚动条/滑块复位/行悬停压暗， 回归面极大。 * 56 处 InvalidateRect 并集：InvalidatePlotRect() 已是按消息的批处理点，逐处替换只增间接层。 验证：make release 零警告；Tools/uicheck 69/69；Tools/rendercheck 7 条功能断言 PASS，退出码 0。## 1. 新增 UiComponent 顶层组件协议（不是负优化） Components/Shared/Inc/UiComponent.hpp：纯接口、无状态，8 个方法 SetScale / Layout / Area / Paint / HitTest / OnMouseLeave / IsEditing / QueryCursor。 Toolbar / TabBar / SignalPanel / PlotView 本来就各自拥有完全同名同签名的成员， 因此改造 = 加 override + 补 Area()（PlotView 另加一个非 const 的 QueryCursor 转发， 因为它自己的查询会惰性建立行缓存），实现代码零改动、静态派发、体积无增长。 刻意不把 UiWidget 当作它的基类：UiWidget 是"树节点"（父给尺寸、父下探脏区、 命中沿树链派发），而 PlotView（4 层位图缓存）/ SignalPanel（行位图缓存）是 "地盘宿主"。强行上树会推翻"父脏则子全脏"的前提，历史上正是这类耦合导致过 "后台渲染覆盖平移结果""命中矩形错位"的事故。头文件里已写明这条理由。 Toolbar/TabBar 是两者的交集：对外实现 UiComponent，对内持有一棵 UiWidget 树。 ## 2. 宿主侧：四条手写链 -> 组件表 Application 新增 ComponentEntry{ component, target, chrome } 与 m_components （底->顶：plot -> panel -> toolbar -> tabBar），BuildComponentTable() 装配一次。 - ApplyDpi 6 行逐个 SetScale -> 1 个循环 - Relayout 手算三列 x 坐标 -> UiStackRects(内容区, HORIZONTAL, {panelW, splitW, AUTO}) - WM_MOUSELEAVE 逐个 OnMouseLeave -> 循环累积 chromeChanged / plotChanged - WM_SETCURSOR if/else if 链 -> 从表尾向前找首个命中者，取其 QueryCursor 顺带兑现历史缺口：UiLayout::UiStackRects 自引入以来第一次有了生产调用点。 有意保留显式的三条链（WM_LBUTTONDOWN / WM_LBUTTONUP / WM_MOUSEMOVE）：它们各自带 组件专属后置动作（提交重命名、构建派生信号、面板联动滚动、更新拖拽光标、 plotOnlyMove 决定局部失效还是整帧失效）。塞进表里只能靠 lambda 字段， 可读性反而下降 —— 属于用户明确禁止的"过度抽象"，因此不做。 ## 3. 大文件按职责拆分（纯整函数搬移，逐像素 0 差异） SignalPanelInteraction.cpp 2329 -> 831 行，拆出： SignalPanelEdit.cpp 616 内联编辑（筛选框、组名/信号名、数值、颜色与透明度） SignalPanelScroll.cpp 205 动画与滚动（折起、联动滚动、滚动到目标信号） SignalPanelMenu.cpp 527 弹出菜单（系数/偏移、镜像、右键菜单与命令回执） Shared/PopupMenu.cpp 1901 -> 706 行，拆出： PopupMenuLayout.cpp 753 尺寸测量、项矩形排版、滚动可见性 PopupMenuPaint.cpp 397 背景/阴影/项绘制 Inc/PopupMenuInternal.hpp 103 pmdetail 常量 + inline 辅助（跨 TU 安全） 拆分判据是"职责"而非行数；共享常量一律收敛到 *Internal.hpp。 ## 4. 代码审查（修 5 处） - SignalPanelInteraction.cpp 头注释仍写"4 片"，实际 6 片 -> 改为完整清单 - PopupMenuLayout.cpp 机械搬移时把构造函数一起搬走 -> 重复定义，只保留在交互分片 - PopupMenu.cpp 的 #include "PopupMenuInternal.hpp" 落进 namespace jdi 内 -> 移到文件头 - PopupMenuPaint.cpp 缺 UiControls.hpp（UiDrawEditFieldContent 未声明）-> 补 include - 全仓复查历史删除符号残留引用（m_paintPlot / ClampCursorsAfterPan / PaintFreeMarkerTooltip / CaptureDecorCache / FitSinglePointSignal / CsvTable / DataFile / .preflight / structcheck）-> 零命中 ## 5. Tools/ 剥离 git rm -r --cached Tools + .gitignore 新增 Tools/（本地文件保留，可随时复跑）。 ui_refactor 分支为全本地分支，另做 filter-branch 清除历史中的该目录。 ## 6. 验证 - make release / make debug：零 error 零 warning - rendercheck：A-H 八个场景哈希与改造前逐一相同 (A 2166933039626F66 B C444ECFEB18FD73D C 7984446D8E7A4418 D BF855879CA12F289 E 1C663E4118616016 F 0535292D8E07AE18 G 7A58172C46577729 H 23F390DD76141113) FUNC 7/7 PASS - uicheck：69 passed, 0 failed - TargetCheck.exe 891,392 B（< 900 KB 阈值） ## 7. 文档 Documents/UI_Refactor_Plan.md / UI_Refactor_Progress.md / UI_Refactor_Report.md 新增第五阶段章节；Documents/agent_mem.md 同步变更日志与「第七轮」硬约束。## 1. 边界描边按元素尺寸自适应（修复"小元素变成粗描边"） 旧规则四角固定 3-4px：对 15px 的复选框来说包角占短边 20%，看起来就是一整圈粗边框。 新规则全部以**短边**为基准： - 四边固定 1 设备像素； - 包角粗细 = min(基础 4/3, 短边/10)，再夹到 [1, 短边/4]； - 包角长度 = min(14, 短边/3)，且不小于包角粗细； - 短边 <= 12 只画四个 L 形角标记、**不画边**（一圈连续描边会让小方框显得"被框住"）； - 短边 <= 5 完全不画（再画就盖住元素本身）； - 内缩只用于「层级 > 0 且短边 >= 10」，否则小元素会被缩没。 同时**删除文字标签**（含 UiDebugPaintStyle）：黑底白字在小元素上必糊成一片，体积也省约 1.5KB。 ## 2. 拖网格滚动条时的"大量绘制残留"：三个独立成因 R1. PlotView::CollectDebugBoxes 读了 m_decorRects —— 那是**装饰层位图缓存**的登记矩形， 坐标处在位图/图层坐标系（带负 Y、超出绘图区），于是出现 (472,-27 1213x101) 这类 **横跨工具栏的幽灵巨框**。改为只用 LaneBadgeRect 与 m_legendHits（屏幕坐标）。 R2. Paint 的三条快路径（静态场景贴图 / 宽基底贴图 / 样式补丁）只重画**变化的部分**， 而调试边框是画在整个窗口上的叠加内容 ⇒ 上一帧的边框残留在未被重画的像素上， 直到松开鼠标走整幅重绘才消失。 新增 PlotView::SetForceFullRepaint(bool)：开启调试叠加层时禁用全部快路径。 R3. 组件内元素可能落在自己地盘之外（滚出可视区的 lane.rect 的 Y 为负），不裁剪就画到 工具栏/标签栏上。box 增加 clip：宿主按组件 Area() 设置，Add() 跳过无交集、 绘制时与 clip 求交。 另外把 Render 的 fullChrome 并入 m_showLayoutBounds，装饰区也保证完整一帧。 ## 3. 层级：排序 + 挖洞（修复二级菜单被下层边界覆盖） - UiDebugBoxList::PushLayer() + 按 (layer, depth) 稳定排序：后收集的内容压住先收集的。 - 但仅靠排序不够：调试线画在所有内容之后，下层组件的线仍会显示在不透明菜单上面。 新增 AddOccluder()：菜单/拾色器把本体登记为遮挡矩形，绘制**更低层**的 box 时用 Region::Exclude 挖洞。实测菜单区与子菜单区的琥珀/绿色像素均为 0。 - 浮层**不设** clip = 本体矩形：二级子菜单会展开到本体之外，设裁剪会把它整个裁掉。 ## 4. 验证 - make release / make debug 零 error 零 warning；TargetCheck.exe 906,752 B（885.5 KiB < 900 KiB）。 - 新增 .preflight/lbresid（MF4-Record.MF4 / 283 网格 / 拖滚动条）**5/5**： toolbar-unchanged-while-scrolling、repaint-same-state-is-identical、 toolbar-restored-by-full-repaint、residual-never-above-plot-area、later-layer-wins-over-earlier。 - 新增 .preflight/lbzorder **4/4**：菜单与二级子菜单区内下层颜色像素 = 0。 - 回归：.preflight/lbcheck 21/21、Tools/uicheck 69/69、 Tools/rendercheck「工具栏带以下」区域哈希 8/8 与上一轮逐一相同 + FUNC 7/7。 注：判断"是否有绘制残留"不能用"拖拽帧 vs 松开后一帧"——两者图层预热进度不同会产生 几十万像素的**合法**差异；正确判据是**同一状态连续两帧必须逐像素相同**。 ## 5. 文档 Documents/UI_Refactor_Plan.md / UI_Refactor_Progress.md / UI_Refactor_Report.md 追加第八阶段； Documents/agent_mem.md 同步变更日志与「2026-10-28 第十轮」硬约束与踩坑。## 1. 取消内缩（这是"边框不清晰"的主因） 第九轮为"父子矩形共边不叠粗"给 depth > 0 的 box 加了 1px 内缩。结果 GX 徽标 （30x17 逻辑像素的胶囊，圆角 = 高的一半，外接矩形正好等于 LaneBadgeRect）内缩 1px 后 框比形状小一圈 ⇒ 左右尖端与上下圆弧全部落在框外。 现行规则：**框 = 可见形状的外接矩形，绝不内缩**。父子共边时让"后画的覆盖"即可， 这本来就是正确的图层语义。层级 > 0 只影响配色，不再影响几何。 ## 2. 文本第一次有了几何身份（唯一出口回报，不逐处登记） 文本是本项目唯一"没有几何身份"的元素：65 处绘制点各自现算 gd::RectF、画完即弃。 逐处补登记必漏，因此在唯一出口回报一次： PaintUtil 新增 class UiTextRectSink { virtual void OnTextRect(const gd::RectF&) = 0; }; void UiSetTextRectSink(UiTextRectSink*); // 开关关闭时为 nullptr void UiSetTextRectOffset(float dx, float dy); // 离屏位图渲染的坐标换算 UiTextRectSink* UiGetTextRectSink(); DrawUiText() / UiTextAtClipped() 画完后按对齐方式 + 实测宽高把布局矩形**收窄成墨迹矩形** 再回报。UiDebugBoxList 直接继承该接口，宿主只需 UiSetTextRectSink(&m_debugBoxes) 一句。 开关关闭时只是一次空指针判断，正常绘制零影响。 ## 3. 缓存命中的行也要有文本框 面板的行是"先画进位图再贴回"，命中缓存的帧**根本不调用 UiText** ⇒ 文本框第二帧起消失。 做法：行渲染时用本地 RowTextCollector 收集（位图坐标）→ 连同位图存进 RowBitmapCache::textRects → 贴图时按 (originX, originY) 回放。 ⚠️ **必须无条件收集**：只在"外层有收集器"时收集会导致"关调试时滚过列表 → 打开调试 → 命中缓存 → 永远没有文本框"。 ## 4. 补齐 PlotView 漏项（全部读现成成员） m_timeAxisRect / m_scrollBarRect / BackToTopRect() / m_cursorSpanRect / m_cursorLabelRects / EditFieldRect() ## 5. 描边提速：图元 12 → 8 微基准结论：图元数量是唯一瓶颈（每次 FillRectangle ≈1µs）。 旧实现把每条边拆成"中段 1px + 两端各一段加粗"= 12 次；新实现 = 4 条 1px 边 + 4 个自适应角块。 实测 paintBoxes 5.892ms → 4.028ms（-32%），观感几乎一致（角仍是两条粗边的交点）。 ⚠️ 不要改写成 GraphicsPath/FillPath（单次约 20µs，比 12 段还慢）； GDI PolyPolygon 一次画 5688 个矩形要 114ms，更不能用。 ## 6. 关闭开关时清空容器（释放内存，避免误读） ## 7. 验证 - make release / make debug 零 error 零 warning；TargetCheck.exe 909,824 B（888.5 KiB < 900 KiB）。 - 新增探针 .preflight/lbcovr 7/7：box-time-axis / box-plot-scrollbar / box-back-to-top / box-gx-badge-matches-pill（容差 0.5px）/ text-boxes-collected（89 个）/ row-text-boxes-from-cached-rows / boxes-cleared-when-off。 - 回归：lbcheck 21/21、lbresid 5/5、lbzorder 4/4、uicheck 69/69。 - rendercheck：8 个场景的整帧与区域哈希与上一轮**逐一相同** + FUNC 7/7 （证明调试功能对正常绘制零影响）。 - 帧耗时分解（MF4 / 283 网格）：base 9.06ms、仅强制整帧 6.66ms、完整调试 11.35ms； collect 0.082ms、paintBoxes 4.028ms（上一轮 5.892ms）。 ## 8. 文档 Documents/UI_Refactor_Plan.md / UI_Refactor_Progress.md / UI_Refactor_Report.md 追加第九阶段； Documents/agent_mem.md 同步变更日志与「2026-10-28 第十一轮」硬约束与踩坑。