关于工具提示控件

当用户将鼠标指针悬停在工具或其他 UI 元素上时,工具提示会自动显示或弹出。 工具提示显示在指针附近,当用户单击鼠标按钮、将指针移开工具时消失,或者只需等待几秒钟。

下图中的工具提示控件显示有关Windows桌面上的文件的信息。 将鼠标移到插图上时,还应看到包含描述性文本的实时工具提示。

screen shot showing text in a tooltip that appears over a file on the desktop

本部分介绍工具提示控件的工作原理以及创建方法。

工具提示行为和外观

工具提示控件可以显示单行文本或多行。 其角落可以圆角或正方形。 他们可能或可能没有指向卡通语音气球之类的工具的词干。 工具提示文本可以是固定的,也可以随鼠标指针一起移动,称为跟踪。 固定文本可以显示在工具旁边,也可以通过工具显示,该工具称为就地显示。 标准工具提示是固定的,显示单行文本,有方角,没有指向该工具的词干。

跟踪工具提示(由 4.70 版 通用控件支持)动态更改屏幕上的位置。 通过快速更新位置,这些工具提示控件似乎可以顺利移动或“跟踪”。如果希望工具提示文本在鼠标指针移动时的位置,这些文本非常有用。 有关跟踪工具提示的详细信息以及显示如何创建工具的代码的示例,请参阅 跟踪工具提示

多行工具提示(也受 4.70 版常见控件支持)在多个行上显示文本。 这对于显示冗长的消息很有用。 有关详细信息和演示如何创建多行工具提示的示例,请参阅 多行工具提示

气球工具提示显示在圆角框和指向该工具的词干中。 它们可以是单行或多行。 下图显示了一个气球工具提示,其中包含其默认位置中的词干和矩形。 有关气球工具提示的详细信息以及演示如何创建它们的示例,请参阅 使用工具提示控件

screen shot showing a tooltip containing one line of text, positioned above a button on a dialog box

工具提示还可以包含标题文本和图标,如下图所示。 请注意,工具提示必须具有文本;如果它只有标题文本,则工具提示不会显示。 此外,除非有标题,否则不会显示该图标。

screen shot showing a tooltip with an icon, title, and text, positioned below a button on a dialog box

有时,文本字符串被剪裁,因为它们太长,无法完全显示在一个小窗口中。 就地工具提示用于显示已剪裁的对象的文本字符串,如下图中的文件名。 有关如何创建就地工具提示的示例,请参阅 就地工具提示

screen shot showing a tooltip containing a file name positioned next to a file icon in a tree control

光标必须悬停在工具上一段时间后才会显示工具提示。 此超时的默认持续时间由用户的双击时间控制,通常大约半秒。 若要指定非默认超时值,请发送工具提示控件 TTM_SETDELAYTIME 消息。

创建工具提示控件

若要创建工具提示控件,请调用 CreateWindowEx 并指定 TOOLTIPS_CLASS 窗口类。 加载公共控件 DLL 时,会注册此类。 若要确保加载此 DLL,请在应用程序中包括 InitCommonControlsEx 函数。 必须将工具提示控件显式定义为最顶层。 否则,父窗口可能会覆盖该窗口。 以下代码片段演示如何创建工具提示控件。

HWND hwndTip = CreateWindowEx(NULL, TOOLTIPS_CLASS, NULL,
                            WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            hwndParent, NULL, hinstMyDll,
                            NULL);

SetWindowPos(hwndTip, HWND_TOPMOST,0, 0, 0, 0,
             SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);

工具提示控件的窗口过程会自动设置控件的大小、位置和可见性。 工具提示窗口的高度基于当前选择到工具提示控件的设备上下文中的字体的高度。 宽度因工具提示窗口中当前字符串的长度而异。

激活工具提示控件

工具提示控件可以是活动控件或非活动控件。 当它处于活动状态时,当鼠标指针位于工具上时,将显示工具提示文本。 当它处于非活动状态时,即使指针位于工具上,工具提示文本也不会显示。 TTM_ACTIVATE消息将激活和停用工具提示控件。

支持工具

工具提示控件可以支持任意数量的工具。 若要支持特定工具,必须通过发送控件来向工具提示控件注册该工具 TTM_ADDTOOL 消息。 该消息包括 TOOLINFO 结构的地址,它提供工具提示控件需要显示工具文本的信息。 TOOLINFO 结构的 uID 成员由应用程序定义。 每次添加工具时,应用程序都会提供唯一标识符。 需要 TOOLINFO 结构的 cbSize 成员,并且必须指定结构的大小。

工具提示控件支持实现为窗口 (的工具,例如子窗口或控件窗口) ,以及窗口工作区中的矩形区域。 添加作为矩形区域实现的工具时,TOOLINFO 结构的 hwnd 成员必须指定包含区域的窗口的句柄,而 rect 成员必须指定区域的边界矩形的客户端坐标。 此外, uID 成员必须为该工具指定应用程序定义的标识符。

添加作为窗口实现的工具时,TOOLINFO 结构的 uID 成员必须包含工具的窗口句柄。 此外, uFlags 成员必须指定 TTF_IDISHWND 值,该值指示工具提示控件将 uID 成员解释为窗口句柄。

显示文本

向工具提示控件添加工具时,TOOLINFO 结构的 lpszText 成员必须指定要为该工具显示的字符串的地址。 添加工具后,可以使用 TTM_UPDATETIPTEXT 消息更改文本。

如果 lpszText 的高顺序单词为零,则低序单词必须是字符串资源的标识符。 当工具提示控件需要文本时,系统会从 TOOLINFO 结构发成员标识的应用程序实例加载指定的字符串资源。

