Share via


CToolTipCtrl

封装“工具提示控件”功能,此控件是一个小型弹出窗口,显示一行文本来说明应用程序中工具的用途。

语法

class CToolTipCtrl : public CWnd

成员

公共构造函数

名称 描述
CToolTipCtrl::CToolTipCtrl 构造 CToolTipCtrl 对象。

公共方法

名称 描述
CToolTipCtrl::Activate 激活和停用工具提示控件。
CToolTipCtrl::AddTool 向工具提示控件注册工具。
CToolTipCtrl::AdjustRect 在工具提示控件的文本显示矩形与其窗口矩形之间转换。
CToolTipCtrl::Create 创建工具提示控件并将其附加到 CToolTipCtrl 对象。
CToolTipCtrl::CreateEx 创建具有指定 Windows 扩展样式的工具提示控件,并将其附加到 CToolTipCtrl 对象。
CToolTipCtrl::DelTool 从工具提示控件中移除工具。
CToolTipCtrl::GetBubbleSize 检索工具提示的大小。
CToolTipCtrl::GetCurrentTool 检索当前工具提示控件显示的工具提示窗口的大小、位置和文本等信息。
CToolTipCtrl::GetDelayTime 检索当前为工具提示控件设置的初始持续时间、弹出持续时间和重新显示持续时间。
CToolTipCtrl::GetMargin 检索为工具提示窗口设置的上边距、下边距、左边距和右边距。
CToolTipCtrl::GetMaxTipWidth 检索工具提示窗口的最大宽度。
CToolTipCtrl::GetText 检索工具提示控件为工具维护的文本。
CToolTipCtrl::GetTipBkColor 检索工具提示窗口中的背景色。
CToolTipCtrl::GetTipTextColor 检索工具提示窗口中的文本颜色。
CToolTipCtrl::GetTitle 检索当前工具提示控件的标题。
CToolTipCtrl::GetToolCount 检索工具提示控件维护的工具计数。
CToolTipCtrl::GetToolInfo 检索工具提示控件维护的工具相关信息。
CToolTipCtrl::HitTest 测试一个点,确定它是否在给定工具的边界矩形范围内。 如果是,检索工具相关信息。
CToolTipCtrl::Pop 从视图中移除显示的工具提示窗口。
CToolTipCtrl::Popup 导致当前工具提示控件显示在上一条鼠标消息的坐标处。
CToolTipCtrl::RelayEvent 将鼠标消息传递给工具提示控件进行处理。
CToolTipCtrl::SetDelayTime 设置工具提示控件的初始持续时间、弹出持续时间和重新显示持续时间。
CToolTipCtrl::SetMargin 设置工具提示窗口的上边距、下边距、左边距和右边距。
CToolTipCtrl::SetMaxTipWidth 设置工具提示窗口的最大宽度。
CToolTipCtrl::SetTipBkColor 设置工具提示窗口中的背景色。
CToolTipCtrl::SetTipTextColor 设置工具提示窗口中的文本颜色。
CToolTipCtrl::SetTitle 向工具提示添加标准图标和标题字符串。
CToolTipCtrl::SetToolInfo 设置工具提示为工具维护的信息。
CToolTipCtrl::SetToolRect 设置工具的新边界矩形。
CToolTipCtrl::SetWindowTheme 设置工具提示窗口的视觉样式。
CToolTipCtrl::Update 强制重新绘制当前工具。
CToolTipCtrl::UpdateTipText 设置工具的工具提示文本。

注解

“工具”是一个窗口(如子窗口或控件)或窗口工作区中应用程序定义的矩形区域。 工具提示在大多数时间都是隐藏的,它仅在用户将光标置于工具上并在其上停留约半秒时间时显示。 工具提示显示在光标附近,并且在用户单击鼠标按钮或将光标移离工具时消失。

