跳到主要内容

工具提示 Tooltip

工具提示（Tooltip）是 UI 里的“贴心小助手”：当鼠标悬停在某个按钮或图标上时，弹出一行简短的说明文字，告诉用户这个功能是干嘛的。HiEasyX 的 Tooltip 使用极其简单，却能显著提升界面的友好度。

函数原型​

void Tooltip(const HXString &Text);

参数说明​

参数类型默认值说明
TextHXString—要显示的提示文字。支持换行符 \n。

返回值​

void。

使用方式​

Tooltip 的调用位置非常关键：它必须紧跟在你想要解释的控件之后。HiEasyX 会记住上一个控件的矩形区域，当鼠标悬停在该区域时，就会显示出你设置的提示文字。

HX::Button(HXStr("保存"), btn);
HX::Tooltip(HXStr("Ctrl+S\n将当前文件保存到磁盘"));
紧跟调用

Tooltip 本身不是独立控件，它更像是一个“附加说明”。如果你在 Button 和 Tooltip 之间插了一个 Text，提示就会挂到那个 Text 上，而不是按钮。

全局配置​

如果你想统一调整所有 Tooltip 的样式（而不是逐个设置），可以修改 TooltipProfile：

TooltipProfile​

字段类型默认值说明
ShowDelayMsint200鼠标悬停后多久显示提示，单位毫秒。设为 0 则立刻显示。
Paddingint6提示框内部文字到边框的距离。
OffsetXYint15提示框相对于鼠标位置的偏移量（右下方）。
BackgroundColorHXColor主题背景色提示框背景色。
BorderColorHXColor主题边框色提示框边框色。
TextColorHXColor主题文字色文字颜色。
FontSizeint14提示文字字体大小。
如何修改全局 Tooltip 样式？

TooltipProfile 通常通过 HX::GetTheme() 或框架内部全局实例访问。在大多数场景下，默认的淡黄/浅灰提示框已经足够美观。如果你有特殊的暗色主题需求，可以在初始化时统一修改。

完整示例​

#include <include/hex.h>
#include <include/impl/EasyX/hex_impl_easyx.h>

int main() {
    static HX::WindowProfile wp;
    while (true) {
        HX::HXBegin();
        ExMessage msg;
        while (peekmessage(&msg)) {
            HX::PushMessage(HX::GetHXMessage(&msg));
        }

        HX::Window(HXStr("Tooltip 示例"), wp);

        // 按钮 + 提示
        HX::ButtonProfile btnSave;
        HX::Button(HXStr("保存"), btnSave);
        HX::Tooltip(HXStr("快捷键：Ctrl+S\n保存当前工程到磁盘。"));

        // 滑块 + 提示
        static float g_volume = 0.75f;
        HX::SliderProfile1f sld;
        HX::Slider1f(HXStr("主音量"), g_volume, sld);
        HX::Tooltip(HXStr("调节系统总音量，范围 0% ~ 100%"));

        // 复选框 + 提示
        static HX::CheckboxProfile chk;
        HX::Checkbox(HXStr("开发者模式"), chk);
        HX::Tooltip(HXStr("开启后将显示调试信息和额外菜单。"));

        HX::End();
        HX::Render();
    }

    return 0;
}
支持多行

Tooltip 的文字里可以直接放 \n 换行，非常适合写两行提示：第一行是功能简述，第二行是快捷键。

延迟显示的意义​

默认 ShowDelayMs = 200 不是随便设的。如果提示立刻弹出，用户鼠标只是快速划过界面时，屏幕会闪烁一大片提示框，非常烦人。200 毫秒的延迟刚好过滤掉“路过”的鼠标动作，只在用户真正停住思考时才出现提示。

如果你觉得 200ms 太慢，可以调小；如果你的提示内容很长，用户需要更多时间阅读，也可以适当调大。

常见疑问​

Q：Tooltip 可以显示在鼠标上方吗？ 目前默认偏移是右下方（OffsetXY = 15）。如果你想改变位置（比如避免超出屏幕右边界），需要在外部根据鼠标坐标手动判断并调整。未来版本可能会增加自动避边功能。

Q：我可以在 Canvas 上用 Tooltip 吗？ Tooltip 依赖“上一个控件”的矩形区域。Canvas 不是标准控件，没有自动布局矩形，所以 Tooltip 不会正确附着。在 Canvas 上实现悬停提示，建议自己在 Canvas 回调里判断鼠标位置并手动绘制提示框。

Q：Tooltip 会遮挡点击吗？ 不会。Tooltip 是 purely visual 的浮层，不会拦截鼠标消息。你可以在它显示的同时正常点击背后的控件。

运行效果​

截图占位符：请补充 $name 控件的运行效果截图。

截图占位符：请补充 Tooltip 运行效果 的运行效果截图，保存为 ./assets/Tooltip_view.png。`n