CToolTipCtrl Class

Encapsulates the functionality of a "tooltip control," a small pop-up window that displays a single line of text describing the purpose of a tool in an application.

Syntax

class CToolTipCtrl : public CWnd

Members

Public Constructors

Name	Description
CToolTipCtrl::CToolTipCtrl	Constructs a CToolTipCtrl object.

Public Methods

Name	Description
CToolTipCtrl::Activate	Activates and deactivates the tooltip control.
CToolTipCtrl::AddTool	Registers a tool with the tooltip control.
CToolTipCtrl::AdjustRect	Converts between a tooltip control's text display rectangle and its window rectangle.
CToolTipCtrl::Create	Creates a tooltip control and attaches it to a CToolTipCtrl object.
CToolTipCtrl::CreateEx	Creates a tooltip control with the specified Windows extended styles and attaches it to a CToolTipCtrl object.
CToolTipCtrl::DelTool	Removes a tool from the tooltip control.
CToolTipCtrl::GetBubbleSize	Retrieves the size of the tooltip.
CToolTipCtrl::GetCurrentTool	Retrieves information, such as the size, position, and text, of the tooltip window that the current tooltip control displays.
CToolTipCtrl::GetDelayTime	Retrieves the initial, pop-up, and reshow durations that are currently set for a tooltip control.
CToolTipCtrl::GetMargin	Retrieves the top, left, bottom, and right margins that are set for a tooltip window.
CToolTipCtrl::GetMaxTipWidth	Retrieves the maximum width for a tooltip window.
CToolTipCtrl::GetText	Retrieves the text that a tooltip control maintains for a tool.
CToolTipCtrl::GetTipBkColor	Retrieves the background color in a tooltip window.
CToolTipCtrl::GetTipTextColor	Retrieves the text color in a tooltip window.
CToolTipCtrl::GetTitle	Retrieves the title of the current tooltip control.
CToolTipCtrl::GetToolCount	Retrieves a count of the tools maintained by a tooltip control.
CToolTipCtrl::GetToolInfo	Retrieves the information that a tooltip control maintains about a tool.
CToolTipCtrl::HitTest	Tests a point to determine whether it is within the bounding rectangle of the given tool. If so, retrieves information about the tool.
CToolTipCtrl::Pop	Removes a displayed tooltip window from view.
CToolTipCtrl::Popup	Causes the current tooltip control to display at the coordinates of the last mouse message.
CToolTipCtrl::RelayEvent	Passes a mouse message to a tooltip control for processing.
CToolTipCtrl::SetDelayTime	Sets the initial, pop-up, and reshow durations for a tooltip control.
CToolTipCtrl::SetMargin	Sets the top, left, bottom, and right margins for a tooltip window.
CToolTipCtrl::SetMaxTipWidth	Sets the maximum width for a tooltip window.
CToolTipCtrl::SetTipBkColor	Sets the background color in a tooltip window.
CToolTipCtrl::SetTipTextColor	Sets the text color in a tooltip window.
CToolTipCtrl::SetTitle	Adds a standard icon and title string to a tooltip.
CToolTipCtrl::SetToolInfo	Sets the information that a tooltip maintains for a tool.
CToolTipCtrl::SetToolRect	Sets a new bounding rectangle for a tool.
CToolTipCtrl::SetWindowTheme	Sets the visual style of the tooltip window.
CToolTipCtrl::Update	Forces the current tool to be redrawn.
CToolTipCtrl::UpdateTipText	Sets the tooltip text for a tool.

Remarks

A "tool" is either a window, such as a child window or control, or an application-defined rectangular area within a window's client area. A tooltip is hidden most of the time, appearing only when the user puts the cursor on a tool and leaves it there for approximately one-half second. The tooltip appears near the cursor and disappears when the user clicks a mouse button or moves the cursor off the tool.

CToolTipCtrl provides the functionality to control the initial time and duration of the tooltip, the margin widths surrounding the tooltip text, the width of the tooltip window itself, and the background and text color of the tooltip. A single tooltip control can provide information for more than one tool.