CToolTipCtrl 提供用于控制工具提示的初始时间和持续时间、工具提示文本周围的边距宽度、工具提示窗口本身的宽度以及工具提示的背景色和文本颜色的功能。 一个工具提示控件可以提供多个工具的信息。

CToolTipCtrl 类提供了 Windows 公共工具提示控件的功能。 此控件(因此决定 CToolTipCtrl 类)仅适用于在 Windows 95/98 和 Windows NT 版本 3.51 及更高版本下运行的程序。

若要详细了解如何启用工具提示,请参阅 Windows 中未派生自 CFrameWnd 的工具提示

有关使用 CToolTipCtrl 的详细信息,请参阅控件使用 CToolTipCtrl

继承层次结构

CObject

CCmdTarget

CWnd

CToolTipCtrl

要求

标头afxcmn.h

CToolTipCtrl::Activate

调用此函数以激活或停用工具提示控件。

void Activate(BOOL bActivate);

参数

bActivate
指定是激活还是停用工具提示控件。

备注

如果 bActivateTRUE,则激活控件;如果为 FALSE,则停用控件。

如果工具提示控件处于活动状态,则在光标置于向该控件注册的工具上时,将显示工具提示信息;如果它处于非活动状态,那么即使光标置于工具上,也不会显示工具提示信息。

示例

请参阅 CPropertySheet::GetTabControl 的示例。

CToolTipCtrl::AddTool

向工具提示控件注册工具。

BOOL AddTool(
    CWnd* pWnd,
    UINT nIDText,
    LPCRECT lpRectTool = NULL,
    UINT_PTR nIDTool = 0);

BOOL AddTool(
    CWnd* pWnd,
    LPCTSTR lpszText = LPSTR_TEXTCALLBACK,
    LPCRECT lpRectTool = NULL,
    UINT_PTR nIDTool = 0);

参数

pWnd
指向包含工具的窗口的指针。

nIDText
包含工具文本的字符串资源的 ID。

lpRectTool
指向 RECT 结构的指针,该结构包含工具边界矩形的坐标。 坐标相对于 pWnd 标识的窗口的工作区左上角。

nIDTool
工具的 ID。

lpszText
指向工具文本的指针。 如果此参数包含值 LPSTR_TEXTCALLBACK,则 TTN_NEEDTEXT 通知消息将转到 pWnd 指向的窗口的父级。

返回值

如果成功,则不为 0;否则为 0。

备注

lpRectToolnIDTool 参数必须都有效;如果 lpRectToolNULL,则 nIDTool 必须为 0。

一个工具提示控件可关联多个工具。 调用此函数向工具提示控件注册工具,以便当光标位于工具上时显示工具提示中存储的信息。

注意

无法使用 AddTool 将工具提示设置为静态控件。

示例

请参阅 CPropertySheet::GetTabControl 的示例。

CToolTipCtrl::AdjustRect

在工具提示控件的文本显示矩形与其窗口矩形之间转换。

BOOL AdjustRect(
    LPRECT lprc,
    BOOL bLarger = TRUE);

参数

lprc
指向 RECT 结构的指针,该结构包含工具提示窗口矩形或文本显示矩形。

bLarger
如果为 TRUE,则使用 lprc 来指定文本显示矩形,并接收相应的窗口矩形。 如果为 FALSE,则使用 lprc 来指定窗口矩形,并接收相应的文本显示矩形。

返回值

如果成功调整矩形,则为非零值;否则为 0。

备注

此成员函数根据其窗口矩形计算工具提示控件的文本显示矩形,或者计算呈现指定文本显示矩形所需的工具提示窗口矩形。

此成员函数实现 Win32 消息 TTM_ADJUSTRECT 的行为,如 Windows SDK 中所述。

CToolTipCtrl::Create

创建工具提示控件并将其附加到 CToolTipCtrl 对象。

virtual BOOL Create(CWnd* pParentWnd, DWORD dwStyle = 0);

参数

