CToolTipCtrl Class

Artigo
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CToolTipCtrl Class.

Encapsulates the functionality of a "tool tip 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 tool tip control.
CToolTipCtrl::AddTool	Registers a tool with the tool tip control.
CToolTipCtrl::AdjustRect	Converts between a tool tip control's text display rectangle and its window rectangle.
CToolTipCtrl::Create	Creates a tool tip control and attaches it to a `CToolTipCtrl` object.
CToolTipCtrl::CreateEx	Creates a tool tip control with the specified Windows extended styles and attaches it to a `CToolTipCtrl` object.
CToolTipCtrl::DelTool	Removes a tool from the tool tip control.
CToolTipCtrl::GetBubbleSize	Retrieves the size of the tool tip.
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 tool tip control.
CToolTipCtrl::GetMargin	Retrieves the top, left, bottom, and right margins that are set for a tool tip window.
CToolTipCtrl::GetMaxTipWidth	Retrieves the maximum width for a tool tip window.
CToolTipCtrl::GetText	Retrieves the text that a tool tip control maintains for a tool.
CToolTipCtrl::GetTipBkColor	Retrieves the background color in a tool tip window.
CToolTipCtrl::GetTipTextColor	Retrieves the text color in a tool tip window.
CToolTipCtrl::GetTitle	Retrieves the title of the current tooltip control.
CToolTipCtrl::GetToolCount	Retrieves a count of the tools maintained by a tool tip control.
CToolTipCtrl::GetToolInfo	Retrieves the information that a tool tip 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 tool tip 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 tool tip control for processing.
CToolTipCtrl::SetDelayTime	Sets the initial, pop-up, and reshow durations for a tool tip control.
CToolTipCtrl::SetMargin	Sets the top, left, bottom, and right margins for a tool tip window.
CToolTipCtrl::SetMaxTipWidth	Sets the maximum width for a tool tip window.
CToolTipCtrl::SetTipBkColor	Sets the background color in a tool tip window.
CToolTipCtrl::SetTipTextColor	Sets the text color in a tool tip window.
CToolTipCtrl::SetTitle	Adds a standard icon and title string to a tool tip.
CToolTipCtrl::SetToolInfo	Sets the information that a tool tip maintains for a tool.
CToolTipCtrl::SetToolRect	Sets a new bounding rectangle for a tool.
CToolTipCtrl::SetWindowTheme	Sets the visual style of the tool tip window.
CToolTipCtrl::Update	Forces the current tool to be redrawn.
CToolTipCtrl::UpdateTipText	Sets the tool tip 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 tool tip 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 tool tip 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 tool tip, the margin widths surrounding the tool tip text, the width of the tool tip window itself, and the background and text color of the tool tip. A single tool tip control can provide information for more than one tool.

The CToolTipCtrl class provides the functionality of the Windows common tool tip 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 tool tips, 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 tool tip control.

void Activate(BOOL bActivate);

Parameters

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

Remarks

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

When a tool tip control is active, the tool tip information appears when the cursor is on a tool that is registered with the control; when it is inactive, the tool tip 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 tool tip 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 tool tip control can be associated with more than one tool. Call this function to register a tool with the tool tip control, so that the information stored in the tool tip is displayed when the cursor is on the tool.

Note

You cannot set a tool tip to a static control using AddTool.

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 tool tip 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 tool tip control's text display rectangle from its window rectangle, or the tool tip 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 tool tip control and attaches it to a CToolTipCtrl object.

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

Parameters

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

dwStyle
Specifies the tool tip 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 tool tip control and attach it to the CToolTipCtrl object.

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

Style	Meaning
TTS_ALWAYSTIP	Specifies that the tool tip will appear when the cursor is on a tool, regardless of whether the tool tip control's owner window is active or inactive. Without this style, the tool tip 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 tool tip 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 tool tip control.

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

To create a tool tip 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 associate 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 tool tip 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 tool tip 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 tool tip.

CSize GetBubbleSize(LPTOOLINFO lpToolInfo) const;

Parameters

lpToolInfo
A pointer to the tool tip's TOOLINFO structure.

Return Value

The size of the tool tip.

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

Parameter	Description
[out] `lpToolInfo`	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 tool tip 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 tool tip 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 tool tip window appears.
TTDT_RESHOW Retrieve the length of time it takes for subsequent tool tip 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 tool tip 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 tool tip 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 tool tip window.

int GetMaxTipWidth() const;

Return Value

The maximum width for a tool tip 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 tool tip 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 tool tip 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 tool tip 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 tool tip 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

Parameter	Description
[out] `pttgt`	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 tool tip control.

int GetToolCount() const;

Return Value

A count of tools registered with the tool tip control.

CToolTipCtrl::GetToolInfo

Retrieves the information that a tool tip 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 tool tip 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 tool tip 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 tool tip control for processing.

void RelayEvent(LPMSG lpMsg);

Parameters

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

Remarks

A tool tip 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 tool tip 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 tool tip window appears. The default delay time is 500 milliseconds.

CToolTipCtrl::SetMargin

Sets the top, left, bottom, and right margins for a tool tip 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 tool tip window.

int SetMaxTipWidth(int iWidth);

Parameters

iWidth
The maximum tool tip 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 tool tip 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 tool tip 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 tool tip.

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 tool tip 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 tool tip 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 tool tip 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.

Compartilhar via

CToolTipCtrl Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CToolTipCtrl::Activate

Parameters

Remarks

Example

CToolTipCtrl::AddTool

Parameters

Return Value

Remarks

Example

CToolTipCtrl::AdjustRect

Parameters

Return Value

Remarks

CToolTipCtrl::Create

Parameters

Return Value

Remarks

Example

CToolTipCtrl::CreateEx

Parameters

Return Value

Remarks

CToolTipCtrl::CToolTipCtrl

Remarks

Example

CToolTipCtrl::DelTool

Parameters

CToolTipCtrl::GetBubbleSize

Parameters

Return Value

Remarks

CToolTipCtrl::GetCurrentTool

Parameters

Return Value

Remarks

Example

CToolTipCtrl::GetDelayTime

Parameters

Return Value

Remarks

CToolTipCtrl::GetMargin

Parameters

Remarks

CToolTipCtrl::GetMaxTipWidth

Return Value

Remarks

CToolTipCtrl::GetText

Parameters

Remarks

CToolTipCtrl::GetTipBkColor

Return Value

Remarks

CToolTipCtrl::GetTipTextColor

Return Value

Remarks

CToolTipCtrl::GetTitle

Parameters

Remarks

CToolTipCtrl::GetToolCount

Return Value

CToolTipCtrl::GetToolInfo

Parameters

Return Value

Remarks

CToolTipCtrl::HitTest

Parameters

Return Value

Remarks

CToolTipCtrl::Pop

Remarks

CToolTipCtrl::Popup