The CToolTipCtrl class provides the functionality of the Windows common tooltip control. This control (and therefore the CToolTipCtrl class) is available only to programs running under Windows 95/98 and Windows NT versions 3.51 and later.

For more information about enabling tooltips, see Tool Tips in Windows not Derived from CFrameWnd.

For more information on using CToolTipCtrl, see Controls and Using CToolTipCtrl.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CToolTipCtrl

Requirements

Header: afxcmn.h

CToolTipCtrl::Activate

Call this function to activate or deactivate a tooltip control.

void Activate(BOOL bActivate);

Parameters

bActivate
Specifies whether the tooltip control is to be activated or deactivated.

Remarks

If bActivate is TRUE, the control is activated; if FALSE, it is deactivated.

When a tooltip control is active, the tooltip information appears when the cursor is on a tool that is registered with the control; when it is inactive, the tooltip information does not appear, even when the cursor is on a tool.

Example

See the example for CPropertySheet::GetTabControl.

CToolTipCtrl::AddTool

Registers a tool with the tooltip control.

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);

Parameters

pWnd
Pointer to the window that contains the tool.

nIDText
ID of the string resource that contains the text for the tool.

lpRectTool
Pointer to a RECT structure containing coordinates of the tool's bounding rectangle. The coordinates are relative to the upper-left corner of the client area of the window identified by pWnd.

nIDTool
ID of the tool.

lpszText
Pointer to the text for the tool. If this parameter contains the value LPSTR_TEXTCALLBACK, TTN_NEEDTEXT notification messages go to the parent of the window that pWnd points to.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The lpRectTool and nIDTool parameters must both be valid, or if lpRectTool is NULL, nIDTool must be 0.

A tooltip control can be associated with more than one tool. Call this function to register a tool with the tooltip control, so that the information stored in the tooltip is displayed when the cursor is on the tool.

Example

See the example for CPropertySheet::GetTabControl.

CToolTipCtrl::AdjustRect

Converts between a tooltip control's text display rectangle and its window rectangle.

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

Parameters

lprc
Pointer to a RECT structure that holds either a tooltip window rectangle or a text display rectangle.

bLarger
If TRUE, lprc is used to specify a text-display rectangle, and it receives the corresponding window rectangle. If FALSE, lprc is used to specify a window rectangle, and it receives the corresponding text display rectangle.

Return Value

Nonzero if the rectangle is successfully adjusted; otherwise 0.

Remarks

This member function calculates a tooltip control's text display rectangle from its window rectangle, or the tooltip window rectangle needed to display a specified text display rectangle.

This member function implements the behavior of the Win32 message TTM_ADJUSTRECT, as described in the Windows SDK.

CToolTipCtrl::Create

Creates a tooltip control and attaches it to a CToolTipCtrl object.

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

Parameters

pParentWnd
Specifies the tooltip control's parent window, usually a CDialog. It must not be NULL.

dwStyle
Specifies the tooltip control's style. See the Remarks section for more information.

Return Value

Nonzero if the CToolTipCtrl object is successfully created; otherwise 0.

Remarks

You construct a CToolTipCtrl in two steps. First, call the constructor to construct the CToolTipCtrl object, and then call Create to create the tooltip control and attach it to the CToolTipCtrl object.

The dwStyle parameter can be any combination of Window Styles. In addition, a tooltip control has two class-specific styles: TTS_ALWAYSTIP and TTS_NOPREFIX.

Style	Meaning
TTS_ALWAYSTIP	Specifies that the tooltip will appear when the cursor is on a tool, regardless of whether the tooltip control's owner window is active or inactive. Without this style, the tooltip control appears when the tool's owner window is active, but not when it is inactive.
TTS_NOPREFIX	This style prevents the system from stripping the ampersand (&) character from a string. If a tooltip control does not have the TTS_NOPREFIX style, the system automatically strips ampersand characters, allowing an application to use the same string as both a menu item and as text in a tooltip control.