pParentWnd
指定工具提示控件的父窗口,通常为 CDialog。 不得为 NULL

dwStyle
指定工具提示控件的样式。 有关详细信息,请参阅备注部分。

返回值

如果已成功创建 CToolTipCtrl 对象,则为非零值;否则为 0。

备注

分两步构建 CToolTipCtrl。 首先调用构造函数以构造 CToolTipCtrl 对象,然后调用 Create 来创建工具提示控件,并将其附加到 CToolTipCtrl 对象。

dwStyle 参数可以是窗口样式的任意组合。 此外,工具提示控件还具有两个类特定的样式:TTS_ALWAYSTIPTTS_NOPREFIX

样式 含义
TTS_ALWAYSTIP 指定当光标位于工具上时,无论工具提示控件的所有者窗口处于活动状态还是非活动状态,都会显示工具提示。 如果不使用此样式,工具提示控件将在工具的所有者窗口处于活动状态时显示,当其处于非活动状态时则不显示。
TTS_NOPREFIX 此样式可防止系统从字符串中剥离与 (&) 字符。 如果工具提示控件没有 TTS_NOPREFIX 样式,系统会自动剥离与字符,让应用程序能够使用与菜单项和工具提示控件中的文本相同的字符串。

无论在创建控件时是否指定 WS_POPUPWS_EX_TOOLWINDOW 窗口样式,工具提示控件都具有这两个样式。

若要创建具有扩展窗口样式的工具提示控件,请调用 CToolTipCtrl::CreateEx 而不是 Create

示例

请参阅 CPropertySheet::GetTabControl 的示例。

CToolTipCtrl::CreateEx

创建一个控件(子窗口)并将其与 CToolTipCtrl 对象相关联。

virtual BOOL CreateEx(
    CWnd* pParentWnd,
    DWORD dwStyle = 0,
    DWORD dwStyleEx = 0);

参数

pParentWnd
指向作为控件父级的窗口的指针。

dwStyle
指定工具提示控件的样式。 有关详细信息,请参阅 Create 的“注解”部分。

dwStyleEx
指定要创建的控件的扩展样式。 有关扩展 Windows 样式的列表,请参阅 Windows SDK 中 CreateWindowExdwExStyle 参数。

返回值

如果成功,则不为 0,否则为 0。

备注

使用 CreateEx(而不是 Create)应用由 Windows 扩展样式前缀 WS_EX_ 指定的扩展 Windows 样式。

CToolTipCtrl::CToolTipCtrl

构造 CToolTipCtrl 对象。

CToolTipCtrl();

备注

构造对象后必须调用 Create

示例

// Declare a CToolTipCtrl object.
CToolTipCtrl m_ToolTipCtrl;

CToolTipCtrl::DelTool

从工具提示控件支持的工具集合中移除 pWndnIDTool 指定的工具。

void DelTool(
    CWnd* pWnd,
    UINT_PTR nIDTool = 0);

参数

pWnd
指向包含工具的窗口的指针。

nIDTool
工具的 ID。

CToolTipCtrl::GetBubbleSize

检索工具提示的大小。

CSize GetBubbleSize(LPTOOLINFO lpToolInfo) const;

参数

lpToolInfo
指向工具提示的 TOOLINFO 结构的指针。

返回值

工具提示的大小。

注解

此成员函数实现 Win32 消息 TTM_GETBUBBLESIZE 的行为,如 Windows SDK 中所述。

CToolTipCtrl::GetCurrentTool

检索当前工具提示控件显示的工具提示窗口的大小、位置和文本等信息。

BOOL GetCurrentTool(LPTOOLINFO lpToolInfo) const;

参数

lpToolInfo
[out] 指向 TOOLINFO 结构的指针,该结构接收当前工具提示窗口的相关信息。

返回值

如果成功检索到此信息,则为 TRUE;否则为 FALSE

备注

