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

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 中 hideTooltip() 在托管分发阶段只作废快照，不回贴 Tooltip 自身区域

修复方案

• 修复思路:
  • Tooltip 既然是 Button 的内置浮层，就按“内置浮层”语义处理隐藏逻辑
  • 隐藏时直接调用 Tooltip 现有接口回贴背景快照并作废，不再区分托管分发阶段
• 关键改动:
  • 简化 Button::hideTooltip() 分支
  • 只要 tipVisible == true，统一调用 tipLabel.hide()
  • 保留 tipHoverTick 重置逻辑
• 涉及文件 / 类 / 函数:
  • 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 中 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 对外接口，只调整内部隐藏路径