Expose layout API and refresh regression docs

开发记录/Fix/Fix-BUG-20260410-0004-按钮Tooltip移出后不消失.md

@@ -0,0 +1,88 @@
+# Fix-BUG-20260410-0004
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: `Fix-BUG-20260410-0004`
+- 关联 BUG ID: `BUG-20260410-0004`
+- 修复目标: 让按钮 Tooltip 在鼠标移出后立即回贴并消失，不再残留在屏幕上
+- 状态：已验证
+- 负责人: Codex 协作修改
+- 分支 / 版本: 当前工作区 / 下一版本开发中
+
+## 根因分析
+
+- 根因:
+  - Tooltip 由 `Button` 在绘制末尾以内置浮层方式直接补画，不属于独立控件树节点。
+  - 隐藏路径里根据托管分发状态分叉处理，在托管分发阶段仅调用 `invalidateBackgroundSnapshot()`，只作废 Tooltip 快照，不执行回贴。
+  - 当本轮后续重绘只覆盖按钮本体区域时，Tooltip 占用的屏幕区域不会被擦除，因此表现为 Tooltip 留在屏幕上。
+- 触发条件:
+  - Tooltip 已显示
+  - 鼠标移出按钮区域，进入 `hideTooltip()` 分支
+- 为什么之前没发现:
+  - 之前更关注 Tooltip 的显示、Hover 切换和对话框遮挡链路
+  - “逻辑状态已隐藏，但屏幕区域无人回贴”的问题只有在当前托管重绘路径下才更稳定暴露
+- 关键证据:
+  - [`Button.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Button.cpp) 中 `hideTooltip()` 在托管分发阶段只作废快照，不回贴 Tooltip 自身区域
+
+## 修复方案
+
+- 修复思路:
+  - Tooltip 既然是 `Button` 的内置浮层，就按“内置浮层”语义处理隐藏逻辑
+  - 隐藏时直接调用 Tooltip 现有接口回贴背景快照并作废，不再区分托管分发阶段
+- 关键改动:
+  - 简化 `Button::hideTooltip()` 分支
+  - 只要 `tipVisible == true`，统一调用 `tipLabel.hide()`
+  - 保留 `tipHoverTick` 重置逻辑
+- 涉及文件 / 类 / 函数:
+  - [`Button.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Button.cpp)
+  - `Button::hideTooltip()`
+- 影响的 API / 行为:
+  - 无公开 API 变化
+  - 内部行为调整为“Tooltip 隐藏时总是立即回贴其自身区域”
+- 关键约束 / 不变量:
+  - Tooltip 继续作为 `Button` 内置浮层存在
+  - 不引入新的 Tooltip 控件树托管协议
+  - 不扩大 `Window` 托管重绘 coverage
+- 回滚点 / 开关:
+  - 若后续需要回退，只需恢复 `Button::hideTooltip()` 的旧分支逻辑
+
+## 影响评估
+
+- 影响范围:
+  - 启用 Tooltip 的 `Button`
+  - `KEY == 4` 等包含 Tooltip 的回归场景
+- 兼容性影响：无
+- 行为变化：有（Tooltip 隐藏时由“部分路径只作废快照”改为“统一立即回贴并作废”）
+- 性能影响：无
+- 回归风险:
+  - Tooltip 隐藏时会发生一次即时局部回贴
+  - 由于 Tooltip 本身就是按钮内置浮层，这个行为与其显示方式一致，风险相对可控
+
+## 验证结果
+
+- 验证步骤:
+
+1. 修改 [`Button.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Button.cpp) 中 `Button::hideTooltip()` 的 Tooltip 隐藏分支
+2. 编译 `Button.cpp`
+3. 编译 `z-testDome.cpp` 并指定 `KEY=4`，确认 Tooltip 相关 demo 入口可正常编译
+
+- 验证结果:
+  - 代码已完成修改
+  - 源码级编译验证通过
+  - 基于当前代码链路推演，Tooltip 离开按钮后会立即回贴自身区域，不再依赖按钮本体重绘覆盖 Tooltip 区域
+- 回归检查:
+  - 未做 GUI 手动交互回归
+  - 需用户进一步确认实际 Tooltip 行为
+- 验证证据:
+  - `Button.cpp` 编译通过
+  - `z-testDome.cpp /DKEY=4` 编译通过
+
+## 落地信息
+
+- Commit: 当前工作区未提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注:
+  - 本次修复未改动 Tooltip 对外接口，只调整内部隐藏路径

开发记录/Fix/Fix-BUG-20260415-0005-局部重绘补画上层兄弟修复.md

@@ -0,0 +1,83 @@
+# Fix-BUG-20260415-0005
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20260415-0005
+- 关联 BUG ID: BUG-20260415-0005
+- 修复目标: 收口局部重绘提交后的 overlay 兄弟补画机制
+- 状态：已完成
+- 负责人: Codex 协作修改
+- 分支 / 版本: 当前工作区
+
+## 根因分析
+
+- 根因:
+  - 局部重绘提交只重画了 dirty root 或 dirty child，没有按父容器真实绘制顺序把 coverage 上方相交的兄弟补画回来。
+- 触发条件:
+  - 下层区域写入像素后，上层 sibling 与本次 coverage 相交。
+- 为什么之前没发现：[可选]
+  - 旧场景多集中在对话框覆盖链，普通 sibling overlay 问题没有被系统化回归。
+- 关键证据：[可选]
+  - `KEY5` 中 `Table` 翻页覆盖顶层粉色浮层可稳定复现。
+  - 同父 `Canvas` 相交子控件在局部重绘后会出现相同症状。
+
+## 修复方案
+
+- 修复思路:
+  - 不做控件之间的长期联动标记。
+  - 改为由父容器在局部重绘提交后，按真实绘制顺序动态补画 coverage 上方相交的直接绘制单元。
+- 关键改动:
+  - `Window`：补画普通顶层控件 overlay，而不再只补 `Dialog`
+  - `Canvas`：补画 coverage 上方相交的直接子控件
+  - `TabControl`：按自己的真实绘制顺序补画页签按钮与页面
+  - overlay 补画前统一 `invalidateBackgroundSnapshot()`，避免旧快照反贴旧背景
+- 涉及文件 / 类 / 函数:
+  - [`Window.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Window.cpp)
+  - [`Canvas.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Canvas.cpp)
+  - [`TabControl.cpp`](D:/programming/imGUI-easyX/imGui-easyX/TabControl.cpp)
+- 影响的 API / 行为：[可选]
+  - 无对外 API 变化
+  - 局部重绘行为更严格遵守视觉合成顺序
+- 关键约束 / 不变量：[可选]
+  - 父容器只处理自己的直接绘制单元
+  - overlay 补画顺序必须与实际 `draw()` 顺序一致
+  - 不升级为整窗 / 整容器重绘，除非父容器自身快照或 dirty 条件不满足
+- 回滚点 / 开关：[可选]
+  - 无单独开关，回滚需回退相关局部重绘提交逻辑
+
+## 影响评估
+
+- 影响范围:
+  - `Window / Canvas / TabControl` 的局部重绘提交路径
+- 兼容性影响：无
+- 行为变化：有（局部重绘后会补画上层 overlay）
+- 性能影响：有（增加必要的 overlay 补画），但仍显著小于整窗 / 整容器重绘
+- 回归风险:
+  - 若 coverage 计算不准，仍可能遗漏或多画
+  - `TabControl` 局部重绘顺序必须和真实 `draw()` 顺序保持一致
+
+## 验证结果
+
+- 验证步骤:
+
+1. 编译 [`Window.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Window.cpp)、[`Canvas.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Canvas.cpp)、[`TabControl.cpp`](D:/programming/imGUI-easyX/imGui-easyX/TabControl.cpp)
+2. 编译 [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/z-testDome.cpp) `KEY=5`
+3. 回归 `Table` 翻页、相交 `Canvas`、`TabControl` 页签/页面遮挡场景
+
+- 验证结果:
+  - 编译级验证通过
+  - GUI 手动回归需继续在本机确认
+- 回归检查：[可选]
+  - `Table` 分页按钮与页码链已同步收口
+- 验证证据：[可选]
+  - `KEY5` 已新增更明确的 overlay 专项场景
+
+## 落地信息
+
+- Commit: 未提交（当前工作区）
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]
+  - `Dialog` 旧 synthetic move 逻辑本轮保留，后续可再评估是否纳入通用清理模型。

开发记录/Fix/Fix-BUG-20260415-0006-托管局部重绘脏子树提交链修复.md

@@ -0,0 +1,69 @@
+# Fix-BUG-20260415-0006
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20260415-0006
+- 关联 BUG ID: BUG-20260415-0006
+- 修复目标: 让托管局部重绘能够正确提交嵌套容器中的脏后代
+- 状态：已完成
+- 负责人: Codex
+- 分支 / 版本: 当前工作区
+
+## 根因分析
+
+- 根因: 托管局部重绘提交只识别 root 的直接 dirty child，不识别“自己不脏，但下面有 dirty descendant”的直接子分支。
+- 触发条件: 深层按钮状态变化后，叶子控件已 dirty，但中间层 Canvas 自己未 dirty。
+- 为什么之前没发现: 第一阶段主要覆盖顶层和浅层容器，三层嵌套专项场景在 KEY5 重构后才稳定暴露。
+- 关键证据:
+  - 按钮 hover / click 回调正常执行
+  - 日志正常，但视觉状态直到更大重绘才补出来
+
+## 修复方案
+
+- 修复思路: 把托管重绘提交从“只认直接 dirty child”改成“识别 dirty descendant，并提升到 root 下直接脏分支提交”。
+- 关键改动:
+  - 新增 `hasManagedDirtySubtree()`
+  - 新增 `getManagedRepaintDirectBranch(root)`
+  - `Canvas / TabControl` 局部提交时，直接子单元若拥有 dirty descendant，也继续 `commitManagedRepaint()`
+  - `Window::requestManagedRepaint()` 的 coverage 从最深叶子提升到 root 下直接脏分支
+- 涉及文件 / 类 / 函数:
+  - `Control.h / Control.cpp`
+  - `Canvas.cpp`
+  - `TabControl.cpp`
+  - `Window.cpp`
+- 影响的 API / 行为：无公开 API 变化
+- 关键约束 / 不变量:
+  - dirty descendant 不能再被中间层漏掉
+  - 托管局部提交顺序仍需保持与真实绘制顺序一致
+- 回滚点 / 开关：无
+
+## 影响评估
+
+- 影响范围: 嵌套 Canvas、页内嵌套容器、深层按钮 hover / click / tooltip 状态刷新
+- 兼容性影响：无
+- 行为变化：有（深层按钮视觉状态会及时刷新）
+- 性能影响：有（coverage 更保守，局部补画可能略增）
+- 回归风险:
+  - 局部提交 coverage 扩大后，上层 overlay 补画次数可能增加
+  - 需重点回归嵌套容器与顶层 overlay 场景
+
+## 验证结果
+
+- 验证步骤:
+
+1. 编译 `Control.cpp / Canvas.cpp / TabControl.cpp / Window.cpp / z-testDome.cpp`
+2. 使用 KEY5 三层嵌套区作为主回归入口
+3. 检查深层按钮 hover / press / release 是否能即时刷新
+
+- 验证结果: 编译通过；逻辑推演闭合；GUI 需用户本机手测
+- 回归检查：KEY5 三层嵌套、页内嵌套、overlay 补画主线
+- 验证证据：编译级验证通过
+
+## 落地信息
+
+- Commit: 未单独提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：该修复为机制修正，不是 KEY5 专项补丁

开发记录/Fix/Fix-BUG-20260415-0007-实际绘制coverage与overlay补画链修复.md

@@ -0,0 +1,71 @@
+# Fix-BUG-20260415-0007
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20260415-0007
+- 关联 BUG ID: BUG-20260415-0007
+- 修复目标: 让托管 coverage 与 overlay 补画基于实际绘制范围，而非控件本体 bounds
+- 状态：已完成
+- 负责人: Codex
+- 分支 / 版本: 当前工作区
+
+## 根因分析
+
+- 根因: `Window / Canvas / TabControl` 的 coverage 计算链默认使用 `getBoundsRect()`，没有把 Tooltip 这类附加绘制区域纳入。
+- 触发条件: 控件本体未与 overlay 相交，但附加绘制区域超出本体并写入更上层区域。
+- 为什么之前没发现: 第一轮主要解决普通控件和顶层 overlay；Tooltip 属于本体外附加绘制，直到 C / D 交界回归才稳定暴露。
+- 关键证据:
+  - 顶层按钮 Tooltip 正常，但容器内按钮 Tooltip 压到 D 橙区
+  - 根因与按钮本体 bounds 无关，与 Tooltip 超出范围有关
+
+## 修复方案
+
+- 修复思路: 引入“实际绘制 coverage”接口，让托管重绘与局部提交统一走真实覆盖范围。
+- 关键改动:
+  - 在 `Control` 增加 `getManagedRepaintCoverageRect()`
+  - `Button` 在 Tooltip 可见时返回“按钮矩形 + Tooltip 矩形”的并集
+  - `Canvas / TabControl / Table` 将可见内部绘制单元 coverage 递归并入
+  - `Window::requestManagedRepaint()` 和顶层 overlay 重组改为走 coverage 接口
+- 涉及文件 / 类 / 函数:
+  - `Control.h / Control.cpp`
+  - `Button.h / Button.cpp`
+  - `Canvas.h / Canvas.cpp`
+  - `TabControl.h / TabControl.cpp`
+  - `Table.h / Table.cpp`
+  - `Window.cpp`
+- 影响的 API / 行为：新增内部 virtual 接口，无公开 API 变化
+- 关键约束 / 不变量:
+  - Tooltip 智能选位不在本次修复范围内
+  - overlay 补画继续按父容器真实绘制顺序工作
+- 回滚点 / 开关：无
+
+## 影响评估
+
+- 影响范围: Tooltip、overlay 补画、复杂容器内附加绘制区域
+- 兼容性影响：无
+- 行为变化：有（Tooltip 与 overlay 层级恢复正确）
+- 性能影响：有（coverage 更保守，可能触发更多 overlay 补画）
+- 回归风险:
+  - coverage 扩大后顶层/容器层局部提交会多画一些 overlay
+  - 需重点回归 Tooltip 与多跳 overlay 场景
+
+## 验证结果
+
+- 验证步骤:
+
+1. 编译 `Control.cpp / Button.cpp / Canvas.cpp / TabControl.cpp / Table.cpp / Window.cpp / z-testDome.cpp`
+2. 在 KEY5 中验证 C 米区容器内按钮 Tooltip 与 D 橙区的遮挡关系
+3. 回归顶层按钮 Tooltip、页签按钮 Tooltip、浮层按钮 Tooltip
+
+- 验证结果: 编译通过；逻辑推演闭合；GUI 需用户本机手测
+- 回归检查：KEY5 C/D 交界区、TabControl 页签、三层嵌套按钮 Tooltip
+- 验证证据：编译级验证通过
+
+## 落地信息
+
+- Commit: 未单独提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：Tooltip 智能选位明确延期，本次只修“coverage 正确性”

开发记录/Fix/Fix-BUG-20260415-0008-TabControl页签层级与重复激活链路修复.md

@@ -0,0 +1,75 @@
+# Fix-BUG-20260415-0008
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20260415-0008
+- 关联 BUG ID: BUG-20260415-0008
+- 修复目标: 修正 TabControl 页签层级和重复激活已激活页签的回调链
+- 状态：已完成
+- 负责人: Codex
+- 分支 / 版本: 当前工作区
+
+## 根因分析
+
+- 根因:
+  - `TabControl::draw()` 与局部重绘顺序为“先页签按钮，后页面”，导致页签 Tooltip 被页面盖掉。
+  - `Button::setButtonClick()` 对 `TOGGLE` 没有做“同状态短路”，外部重复激活同一页签会重复触发 `onToggleOnCallback`。
+  - `TabControl::setActiveIndex()` 也没有对“目标已是当前激活页”做保护，导致当前可见页的 `onWindowResize()` / `setIsVisible(true)` 链被重复执行。
+- 触发条件:
+  - 任意页打开时触发页签 Tooltip
+  - 外部对已激活页签再次 `setActiveIndex()`
+- 为什么之前没发现: KEY1 外部按钮重复激活场景和 KEY5 页签 Tooltip 场景是后续专项回归才补出来的。
+- 关键证据:
+  - 所有页关闭时页签 Tooltip 正常，说明问题在页面层级覆盖
+  - 只点一次外部激活正常，重复激活后残影出现，说明问题在重复回调链
+
+## 修复方案
+
+- 修复思路:
+  - 把 TabControl 绘制/局部重绘顺序改为“先页面、后页签按钮”
+  - 给 `TOGGLE` 状态设置和 `setActiveIndex()` 增加同状态短路
+- 关键改动:
+  - `TabControl::draw()` 改成先画页面、后画页签按钮
+  - `TabControl::requestRepaint(this)` 的局部提交顺序同步调整
+  - `Button::setButtonClick()` 在 `TOGGLE` 同状态时直接返回
+  - `TabControl::setActiveIndex()` 若目标已是当前激活页则直接返回
+- 涉及文件 / 类 / 函数:
+  - `TabControl.cpp`
+  - `Button.cpp`
+- 影响的 API / 行为:
+  - 重复设置相同 `TOGGLE` 状态不再重复触发回调
+- 关键约束 / 不变量:
+  - 页签按钮视觉层级应始终高于页面
+  - 外部重复激活同一页签不应重新走页面显示链
+- 回滚点 / 开关：无
+
+## 影响评估
+
+- 影响范围: TabControl 页签 Tooltip、外部页签激活、页内超出页面边界的复合控件
+- 兼容性影响：有（收紧了 TOGGLE 同状态重复 set 的回调语义）
+- 行为变化：有（页签 Tooltip 层级恢复正确；重复激活同一页签不再重复触发回调）
+- 性能影响：无
+- 回归风险:
+  - 如有外部代码依赖“同状态重复 set 也要重复触发回调”，该行为将被收掉
+  - 需重点回归 KEY1 和 KEY5 的 TabControl 场景
+
+## 验证结果
+
+- 验证步骤:
+
+1. 编译 `Button.cpp / TabControl.cpp`
+2. 编译 `z-testDome.cpp` 的 `KEY=1`
+3. 回归 `KEY5` 页签 Tooltip 与 `KEY1` 外部按钮重复激活页签场景
+
+- 验证结果: 编译通过；逻辑推演闭合；GUI 需用户本机手测
+- 回归检查：KEY1 页签 1 表格超出区、KEY5 页签 Tooltip
+- 验证证据：编译级验证通过
+
+## 落地信息
+
+- Commit: 未单独提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：此修复不包含 TabControl 其它内部布局专题