此方法将发送 TTM_GETCURRENTTOOL 消息,如 Windows SDK 中所述。

示例

下面的代码示例会检索当前工具提示窗口的相关信息。

{
    //Get information about the current tooltip. 
    TOOLINFO tInfo = {0};
    tInfo.cbSize = sizeof(TOOLINFO);
    CToolBarCtrl& m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
    CToolTipCtrl* m_toolTip = m_toolBarCtrl.GetToolTips();
    BOOL bRet = m_toolTip->GetCurrentTool( &tInfo );
}

CToolTipCtrl::GetDelayTime

检索当前为工具提示控件设置的初始持续时间、弹出持续时间和重新显示持续时间。

int GetDelayTime(DWORD dwDuration) const;

参数

dwDuration
指定将检索哪个持续时间值的标志。 此参数可能是以下值之一:

  • TTDT_AUTOPOP:检索当指针在工具边界矩形中静止时工具提示窗口保持可见的时长。

  • TTDT_INITIAL:检索在工具提示窗口显示之前,指针必须在工具边界矩形中保持静止的时长。

  • TTDT_RESHOW:检索当指针从一个工具移到另一个工具时显示后续工具提示窗口所需的时长。

返回值

指定的延迟时间(以毫秒为单位)

备注

此成员函数实现 Win32 消息 TTM_GETDELAYTIME 的行为,如 Windows SDK 中所述。

CToolTipCtrl::GetMargin

检索为工具提示窗口设置的上边距、下边距、左边距和右边距。

void GetMargin(LPRECT lprc) const;

参数

lprc
将接收边距信息的 RECT 结构的地址。 RECT 结构的成员不定义边界矩形。 就该消息而言,结构成员解释如下:

成员 表示形式
top 工具提示文本的上边框与顶部之间的距离(以像素为单位)。
left 提示文本的左边框与左侧底部之间的距离(以像素为单位)。
bottom 提示文本的下边框与底部之间的距离(以像素为单位)。
right 提示文本的右边框与右侧底部之间的距离(以像素为单位)。

备注

此成员函数实现 Win32 消息 TTM_GETMARGIN 的行为,如 Windows SDK 中所述。

CToolTipCtrl::GetMaxTipWidth

检索工具提示窗口的最大宽度。

int GetMaxTipWidth() const;

返回值

工具提示窗口的最大宽度。

备注

此成员函数实现 Win32 消息 TTM_GETMAXTIPWIDTH 的行为,如 Windows SDK 中所述。

CToolTipCtrl::GetText

检索工具提示控件为工具维护的文本。

void GetText(
    CString& str,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0) const;

参数

str
对接收工具文本的 CString 对象的引用。

pWnd
指向包含工具的窗口的指针。

nIDTool
工具的 ID。

注解

pWndnIDTool 参数标识该工具。 如果该工具先前已通过上一次调用 CToolTipCtrl::AddTool 注册到工具提示控件,则向 str 参数引用的对象分配工具的文本。

CToolTipCtrl::GetTipBkColor

检索工具提示窗口中的背景色。

COLORREF GetTipBkColor() const;

返回值

一个表示背景色的 COLORREF 值。

备注

此成员函数实现 Win32 消息 TTM_GETTIPBKCOLOR 的行为,如 Windows SDK 中所述。

CToolTipCtrl::GetTipTextColor

检索工具提示窗口中的文本颜色。

COLORREF GetTipTextColor() const;

返回值

表示文本颜色的 COLORREF 值。

备注

此成员函数实现 Win32 消息 TTM_GETTIPTEXTCOLOR 的行为,如 Windows SDK 中所述。

CToolTipCtrl::GetTitle

检索当前工具提示控件的标题。

void GetTitle(PTTGETTITLE pttgt) const;

参数

pttgt
[out] 指向 TTGETTITLE 结构的指针,该结构包含工具提示控件的相关信息。 此方法返回时,TTGETTITLE 结构的 pszTitle 成员指向标题的文本。

