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

BUG-20260410-0004

适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。

基本信息

• ID: BUG-20260410-0004
• 标题: 按钮 Tooltip 显示后，鼠标移出按钮区域提示框不消失
• 状态：已修复
• 严重性：S3
• 优先级：P1
• 模块: Button / Tooltip / 托管重绘
• 版本 / 分支: 当前工作区 / 下一版本开发中
• 环境: Windows + EasyX，本地 GUI Demo
• 发现人: 用户
• 关联 Fix ID: Fix-BUG-20260410-0004

问题描述

• 现象:
  • 按钮启用 Tooltip 后，提示框成功显示。
  • 鼠标离开按钮区域后，Tooltip 仍残留在屏幕上，不会及时消失。
• 影响范围:
  • 所有启用了 Tooltip 的 Button
  • 典型场景包括 KEY == 4 的综合回归用例
• 期望结果:
  • 鼠标离开按钮后，Tooltip 应立即回贴并消失，不留下残影
• 实际结果:
  • Tooltip 逻辑状态已切换为隐藏，但屏幕上的提示框区域未被及时擦除

复现信息

• 前置条件:
  • 使用启用 Tooltip 的按钮
• 复现步骤:

1. 运行带 Tooltip 按钮的 Demo
2. 将鼠标悬停在按钮上，等待 Tooltip 显示
3. 将鼠标移出按钮区域，观察 Tooltip 是否立即消失

• 复现概率：高概率
• 最小复现 Demo:
  • z-testDome.cpp 中 KEY == 4
• 证据：现象观察 + 代码链路分析

初步分析

• 疑似位置:
  • Button.cpp
  • Button::hideTooltip()
• 触发条件:
  • Tooltip 已经显示
  • 鼠标离开按钮，进入 Tooltip 隐藏分支
• 相关线索:
  • Tooltip 不是独立控件树成员，而是 Button::draw() 末尾补画的内置浮层
  • 隐藏时若只作废快照而不回贴 Tooltip 自己的背景，按钮本体重绘并不会覆盖 Tooltip 占用区域
• 最近相关改动:
  • 事件改状态 / Window 托管重绘收口
  • 布局系统第一阶段重构

跟踪信息

• 首次发现时间: 2026-04-10
• 最后更新时间: 2026-04-10
• 修复版本: 待定
• 验证版本: 当前工作区
• 备注:
  • 本文档仅记录问题本身，具体修复方案见关联 Fix 文档