CToolTipCtrl
类
封装“工具提示控件”功能,此控件是一个小型弹出窗口,显示一行文本来说明应用程序中工具的用途。
语法
class CToolTipCtrl : public CWnd
成员
公共构造函数
名称 | 描述 |
---|---|
CToolTipCtrl::CToolTipCtrl |
构造 CToolTipCtrl 对象。 |
公共方法
注解
“工具”是一个窗口(如子窗口或控件)或窗口工作区中应用程序定义的矩形区域。 工具提示在大多数时间都是隐藏的,它仅在用户将光标置于工具上并在其上停留约半秒时间时显示。 工具提示显示在光标附近,并且在用户单击鼠标按钮或将光标移离工具时消失。
CToolTipCtrl
提供用于控制工具提示的初始时间和持续时间、工具提示文本周围的边距宽度、工具提示窗口本身的宽度以及工具提示的背景色和文本颜色的功能。 一个工具提示控件可以提供多个工具的信息。
CToolTipCtrl
类提供了 Windows 公共工具提示控件的功能。 此控件(因此决定 CToolTipCtrl
类)仅适用于在 Windows 95/98 和 Windows NT 版本 3.51 及更高版本下运行的程序。
若要详细了解如何启用工具提示,请参阅 Windows 中未派生自 CFrameWnd
的工具提示。
有关使用 CToolTipCtrl
的详细信息,请参阅控件和使用 CToolTipCtrl
。
继承层次结构
CToolTipCtrl
要求
标头:afxcmn.h
CToolTipCtrl::Activate
调用此函数以激活或停用工具提示控件。
void Activate(BOOL bActivate);
参数
bActivate
指定是激活还是停用工具提示控件。
备注
如果 bActivate
为 TRUE
,则激活控件;如果为 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。
备注
lpRectTool
和 nIDTool
参数必须都有效;如果 lpRectTool
为 NULL
,则 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_ALWAYSTIP
和 TTS_NOPREFIX
。
样式 | 含义 |
---|---|
TTS_ALWAYSTIP |
指定当光标位于工具上时,无论工具提示控件的所有者窗口处于活动状态还是非活动状态,都会显示工具提示。 如果不使用此样式,工具提示控件将在工具的所有者窗口处于活动状态时显示,当其处于非活动状态时则不显示。 |
TTS_NOPREFIX |
此样式可防止系统从字符串中剥离与 (& ) 字符。 如果工具提示控件没有 TTS_NOPREFIX 样式,系统会自动剥离与字符,让应用程序能够使用与菜单项和工具提示控件中的文本相同的字符串。 |
无论在创建控件时是否指定 WS_POPUP
和 WS_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 中 CreateWindowEx
的 dwExStyle
参数。
返回值
如果成功,则不为 0,否则为 0。
备注
使用 CreateEx
(而不是 Create
)应用由 Windows 扩展样式前缀 WS_EX_
指定的扩展 Windows 样式。
CToolTipCtrl::CToolTipCtrl
构造 CToolTipCtrl
对象。
CToolTipCtrl();
备注
构造对象后必须调用 Create
。
示例
// Declare a CToolTipCtrl object.
CToolTipCtrl m_ToolTipCtrl;
CToolTipCtrl::DelTool
从工具提示控件支持的工具集合中移除 pWnd
和 nIDTool
指定的工具。
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。
注解
pWnd
和 nIDTool
参数标识该工具。 如果该工具先前已通过上一次调用 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
结构的 hwnd
和 uId
成员可标识该工具。 如果该工具已通过上一次调用 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 中所述。
CToolTipCtrl::Popup
导致当前工具提示控件显示在上一条鼠标消息的坐标处。
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。