备注

此方法将发送 TTM_GETTITLE 消息,如 Windows SDK 中所述。

CToolTipCtrl::GetToolCount

检索向工具提示控件注册的工具计数。

int GetToolCount() const;

返回值

向工具提示控件注册的工具计数。

CToolTipCtrl::GetToolInfo

检索工具提示控件维护的工具相关信息。

BOOL GetToolInfo(
    CToolInfo& ToolInfo,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0) const;

参数

ToolInfo
对接收工具文本的 TOOLINFO 对象的引用。

pWnd
指向包含工具的窗口的指针。

nIDTool
工具的 ID。

返回值

如果成功,则不为 0;否则为 0。

注解

CToolInfo 引用的 TOOLINFO 结构的 hwnduId 成员可标识该工具。 如果该工具已通过上一次调用 AddTool 注册到工具提示控件,则 TOOLINFO 结构将填充该工具的相关信息。

CToolTipCtrl::HitTest

测试一个点来确定它是否位于给定工具的边界矩形中;如果是,则检索该工具的相关信息。

BOOL HitTest(
    CWnd* pWnd,
    CPoint pt,
    LPTOOLINFO lpToolInfo) const;

参数

pWnd
指向包含工具的窗口的指针。

pt
指向 CPoint 对象的指针,该对象包含要测试的点的坐标。

lpToolInfo
指向包含工具相关信息的 TOOLINFO 结构的指针。

返回值

如果命中测试信息指定的点位于工具边界矩形内,则为非零值;否则为 0。

备注

如果此函数返回非零值,则 lpToolInfo 指向的结构将填充点所在的矩形中的工具相关信息。

TTHITTESTINFO 结构的定义如下所示:

typedef struct _TT_HITTESTINFO { // tthti
    HWND hwnd;   // handle of tool or window with tool
    POINT pt;    // client coordinates of point to test
    TOOLINFO ti; // receives information about the tool
} TTHITTESTINFO, FAR * LPHITTESTINFO;
  • hwnd

    指定工具的句柄。

  • pt

    如果点位于工具的边界矩形中,则指定点的坐标。

  • ti

    工具的相关信息。 有关 TOOLINFO 结构的详细信息,请参阅 CToolTipCtrl::GetToolInfo

CToolTipCtrl::Pop

从视图中移除显示的工具提示窗口。

void Pop();

备注

此成员函数实现 Win32 消息 TTM_POP 的行为,如 Windows SDK 中所述。

导致当前工具提示控件显示在上一条鼠标消息的坐标处。

void Popup();

备注

此方法将发送 TTM_POPUP 消息,如 Windows SDK 中所述。

示例

下面的代码示例显示工具提示窗口。

{
   // Display the most recent tooltip.
   CToolBarCtrl &m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
   CToolTipCtrl *m_toolTip = m_toolBarCtrl.GetToolTips();
   m_toolTip->Popup();
}

CToolTipCtrl::RelayEvent

将鼠标消息传递给工具提示控件进行处理。

void RelayEvent(LPMSG lpMsg);

参数

lpMsg
指向 MSG 结构的指针,该结构包含要中继的消息。

备注

工具提示控件仅处理以下信息,这些信息由 RelayEvent 发送给它:

WM_LBUTTONDOWN WM_MOUSEMOVE
WM_LBUTTONUP WM_RBUTTONDOWN
WM_MBUTTONDOWN WM_RBUTTONUP
WM_MBUTTONUP

示例

请参阅 CPropertySheet::GetTabControl 的示例。

CToolTipCtrl::SetDelayTime

设置工具提示控件的延迟时间。

void SetDelayTime(UINT nDelay);

void SetDelayTime(
    DWORD dwDuration,
    int iTime);

参数

nDelay
指定新的延迟时间(以毫秒为单位)。