如果在 lpszText 成员中指定LPSTR_TEXTCALLBACK值,工具提示控件会在工具提示控件需要显示工具文本时通知 TOOLINFOstructure的 hwnd 成员中指定的窗口。 工具提示控件将 TTN_GETDISPINFO 通知代码发送到窗口。 该消息包括 NMTTDISPINFO 结构的地址,该结构包含窗口句柄以及工具的应用程序定义标识符。 该窗口检查结构以确定需要文本的工具,并用工具提示控件需要的信息填充相应的结构成员,以便显示字符串。

注意

标准工具提示文本的最大长度为 80 个字符。 有关详细信息,请参阅 NMTTDISPINFO 结构。 多行工具提示文本可能更长。

 

许多应用程序创建包含对应于菜单命令的工具的工具栏。 对于此类工具,工具提示控件可以方便地显示与相应菜单项相同的文本。 除非控件具有TTS_NOPREFIX样式,否则系统会自动从传递给工具提示控件的所有字符串中去除和 () & 快捷键字符,并在第一个制表符 (\t) 终止字符串。

若要检索工具的文本,请使用 TTM_GETTEXT 消息。

消息传送和通知

当鼠标指针悬停在某个区域上时,通常显示工具提示文本,通常是由工具(如按钮控件)定义的矩形。 但是,Microsoft Windows仅将鼠标相关的消息发送到包含指针的窗口,而不是工具提示控件本身。 必须将鼠标相关信息中继到工具提示控件,以便它在适当的时间和地点显示工具提示文本。

如果:

  • 该工具是控件,或定义为工具 TOOLINFO 结构中的矩形。
  • 与该工具关联的窗口与工具提示控件位于同一线程中。

如果满足这两个条件,请在工具 TOOLINFO 结构的 uFlags 成员中设置TTF_SUBCLASS标志,将该工具添加到具有TTM_ADDTOOL的工具提示控件。 然后,必要的鼠标消息将自动中继到工具提示控件。

TTF_SUBCLASS 设置为将鼠标消息中继到控件足以满足大多数目的。 但是,在工具提示控件与工具窗口之间没有直接连接的情况下,它不起作用。 例如,如果工具作为应用程序定义的窗口中的矩形区域实现,则窗口过程将接收鼠标消息。 设置 TTF_SUBCLASS 足以确保将它们传递给控件。 但是,如果工具作为系统定义的窗口实现,则鼠标消息将发送到该窗口,并且不能直接提供给应用程序。 在这种情况下,必须对窗口进行子类,或使用消息挂钩访问鼠标消息。 然后,必须使用 TTM_RELAYEVENT显式将鼠标消息中继到工具提示控件。 有关如何使用 TTM_RELAYEVENT的示例,请参阅 跟踪工具提示

当工具提示控件收到 WM_MOUSEMOVE 消息时,它确定鼠标指针是否位于工具的边界矩形中。 如果是,工具提示控件设置计时器。 在超时间隔结束时,工具提示控件检查指针的位置,以查看指针是否已移动。 如果没有,工具提示控件将检索该工具的文本并显示工具提示。 工具提示控件继续显示窗口,直到它收到中继的按钮向上或按钮关闭消息,或者直到 WM_MOUSEMOVE 消息指示指针已移动到工具边界矩形之外。

工具提示控件实际上具有与之关联的三个超时持续时间。 初始持续时间是鼠标指针在工具提示窗口显示前必须保持固定在工具边界矩形内的时间。 重新放映持续时间是当指针从一个工具移动到另一个工具之前显示后续工具提示窗口之前延迟的长度。 弹出持续时间是工具提示窗口在隐藏之前保持显示的时间。 也就是说,如果在显示工具提示窗口后指针在边界矩形内保持固定状态,则工具提示窗口将自动隐藏在弹出窗口持续时间的末尾。 可以使用 TTM_SETDELAYTIME 消息来调整所有超时持续时间。

如果应用程序包含作为矩形区域实现的工具以及控件的大小或位置发生更改,则应用程序可以使用 TTM_NEWTOOLRECT 消息向工具提示控件报告更改。 应用程序不需要报告作为窗口实现的工具的大小和位置更改,因为工具提示控件使用工具的窗口句柄来确定鼠标指针是否位于工具上,而不是工具的边界矩形。

当工具提示即将显示时,工具提示控件会向所有者窗口发送 一个TTN_SHOW 通知代码。 当工具提示即将隐藏时,所有者窗口会收到 TTN_POP 通知代码。 每个通知代码都会在 WM_NOTIFY 消息的上下文中发送。

命中测试

使用TTM_HITTEST消息可以检索工具提示控件保留的有关占用特定点的工具的信息。 该消息包含一个 TTHITTESTINFO 结构,该结构包含窗口句柄、点坐标和 TOOLINFO 结构的地址。 工具提示控件确定工具是否占用该点,如果这样做,请使用有关该工具的信息填充 TOOLINFO

默认消息处理

下表描述了工具提示控件的窗口过程处理的消息。

消息 说明
WM_CREATE 确保工具提示控件具有 WS_EX_TOOLWINDOWWS_POPUP 窗口样式。 它还分配内存并初始化内部变量。
WM_DESTROY 释放为工具提示控件分配的资源。
WM_GETFONT 返回工具提示控件用于绘制文本的字体的句柄。
WM_MOUSEMOVE 隐藏工具提示窗口。
WM_PAINT 绘制工具提示窗口。
WM_SETFONT 设置工具提示控件用于绘制文本的字体的句柄。
WM_TIMER 如果工具已更改位置或鼠标指针在工具外部移动,则隐藏工具提示窗口。 否则,它会显示工具提示窗口。
WM_WININICHANGE 重置基于系统指标的内部变量。