A tooltip control has the WS_POPUP and WS_EX_TOOLWINDOW window styles, regardless of whether you specify them when creating the control.

To create a tooltip control with extended windows styles, call CToolTipCtrl::CreateEx instead of Create.

Example

See the example for CPropertySheet::GetTabControl.

CToolTipCtrl::CreateEx

Creates a control (a child window) and associates it with the CToolTipCtrl object.

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

Parameters

pParentWnd
A pointer to the window that is the control's parent.

dwStyle
Specifies the tooltip control's style. See the Remarks section of Create for more information.

dwStyleEx
Specifies the extended style of the control being created. For a list of extended Windows styles, see the dwExStyle parameter for CreateWindowEx in the Windows SDK.

Return Value

Nonzero if successful otherwise 0.

Remarks

Use CreateEx instead of Create to apply extended Windows styles, specified by the Windows extended style preface WS_EX_.

CToolTipCtrl::CToolTipCtrl

Constructs a CToolTipCtrl object.

CToolTipCtrl();

Remarks

You must call Create after constructing the object.

Example

// Declare a CToolTipCtrl object.
CToolTipCtrl m_ToolTipCtrl;

CToolTipCtrl::DelTool

Removes the tool specified by pWnd and nIDTool from the collection of tools supported by a tooltip control.

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

Parameters

pWnd
Pointer to the window that contains the tool.

nIDTool
ID of the tool.

CToolTipCtrl::GetBubbleSize

Retrieves the size of the tooltip.

CSize GetBubbleSize(LPTOOLINFO lpToolInfo) const;

Parameters

lpToolInfo
A pointer to the tooltip's TOOLINFO structure.

Return Value

The size of the tooltip.

Remarks

This member function implements the behavior of the Win32 message TTM_GETBUBBLESIZE, as described in the Windows SDK.

CToolTipCtrl::GetCurrentTool

Retrieves information, such as the size, position, and text, of the tooltip window displayed by the current tooltip control.

BOOL GetCurrentTool(LPTOOLINFO lpToolInfo) const;

Parameters

lpToolInfo
[out] Pointer to a TOOLINFO structure that receives information about the current tooltip window.

Return Value

TRUE if the information is retrieved successfully; otherwise, FALSE.

Remarks

This method sends the TTM_GETCURRENTTOOL message, which is described in the Windows SDK.

Example

The following code example retrieves information about the current tooltip window.

