概念
Tooltip 不是独立控件，而是控件级属性 + 全局渲染系统：
• TooltipText：简单文本提示（最常用）
• Tooltip Desc：自定义 Measure + Paint 回调实现富内容
• Resolver：全局回调，根据悬停控件动态决定提示内容
• 延迟：悬停一段时间后显示，移开立即消失
API 速查
| 函数 | 说明 |
|---|---|
int xuiWidgetSetTooltipText(xui_widget pW, const char* sText) | 设置文本提示 |
int xuiWidgetSetTooltip(xui_widget pW, const xui_tooltip_desc_t* pDesc) | 自定义提示 |
int xuiWidgetSetTooltipResolver(xui_widget pW, xui_tooltip_resolve_proc onResolve, void* pUser) | 解析回调 |
int xuiToolbarSetItemTooltip(xui_widget pW, int iIndex, const char* sText) | 工具栏项提示 |
编译本章示例
gcc -O2 -I. -o ch158.exe ch158_main.c src\xui_*.c build\xge.lib -lm -lws2_32 -liphlpapi -lgdi32 -luser32 -lshell32 -lopengl32 -lole32 -lwinmm -lavrt
.\ch158.exe示例：按钮提示
// 简单文本提示
xuiWidgetSetTooltipText(pBtnSave, "保存 (Ctrl+S)");
xuiWidgetSetTooltipText(pBtnUndo, "撤销上一步操作");
// 自定义绘制提示
xui_tooltip_desc_t tip = { 0 };
tip.sText = "颜色预览";
tip.onMeasure = OnTipMeasure; // 返回尺寸
tip.onPaint = OnTipPaint; // 自定义绘制
tip.pUser = pColorData;
xuiWidgetSetTooltip(pColorSwatch, &tip);
// Resolver：根据控件动态生成提示
xuiWidgetSetTooltipResolver(pRoot, OnResolveTooltip, NULL);
static int OnResolveTooltip(xui_context pCtx, xui_widget pW,
xui_tooltip_desc_t* pDesc, void* pUser) {
// 返回 1 表示已处理，0 表示使用默认
pDesc->sText = GetWidgetHelp(pW);
return 1;
}完整代码
将以下代码保存为 ch158_main.c，编译后运行即可看到 Tooltip 效果：
#include "xge.h"
#include "xui.h"
static xui_context g_pCtx;
static int onFrame(void* pUser) {
(void)pUser;
xgeClear(0x081114FF);
float mx, my;
xgeMouseGet(&mx, &my);
xuiInputPointerMove(g_pCtx, mx, my);
xuiUpdate(g_pCtx, xgeGetDelta());
xuiLayout(g_pCtx);
xuiRender(g_pCtx, NULL, NULL, 0);
return XGE_OK;
}
int main(void) {
xge_desc_t d = { 0 };
d.iWidth = 800; d.iHeight = 600;
d.sTitle = "ch158 - Tooltip";
d.iFlags = XGE_INIT_VSYNC;
xgeInit(&d);
xuiCreate(&g_pCtx);
extern const xui_proxy_t tXgeProxy;
xui_proxy_t tXgeProxy = xuiProxyXge();
xuiSetProxy(g_pCtx, &tXgeProxy);
xuiSetViewportSize(g_pCtx, 800, 600);
xui_widget pRoot;
xuiWidgetCreate(g_pCtx, &pRoot);
xuiWidgetSetLayoutType(pRoot, XUI_LAYOUT_COLUMN);
xuiWidgetSetRect(pRoot, (xui_rect_t){0, 0, 800, 600});
xuiWidgetSetPadding(pRoot, 40, 40, 40, 40);
/* 间距：用内联样式或子控件布局参数设置 */
xuiSetRootWidget(g_pCtx, pRoot);
/* 创建带 Tooltip 的按钮 */
xui_button_desc_t b1 = { 0 };
b1.sText = "保存";
xui_widget pBtn1;
xuiButtonCreate(g_pCtx, &pBtn1, &b1);
xuiWidgetSetRect(pBtn1, (xui_rect_t){0, 0, 120, 36});
xuiWidgetSetTooltipText(pBtn1, "保存 (Ctrl+S)");
xuiWidgetAddChild(pRoot, pBtn1);
xui_button_desc_t b2 = { 0 };
b2.sText = "撤销";
xui_widget pBtn2;
xuiButtonCreate(g_pCtx, &pBtn2, &b2);
xuiWidgetSetRect(pBtn2, (xui_rect_t){0, 0, 120, 36});
xuiWidgetSetTooltipText(pBtn2, "撤销上一步操作");
xuiWidgetAddChild(pRoot, pBtn2);
xgeRun(onFrame, NULL);
xuiDestroy(g_pCtx);
xgeUnit();
return 0;
}代码讲解
- SetTooltipText：最简单的文本提示，悬停一段时间后显示。
- 自动定位：提示框自动避开屏幕边缘。
- 优先级：Tooltip Desc > TooltipText > Resolver。
- Resolver：可根据控件动态生成提示内容。
要点与陷阱
- 优先级：Tooltip Desc > TooltipText > Resolver。
- 延迟：通过 xui_tooltip_desc_t 中的延迟字段控制显示时机。
- 颜色：全局 Tooltip 背景/文字颜色在 Theme 中配置。
- 自动定位：提示框自动避开屏幕边缘。
进阶练习
- 富文本提示：onPaint 中绘制图标 + 多行文本 + 快捷键。
- 控件帮助系统：Resolver 根据控件 ID 查表返回帮助文本。
