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 对外接口，只调整内部隐藏路径