dwDuration
指定将检索哪个持续时间值的标志。 有关有效值的说明,请参阅 CToolTipCtrl::GetDelayTime

iTime
指定的延迟时间(以毫秒为单位)。

注解

延迟时间是在工具提示窗口显示之前,光标必须保留在工具上的时长。 默认延迟时间为 500 毫秒。

CToolTipCtrl::SetMargin

设置工具提示窗口的上边距、下边距、左边距和右边距。

void SetMargin(LPRECT lprc);

参数

lprc
RECT 结构的地址,该结构包含要设置的边距信息。 RECT 结构的成员不定义边界矩形。 有关边距信息的说明,请参阅 CToolTipCtrl::GetMargin

备注

此成员函数实现 Win32 消息 TTM_SETMARGIN 的行为,如 Windows SDK 中所述。

CToolTipCtrl::SetMaxTipWidth

设置工具提示窗口的最大宽度。

int SetMaxTipWidth(int iWidth);

参数

iWidth
要设置的最大工具提示窗口宽度。

返回值

上一个最大提示宽度。

备注

此成员函数实现 Win32 消息 TTM_SETMAXTIPWIDTH 的行为,如 Windows SDK 中所述。

CToolTipCtrl::SetTipBkColor

设置工具提示窗口中的背景色。

void SetTipBkColor(COLORREF clr);

参数

clr
新的背景色。

备注

此成员函数实现 Win32 消息 TTM_SETTIPBKCOLOR 的行为,如 Windows SDK 中所述。

CToolTipCtrl::SetTipTextColor

设置工具提示窗口中的文本颜色。

void SetTipTextColor(COLORREF clr);

参数

clr
新的文本颜色。

注解

此成员函数实现 Win32 消息 TTM_SETTIPTEXTCOLOR 的行为,如 Windows SDK 中所述。

CToolTipCtrl::SetTitle

向工具提示添加标准图标和标题字符串。

BOOL SetTitle(
    UINT uIcon,
    LPCTSTR lpstrTitle);

参数

uIcon
请参阅 Windows SDK 中 TTM_SETTITLE 中的 icon

lpstrTitle
指向标题字符串的指针。

返回值

如果成功,则不为 0;否则为 0。

备注

此成员函数实现 Win32 消息 TTM_SETTITLE 的行为,如 Windows SDK 中所述。

CToolTipCtrl::SetToolInfo

设置工具提示为工具维护的信息。

void SetToolInfo(LPTOOLINFO lpToolInfo);

参数

lpToolInfo
指向 TOOLINFO 结构的指针,该结构指定要设置的信息。

CToolTipCtrl::SetToolRect

设置工具的新边界矩形。

void SetToolRect(
    CWnd* pWnd,
    UINT_PTR nIDTool,
    LPCRECT lpRect);

参数

pWnd
指向包含工具的窗口的指针。

nIDTool
工具的 ID。

lpRect
指向 RECT 结构的指针,该结构指定新的边界矩形。

CToolTipCtrl::SetWindowTheme

设置工具提示窗口的视觉样式。

HRESULT SetWindowTheme(LPCWSTR pszSubAppName);

参数

pszSubAppName
指向 Unicode 字符串的指针,该字符串包含要设置的视觉样式。

返回值

不使用返回值。

备注

此成员函数模拟 TTM_SETWINDOWTHEME 消息的功能,如 Windows SDK 中所述。

CToolTipCtrl::Update

强制重新绘制当前工具。

void Update();

CToolTipCtrl::UpdateTipText

更新此控件工具的工具提示文本。

void UpdateTipText(
    LPCTSTR lpszText,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0);

void UpdateTipText(
    UINT nIDText,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0);

参数

lpszText
指向工具文本的指针。

pWnd
指向包含工具的窗口的指针。

nIDTool
工具的 ID。

nIDText
包含工具文本的字符串资源的 ID。

另请参阅

CWnd
层次结构图
CToolBar