{
    //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

Retrieves the initial, pop-up, and reshow durations currently set for a tooltip control.

int GetDelayTime(DWORD dwDuration) const;

Parameters

dwDuration
Flag that specifies which duration value will be retrieved. This parameter can be one of the following values:

• TTDT_AUTOPOP Retrieve the length of time the tooltip window remains visible if the pointer is stationary within a tool's bounding rectangle.

• TTDT_INITIAL Retrieve the length of time the pointer must remain stationary within a tool's bounding rectangle before the tooltip window appears.

• TTDT_RESHOW Retrieve the length of time it takes for subsequent tooltip windows to appear as the pointer moves from one tool to another.

Return Value

The specified delay time, in milliseconds

Remarks

This member function implements the behavior of the Win32 message TTM_GETDELAYTIME, as described in the Windows SDK.

CToolTipCtrl::GetMargin

Retrieves the top, left, bottom, and right margins set for a tooltip window.

void GetMargin(LPRECT lprc) const;

Parameters

lprc
Address of a RECT structure that will receive the margin information. The members of the RECT structure do not define a bounding rectangle. For the purpose of this message, the structure members are interpreted as follows:

Member	Representation
top	Distance between top border and top of tooltip text, in pixels.
left	Distance between left border and left end of tip text, in pixels.
bottom	Distance between bottom border and bottom of tip text, in pixels.
right	Distance between right border and right end of tip text, in pixels.

Remarks

This member function implements the behavior of the Win32 message TTM_GETMARGIN, as described in the Windows SDK.

CToolTipCtrl::GetMaxTipWidth

Retrieves the maximum width for a tooltip window.

int GetMaxTipWidth() const;

Return Value

The maximum width for a tooltip window.

Remarks

This member function implements the behavior of the Win32 message TTM_GETMAXTIPWIDTH, as described in the Windows SDK.

CToolTipCtrl::GetText

Retrieves the text that a tooltip control maintains for a tool.

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

Parameters

str
Reference to a CString object that receives the tool's text.

pWnd
Pointer to the window that contains the tool.

nIDTool
ID of the tool.

Remarks

The pWnd and nIDTool parameters identify the tool. If that tool has been previously registered with the tooltip control through a previous call to CToolTipCtrl::AddTool, the object referenced by the str parameter is assigned the tool's text.

CToolTipCtrl::GetTipBkColor

Retrieves the background color in a tooltip window.

COLORREF GetTipBkColor() const;

Return Value

A COLORREF value that represents the background color.

Remarks

This member function implements the behavior of the Win32 message TTM_GETTIPBKCOLOR, as described in the Windows SDK.

CToolTipCtrl::GetTipTextColor

Retrieves the text color in a tooltip window.

COLORREF GetTipTextColor() const;

Return Value

A COLORREF value that represents the text color.

Remarks

This member function implements the behavior of the Win32 message TTM_GETTIPTEXTCOLOR, as described in the Windows SDK.

CToolTipCtrl::GetTitle

Retrieves the title of the current tooltip control.

void GetTitle(PTTGETTITLE pttgt) const;

Parameters

pttgt
[out] Pointer to a TTGETTITLE structure that contains information about the tooltip control. When this method returns, the pszTitle member of the TTGETTITLE structure points to the text of the title.

Remarks

This method sends the TTM_GETTITLE message, which is described in the Windows SDK.

CToolTipCtrl::GetToolCount

Retrieves a count of the tools registered with the tooltip control.

int GetToolCount() const;

Return Value

A count of tools registered with the tooltip control.

CToolTipCtrl::GetToolInfo

Retrieves the information that a tooltip control maintains about a tool.

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

Parameters

ToolInfo
Reference to a TOOLINFO object that receives the tool's text.

pWnd
Pointer to the window that contains the tool.

nIDTool
ID of the tool.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The hwnd and uId members of the TOOLINFO structure referenced by CToolInfo identify the tool. If that tool has been registered with the tooltip control through a previous call to AddTool, the TOOLINFO structure is filled with information about the tool.

CToolTipCtrl::HitTest

Tests a point to determine whether it is within the bounding rectangle of the given tool and, if so, retrieve information about the tool.

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

Parameters

pWnd
Pointer to the window that contains the tool.

pt
Pointer to a CPoint object containing the coordinates of the point to be tested.

lpToolInfo
Pointer to TOOLINFO structure that contains information about the tool.

Return Value

Nonzero if the point specified by the hit-test information is within the tool's bounding rectangle; otherwise 0.

Remarks

If this function returns a nonzero value, the structure pointed to by lpToolInfo is filled with information on the tool within whose rectangle the point lies.

The TTHITTESTINFO structure is defined as follows:

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

  Specifies the tool's handle.

• pt

  Specifies the coordinates of a point if the point is in the tool's bounding rectangle.

• ti

  Information about the tool. For more information about the TOOLINFO structure, see CToolTipCtrl::GetToolInfo.

CToolTipCtrl::Pop

Removes a displayed tooltip window from the view.

void Pop();

Remarks

This member function implements the behavior of the Win32 message TTM_POP, as described in the Windows SDK.

CToolTipCtrl::Popup

Causes the current tooltip control to display at the coordinates of the last mouse message.

void Popup();

Remarks

This method sends the TTM_POPUP message, which is described in the Windows SDK.

Example

The following code example displays a tooltip window.

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

CToolTipCtrl::RelayEvent

Passes a mouse message to a tooltip control for processing.

void RelayEvent(LPMSG lpMsg);

Parameters

lpMsg
Pointer to a MSG structure that contains the message to relay.

Remarks

A tooltip control processes only the following messages, which are sent to it by RelayEvent:

WM_LBUTTONDOWN	WM_MOUSEMOVE
WM_LBUTTONUP	WM_RBUTTONDOWN
WM_MBUTTONDOWN	WM_RBUTTONUP
WM_MBUTTONUP

Example

See the example for CPropertySheet::GetTabControl.

CToolTipCtrl::SetDelayTime

Sets the delay time for a tooltip control.

void SetDelayTime(UINT nDelay);

void SetDelayTime(
    DWORD dwDuration,
    int iTime);

Parameters

nDelay
Specifies the new delay time, in milliseconds.

dwDuration
Flag that specifies which duration value will be retrieved. See CToolTipCtrl::GetDelayTime for a description of the valid values.

iTime
The specified delay time, in milliseconds.

Remarks

The delay time is the length of time the cursor must remain on a tool before the tooltip window appears. The default delay time is 500 milliseconds.

CToolTipCtrl::SetMargin

Sets the top, left, bottom, and right margins for a tooltip window.

void SetMargin(LPRECT lprc);

Parameters

lprc
Address of a RECT structure that contains the margin information to be set. The members of the RECT structure do not define a bounding rectangle. See CToolTipCtrl::GetMargin for a description of the margin information.

Remarks

This member function implements the behavior of the Win32 message TTM_SETMARGIN, as described in the Windows SDK.

CToolTipCtrl::SetMaxTipWidth

Sets the maximum width for a tooltip window.

int SetMaxTipWidth(int iWidth);

Parameters

iWidth
The maximum tooltip window width to be set.

Return Value

The previous maximum tip width.

Remarks

This member function implements the behavior of the Win32 message TTM_SETMAXTIPWIDTH, as described in the Windows SDK.

CToolTipCtrl::SetTipBkColor

Sets the background color in a tooltip window.

void SetTipBkColor(COLORREF clr);

Parameters

clr
The new background color.

Remarks

This member function implements the behavior of the Win32 message TTM_SETTIPBKCOLOR, as described in the Windows SDK.

CToolTipCtrl::SetTipTextColor

Sets the text color in a tooltip window.

void SetTipTextColor(COLORREF clr);

Parameters

clr
The new text color.

Remarks

This member function implements the behavior of the Win32 message TTM_SETTIPTEXTCOLOR, as described in the Windows SDK.

CToolTipCtrl::SetTitle

Adds a standard icon and title string to a tooltip.

BOOL SetTitle(
    UINT uIcon,
    LPCTSTR lpstrTitle);

Parameters

uIcon
See icon in TTM_SETTITLE in the Windows SDK.

lpstrTitle
Pointer to the title string.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message TTM_SETTITLE, as described in the Windows SDK.

CToolTipCtrl::SetToolInfo

Sets the information that a tooltip maintains for a tool.

void SetToolInfo(LPTOOLINFO lpToolInfo);

Parameters

lpToolInfo
A pointer to a TOOLINFO structure that specifies the information to set.

CToolTipCtrl::SetToolRect

Sets a new bounding rectangle for a tool.

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

Parameters

pWnd
Pointer to the window that contains the tool.

nIDTool
ID of the tool.

lpRect
Pointer to a RECT structure specifying the new bounding rectangle.

CToolTipCtrl::SetWindowTheme

Sets the visual style of the tooltip window.

HRESULT SetWindowTheme(LPCWSTR pszSubAppName);

Parameters

pszSubAppName
A pointer to a Unicode string that contains the visual style to set.

Return Value

The return value is not used.

Remarks

This member function emulates the functionality of the TTM_SETWINDOWTHEME message, as described in the Windows SDK.

CToolTipCtrl::Update

Forces the current tool to be redrawn.

void Update();

CToolTipCtrl::UpdateTipText

Updates the tooltip text for this control's tools.

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

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

Parameters

lpszText
Pointer to the text for the tool.

pWnd
Pointer to the window that contains the tool.

nIDTool
ID of the tool.

nIDText
ID of the string resource that contains the text for the tool.

See also

CWnd Class
Hierarchy Chart
CToolBar Class