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