Tooltip Controls

Tooltip Controls


A tooltip control is a small pop-up window that displays a single line of text that describes the purpose of a tool in an application. 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.

arrowy.gifAbout Tooltip Controls

arrowy.gifUsing Tooltip Controls

arrowy.gifTooltip Control Update in Internet Explorer

arrowy.gifTooltip Control Reference

About Tooltip Controls

A tooltip control 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 control appears near the cursor and disappears when the user clicks a mouse button or moves the cursor off of the tool. A single tooltip control can support any number of tools. The following illustration shows a tooltip control associated with a button in a toolbar control.

Tooltip control for a button in a toolbar control.

Tooltip Creation

You create a tooltip control by using the CreateWindowEx function, specifying the TOOLTIPS_CLASS window class. The class is registered when the common control dynamic-link library (DLL) is loaded. To ensure that this DLL is loaded, include the InitCommonControls function in your application.

The window procedure for a tooltip control automatically sets the size, position, and visibility of the tooltip control. The height of the tooltip window is based on the height of the font currently selected into the device context for the tooltip control. The width varies based on the length of the string currently in the tooltip window.

Activation

A tooltip control itself can be either active or inactive. When it is active, the tooltip control appears when the cursor is on a tool. When it is inactive, the tooltip control does not appear, even if the cursor is on a tool. The TTM_ACTIVATE message activates and deactivates a tooltip control.

Types of Tools

A tooltip control can support any number of tools. To support a particular tool, you must register the tool with the tooltip control by sending the control the TTM_ADDTOOL message. The message includes the address of a TOOLINFO structure, which provides information the tooltip control needs to display text for the tool. The cbSize member is required and must specify the size of the structure.

A tooltip control supports tools implemented as windows (such as child windows or control windows) and as rectangular areas within a window's client area. When you add a tool implemented as a rectangular area, the hwnd member of TOOLINFO must specify the handle to the window that contains the area, and the rect member must specify the client coordinates of the area's bounding rectangle. In addition, the uId member must specify the application-defined identifier for the tool.

When you add a tool implemented as a window, the uId member of TOOLINFO must contain the window handle to the tool. Also, the uFlags member must specify the TTF_IDISHWND value, which tells the tooltip control to interpret the uId member as a window handle.

Tool Text

When you add a tool to a tooltip control, the lpszText member of the TOOLINFO structure must specify the address of the string to display for the tool. You can change the text any time after adding the tool by using the TTM_UPDATETIPTEXT message.

If the high-order word of lpszText is zero, the low-order word must be the identifier of a string resource. When the tooltip control needs the text, the system loads the specified string resource from the application instance identified by the hinst member of TOOLINFO.

If you specify the LPSTR_TEXTCALLBACK value in the lpszText member, the tooltip control notifies the window specified in the hwnd member of TOOLINFO whenever the tooltip control needs to display text for the tool. The tooltip control sends the TTN_NEEDTEXT notification message to the window. The message includes the address of a TOOLTIPTEXT structure, which contains the window handle as well as the application-defined identifier for the tool. The window examines the structure to determine the tool for which text is needed, and it fills the appropriate structure members with information that the tooltip control needs to display the string.

Many applications create toolbars containing tools that correspond to menu commands. For such tools, it is convenient for the tooltip control to display the same text as the corresponding menu item. The system automatically strips the ampersand (&) accelerator characters from all strings passed to a tooltip control, unless the control has the TTS_NOPREFIX style.

To retrieve the text for a tool, use the TTM_GETTEXT message.

Relaying Mouse Messages to the Tooltip

A tooltip control needs to receive mouse messages to determine when to display the tooltip window. Because Microsoft® Windows® sends mouse messages only to the window that contains the cursor, you must use the TTM_RELAYEVENT message to relay mouse messages to the tooltip control.

If a tool is implemented as a rectangular area in an application-defined window, the window procedure receives mouse messages and can relay them to the tooltip control. However, if a tool is implemented as a system-defined window, the mouse messages are sent to the window and are not readily available to the application. You must use a message hook to access and relay the mouse messages, or you must subclass the window.

When a tooltip control receives a relayed WM_MOUSEMOVE message, it determines whether the cursor is in the bounding rectangle of a tool. If the cursor is there, the tooltip control sets a timer. At the end of the time-out duration, the tooltip control checks the position of the cursor to see whether it has moved. If it hasn't, the tooltip control retrieves the text for the tool, copies the text into the tooltip window, and shows the window. The tooltip control continues to show the window until it receives a relayed button-up or button-down message or until a relayed WM_MOUSEMOVE message indicates that the cursor has moved outside the bounding rectangle of the tool.

A tooltip control actually has three time-out durations associated with it. The initial duration is the length of time that the cursor must remain stationary within the bounding rectangle of a tool before the tooltip window is displayed. The reshow duration is the length of the delay before subsequent tooltip windows are displayed when the cursor moves from one tool to another. The pop-up duration is the length of time that the tooltip window remains displayed before it is hidden. That is, if the cursor remains stationary within the bounding rectangle after the tooltip window is displayed, the tooltip window is automatically hidden at the end of the pop-up duration. You can adjust all of the time-out durations by using the TTM_SETDELAYTIME message.

If an application includes a tool implemented as a rectangular area and the size or position of the control changes, it can use the TTM_NEWTOOLRECT message to report the change to the tooltip control. An application does not need to report size and position changes for a tool implemented as a window. This is because the tooltip control uses the window handle of a tool to determine if the cursor is on the tool, not the tool's bounding rectangle.

When it is about to be displayed, a tooltip control sends the TTN_SHOW notification to the owner window. A tooltip control sends the TTN_POP notification when it is about to be hidden. Each notification is sent in the context of a WM_NOTIFY message.

Tooltip Hit Testing

The TTM_HITTEST message allows you to retrieve information that a tooltip control maintains about the tool occupying a particular point. The message includes a TTHITTESTINFO structure that contains a window handle, the coordinates of a point, and the address of a TOOLINFO structure. The tooltip control determines whether a tool occupies the point and, if it does, fills TOOLINFO with information about the tool.

Miscellaneous Messages

The TTM_GETCURRENTTOOL and TTM_GETTOOLINFO messages fill a TOOLINFO structure with information about a tool that has been registered with a tooltip control. The TTM_SETTOOLINFO message allows you to change the information that a tooltip control maintains for a particular tool. The TTM_DELTOOL message deletes a tool from a tooltip control.

Default Tooltip Control Message Processing

This section describes the messages handled by the window procedure for the TOOLTIPS_CLASS window class.
Message Default processing
WM_CREATE Ensures that the tooltip control has the WS_EX_TOOLWINDOW and WS_POPUP window styles. It also allocates memory and initializes internal variables.
WM_DESTROY Frees resources allocated for the tooltip control.
WM_GETFONT Returns the handle of the font that the tooltip control will use to draw text.
WM_MOUSEMOVE Hides the tooltip window.
WM_PAINT Draws the tooltip window.
WM_SETFONT Sets the handle of the font that the tooltip control will use to draw text.
WM_TIMER Hides the tooltip window if the tool has changed position or if the cursor has moved outside the tool. Otherwise, it shows the tooltip window.
WM_WININICHANGE Resets internal variables that are based on system metrics.

Using Tooltip Controls

This section provides examples that demonstrate how to create a tooltip control and use a tooltip control with a dialog box.

Creating a Tooltip Control

The following example demonstrates how to create a tooltip control and add several tools to it. The example creates a grid of rectangles in the client area of a window and then uses the TTM_ADDTOOL message to add each rectangle to the tooltip control. Note that the window procedure for the owner of the tooltip control must handle mouse messages and pass them on to the tooltip control by using the TTM_RELAYEVENT message.

	// DoCreateTooltip - creates a tooltip control and adds some tools 
	//     to it. 
	// Returns the handle of the tooltip control if successful, or NULL
	//     otherwise. 
	// hwndOwner - handle of the owner window. 
	// 
	// Global variable 
	//     g_hinst - handle of the application instance. 
	extern HINSTANCE g_hinst; 
 
	HWND DoCreateTooltip(HWND hwndOwner) 
	{ 
    HWND hwndTT;    // handle of tooltip 
    int row, col;   // rows and columns 
    TOOLINFO ti;    // tool information 
    int id = 0;     // offset to string identifiers 
    static char *szTips[NUM_TIPS] =   // tip text 
    { 
    "Cut", "Copy", "Paste", "Undo", "Open", "Save" 
    }; 
 
    // Ensure that the common control DLL is loaded, and create 
    // a tooltip control. 
    InitCommonControls(); 
 
    hwndTT = CreateWindow(TOOLTIPS_CLASS, (LPSTR) NULL, TTS_ALWAYSTIP, 
        CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, 
        NULL, (HMENU) NULL, g_hinst, NULL); 
 
    if (hwndTT == (HWND) NULL) 
        return (HWND) NULL; 
 
    // Divide the client area into a grid of rectangles, and add each 
    // rectangle to the tooltip. 
    for (row = 0; row < MAX_ROWS ; row++ ) 
        for (col = 0; col < MAX_COLS; col++) { 
            ti.cbSize = sizeof(TOOLINFO); 
            ti.uFlags = 0; 
            ti.hwnd = hwndOwner; 
            ti.hinst = g_hinst; 
            ti.uId = (UINT) id; 
            ti.lpszText = (LPSTR) szTips[id++]; 
            ti.rect.left = col * CX_COLUMN; 
            ti.rect.top = row * CY_ROW; 
            ti.rect.right = ti.rect.left + CX_COLUMN; 
            ti.rect.bottom = ti.rect.top + CY_ROW; 
 
            if (!SendMessage(hwndTT, TTM_ADDTOOL, 0, 
                    (LPARAM) (LPTOOLINFO) &ti)) 
                return NULL; 
        } 
 
    return hwndTT; 
	} 
 

Using a Tooltip Control with a Dialog Box

The following example includes a set of application-defined functions that implement a tooltip control for a dialog box. The DoCreateDialogTooltip function creates a tooltip control and uses the EnumChildWindows function to enumerate the controls in the dialog box. The enumeration procedure, EnumChildProc, registers each control with the tooltip control. The procedure specifies the dialog box as the parent window of each tooltip control and includes the LPSTR_TEXTCALLBACK value for each tooltip control. As a result, the dialog box receives a WM_NOTIFY message that contains the TTN_NEEDTEXT notification message whenever the tooltip control needs the text for a control. The dialog box procedure calls the OnWMNotify function to process the TTN_NEEDTEXT notifications. OnWMNotify provides the appropriate string based on the identifier of the tooltip control.

The tooltip control needs to receive mouse messages that the system sends to the control windows. To access the messages, the DoCreateDialogTooltip function installs a hook procedure of the WH_GETMESSAGE type. The hook procedure, GetMsgProc, monitors the message stream for mouse messages intended for one of the control windows and relays the messages to the tooltip control.

	// DoCreateDialogTooltip - creates a tooltip control for a dialog box, 
	//     enumerates the child control windows, and installs a hook 
	//     procedure to monitor the message stream for mouse messages posted 
	//     to the control windows. 
	// Returns TRUE if successful, or FALSE otherwise. 
	// 
	// Global variables 
	// g_hinst - handle to the application instance. 
	// g_hwndTT - handle to the tooltip control. 
	// g_hwndDlg - handle to the dialog box. 
	// g_hhk - handle to the hook procedure. 
 
	BOOL DoCreateDialogTooltip(void) 
	{ 
 
    // Ensure that the common control DLL is loaded, and create 
    // a tooltip control. 
    InitCommonControls(); 
    g_hwndTT = CreateWindowEx(0, TOOLTIPS_CLASS, (LPSTR) NULL, 
        TTS_ALWAYSTIP, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, 
        CW_USEDEFAULT, g_hwndDlg, (HMENU) NULL, g_hinst, NULL); 
 
    if (g_hwndTT == NULL) 
        return FALSE; 
 
    // Enumerate the child windows to register them with the tooltip
    // control. 
    if (!EnumChildWindows(g_hwndDlg, (WNDENUMPROC) EnumChildProc, 0)) 
        return FALSE; 
 
    // Install a hook procedure to monitor the message stream for mouse 
    // messages intended for the controls in the dialog box. 
    g_hhk = SetWindowsHookEx(WH_GETMESSAGE, GetMsgProc, 
        (HINSTANCE) NULL, GetCurrentThreadId()); 
 
    if (g_hhk == (HHOOK) NULL) 
        return FALSE; 
 
    return TRUE; 
	} 
 
	// EmumChildProc - registers control windows with a tooltip control by
	//     using the TTM_ADDTOOL message to pass the address of a 
	//     TOOLINFO structure. 
	// Returns TRUE if successful, or FALSE otherwise. 
	// hwndCtrl - handle of a control window. 
	// lParam - application-defined value (not used). 
	BOOL EnumChildProc(HWND hwndCtrl, LPARAM lParam) 
	{ 
    TOOLINFO ti; 
    char szClass[64]; 
 
    // Skip static controls. 
    GetClassName(hwndCtrl, szClass, sizeof(szClass)); 
    if (lstrcmp(szClass, "STATIC") { 
        ti.cbSize = sizeof(TOOLINFO); 
        ti.uFlags = TTF_IDISHWND; 
        ti.hwnd = g_hwndDlg; 
        ti.uId = (UINT) hwndCtrl; 
        ti.hinst = 0; 
        ti.lpszText = LPSTR_TEXTCALLBACK; 
        SendMessage(g_hwndTT, TTM_ADDTOOL, 0, 
            (LPARAM) (LPTOOLINFO) &ti); 
    } 
    return TRUE; 
	} 
 
	// GetMsgProc - monitors the message stream for mouse messages intended 
	//     for a control window in the dialog box. 
	// Returns a message-dependent value. 
	// nCode - hook code. 
	// wParam - message flag (not used). 
	// lParam - address of an MSG structure. 
	LRESULT CALLBACK GetMsgProc(int nCode, WPARAM wParam, LPARAM lParam) 
	{ 
    MSG *lpmsg; 
 
    lpmsg = (MSG *) lParam; 
    if (nCode < 0 || !(IsChild(g_hwndDlg, lpmsg->hwnd))) 
        return (CallNextHookEx(g_hhk, nCode, wParam, lParam)); 
 
    switch (lpmsg->message) { 
        case WM_MOUSEMOVE: 
        case WM_LBUTTONDOWN: 
        case WM_LBUTTONUP: 
        case WM_RBUTTONDOWN: 
        case WM_RBUTTONUP: 
            if (g_hwndTT != NULL) { 
                MSG msg; 
 
                msg.lParam = lpmsg->lParam; 
                msg.wParam = lpmsg->wParam; 
                msg.message = lpmsg->message; 
                msg.hwnd = hwnd; 
                SendMessage(g_hwndTT, TTM_RELAYEVENT, 0, 
                    (LPARAM) (LPMSG) &msg); 
            } 
            break; 
        default: 
            break; 
    } 
    return (CallNextHookEx(g_hhk, nCode, wParam, lParam)); 
	} 
 
	// OnWMNotify - provides the tooltip control with the appropriate text 
	//     to display for a control window. This function is called by 
	//     the dialog box procedure in response to a WM_NOTIFY message. 
	// lParam - second message parameter of the WM_NOTIFY message. 
	VOID OnWMNotify(LPARAM lParam) 
	{ 
    LPTOOLTIPTEXT lpttt; 
    int idCtrl; 
 
    if ((((LPNMHDR) lParam)->code) == TTN_NEEDTEXT) { 
        idCtrl = GetDlgCtrlID((HWND) ((LPNMHDR) lParam)->idFrom); 
        lpttt = (LPTOOLTIPTEXT) lParam; 
 
        switch (idCtrl) { 
            case ID_HORZSCROLL: 
                lpttt->lpszText = "A horizontal scroll bar."; 
                return; 
 
            case ID_CHECK: 
                lpttt->lpszText = "A check box."; 
                return; 
 
            case ID_EDIT: 
                lpttt->lpszText = "An edit control."; 
                return; 
        } 
    } 
	return; 
	} 
 

Tooltip Control Update in Internet Explorer

Tooltip controls in Microsoft® Internet Explorer support a new feature called a tracking tooltip.

Tracking Tooltips

Tooltip controls support tracking tooltips, which are tooltip windows that you can dynamically position on the screen. By rapidly updating the position, the tooltip window appears to move smoothly, or "track." This functionality can be useful if you need tooltip text to follow the position of the pointer as it moves.

To create a tracking tooltip, use the TTM_ADDTOOL message, including the TTF_TRACK flag in the uFlags member of the accompanying TOOLINFO structure.

Your application must manually activate and deactivate a tracking tooltip using the TTM_TRACKACTIVATE message. While your tooltip is active, your application must supply the location at which the tooltip window will appear by using the TTM_TRACKPOSITION message. Tracking tooltip controls do not support the TTF_SUBCLASS style, so all mouse events must be forwarded from the parent to the child using TTM_RELAYEVENT messages.

The TTM_TRACKPOSITION message causes the tooltip control to display the window using one of two placement styles:

For more information and implementation details, see Creating Tracking Tooltips and Supporting Tracking Tooltips.

Creating Tracking Tooltips

The following example demonstrates how to create a tooltip control and assign a tool to it. The example specifies the main window's entire client area as the tool, but you could specify distinct portions of the client area or specify a different window altogether.

The example uses the TTM_ADDTOOL message to add the tool to the tooltip control. Tracking tooltips do not support the TTF_SUBCLASS flag, so the control's owner must manually forward pertinent messages (like WM_MOUSEMOVE) by using TTM_RELAYEVENT.

Additionally, the uFlags member of the TOOLINFO structure used in the example includes the TTF_ABSOLUTE flag. This flag causes the tooltip control to display tooltip text at the exact coordinates the application provides when it sends the TTM_TRACKPOSITION message. Without the TTF_ABSOLUTE flag, the tooltip control will choose a location to display the tooltip text based on the coordinates you provide. This causes tooltip text to appear next to the corresponding tool but not necessarily at the exact coordinates the application provided.

For additional information on using the TTM_TRACKPOSITION message, see Supporting Tracking Tooltips.

HWND WINAPI CreateTT(HWND hwndOwner)
{
    INITCOMMONCONTROLSEX icex;
    HWND        hwndTT;
    TOOLINFO    ti;

    // Load the tooltips class from the DLL.
    icex.dwSize = sizeof(icex);
    icex.dwICC  = ICC_BAR_CLASSES;

    if(!InitCommonControlsEx(&icex))
       return NULL;

    // Create the tooltip control.
    hwndTT = CreateWindow(TOOLTIPS_CLASS, TEXT(""),
                          WS_POPUP,
                          CW_USEDEFAULT, CW_USEDEFAULT,
                          CW_USEDEFAULT, CW_USEDEFAULT,
                          NULL, (HMENU)NULL, g_hinst,
                          NULL);

    // Prep the TOOLINFO structure to be used for a tracking tooltip.
    ti.cbSize = sizeof(TOOLINFO);
    ti.uFlags = TTF_IDISHWND | TTF_TRACK | TTF_ABSOLUTE;
    ti.hwnd   = hwndOwner;
    ti.uId    = (UINT)g_hwndMain;
    ti.hinst  = g_hinst;
    ti.lpszText  = LPSTR_TEXTCALLBACK;
    ti.rect.left = ti.rect.top = ti.rect.bottom = ti.rect.right = 0; 
    
    // Add the tool to the control, displaying an error if needed.
    if(!SendMessage(hwndTT,TTM_ADDTOOL,0,(LPARAM)&ti)){
        MessageBox(hwndOwner,"Couldn't create the tooltip control.","Error",MB_OK);
        return NULL;
    }
    
    // Activate (display) the tracking tooltip.  Then, set a global
    // flag value to indicate that the tooltip is active, so other
    // functions can check to see if it's visible.
    SendMessage(hwndTT,TTM_TRACKACTIVATE,(WPARAM)TRUE,(LPARAM)&ti);
    g_bIsVisible = TRUE;

    return(hwndTT);    
}
Supporting Tracking Tooltips

The following example is a simple window process function that supports tracking tooltips. It requests the current position of the pointer using the GetCursorPos function and then adds 15 pixels to the x- and y-coordinates so the tooltip appears slightly below and to the right of the pointer.

Note that the example relies on the value of a global variable, g_bIsVisible, to determine whether the application should send the TTM_TRACKPOSITION message. For the purpose of this example, g_bIsVisible is a BOOL variable that another function sets to TRUE upon sending the TTM_TRACKACTIVATE message to activate the tooltip. This way, if the tooltip is inactive, the additional overhead to calculate and send a message is not incurred.

LRESULT CALLBACK WndProc (HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
    HDC   hdc;
    PAINTSTRUCT ps;
    MSG   mssg;
    POINT pt;

    switch(msg){
        case WM_MOUSEMOVE:
            if(g_bIsVisible){
                mssg.hwnd    = g_hwndMain;
                mssg.message = msg;
                mssg.wParam  = wParam;
                mssg.lParam  = lParam;

                GetCursorPos(&pt);
                mssg.pt.x    = pt.x;
                mssg.pt.y    = pt.y;

#define X_OFFSET 15
#define Y_OFFSET X_OFFSET
                SendMessage(g_hwndTT,
                            TTM_TRACKPOSITION,0,
                            (LPARAM)MAKELPARAM(pt.x+X_OFFSET,
                            pt.y+Y_OFFSET));
            }
            break;

/*
 *
 *  Other standard window messages can be handled here.
 *
 */
    }
    return 0;
}

Tooltip Control Reference

This section contains information about the following programming elements used with tooltip controls.

Tooltip Styles

Messages
TTM_ACTIVATE
TTM_ADDTOOL
TTM_DELTOOL
TTM_ENUMTOOLS
TTM_GETCURRENTTOOL
TTM_GETDELAYTIME
TTM_GETMARGIN
TTM_GETMAXTIPWIDTH
TTM_GETTEXT
TTM_GETTIPBKCOLOR
TTM_GETTIPTEXTCOLOR
TTM_GETTOOLCOUNT
TTM_GETTOOLINFO
TTM_HITTEST
TTM_NEWTOOLRECT
TTM_POP
TTM_RELAYEVENT
TTM_SETDELAYTIME
TTM_SETMARGIN
TTM_SETMAXTIPWIDTH
TTM_SETTIPBKCOLOR
TTM_SETTIPTEXTCOLOR
TTM_SETTOOLINFO
TTM_TRACKACTIVATE
TTM_TRACKPOSITION
TTM_UPDATE
TTM_UPDATETIPTEXT
TTM_WINDOWFROMPOINT

Notifications
NM_CUSTOMDRAW (tooltip)
TTN_GETDISPINFO
TTN_NEEDTEXT
TTN_POP
TTN_SHOW

Structures
NMTTCUSTOMDRAW
NMTTDISPINFO
TOOLINFO
TOOLTIPTEXT
TTHITTESTINFO

Tooltip Styles

Tooltip controls support a variety of control styles in addition to standard window styles. A tooltip control always has the WS_POPUP and WS_EX_TOOLWINDOW window styles, regardless of whether you specify them when creating the control.
TTS_ALWAYSTIP The tooltip appears when the cursor is on a tool, even if the tooltip control's owner window is inactive. Without this style, the tooltip control appears only when the tool's owner window is active.
TTS_NOPREFIX Prevents the system from stripping the ampersand (&) character from a string. Without this style, the system automatically strips ampersand characters. This allows an application to use the same string as both a menu item and as text in a tooltip control.

Tooltip Control Messages

This section contains information about the messages used with tooltip controls.

TTM_ACTIVATE
TTM_ACTIVATE 
    wParam = (WPARAM) (BOOL) fActivate; 
    lParam = 0; 

Activates or deactivates a tooltip control.

fActivate
Activation flag. If this parameter is TRUE, the tooltip control is activated. If it is FALSE, the tooltip control is deactivated.
TTM_ADDTOOL
TTM_ADDTOOL 
    wParam = 0; 
    lParam = (LPARAM) (LPTOOLINFO) lpti; 

Registers a tool with a tooltip control.

lpti
Address of a TOOLINFO structure containing information that the tooltip control needs to display text for the tool. The cbSize member of this structure must be filled in before sending this message.
TTM_DELTOOL
TTM_DELTOOL 
    wParam = 0; 
    lParam = (LPARAM) (LPTOOLINFO) lpti; 

Removes a tool from a tooltip control.

lpti
Address of a TOOLINFO structure. The hwnd and uId members identify the tool to remove, and the cbSize member must specify the size of the structure. All other members are ignored.
TTM_ENUMTOOLS
TTM_ENUMTOOLS 
    wParam = (WPARAM) (UINT) iTool; 
    lParam = (LPARAM) (LPTOOLINFO) lpti; 

Retrieves the information that a tooltip control maintains about the current tool—that is, the tool for which the tooltip is currently displaying text.

iTool
Zero-based index of the tool for which to retrieve information.
lpti
Address of a TOOLINFO structure that receives information about the tool. Before sending this message, the cbSize member must specify the size of the structure.
TTM_GETCURRENTTOOL
TTM_GETCURRENTTOOL 
    wParam = 0;
    lParam = (LPARAM)(LPTOOLINFO) lpti;

Retrieves the information for the current tool in a tooltip control.

lpti
Address of a TOOLINFO structure that receives information about the current tool. If this value is NULL, the return value indicates the existence of the current tool without actually retrieving the tool information. If this value is not NULL, the cbSize member of the TOOLINFO structure must be filled in before sending this message.
TTM_GETDELAYTIME
TTM_GETDELAYTIME
    wParam = (DWORD) dwDuration;
    lParam = 0;

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

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.

Version 4.70.

See also TTM_SETDELAYTIME

TTM_GETMARGIN
TTM_GETMARGIN
    wParam = 0;
    lParam = (LPARAM)(LPRECT) lprc;

Retrieves the top, left, bottom, and right margins set for a tooltip window. A margin is the distance, in pixels, between the tooltip window border and the text contained within the tooltip window.

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:
top Distance between top border and top of tooltip text, in pixels.
left Distance between left border and left end of tooltip text, in pixels.
bottom Distance between bottom border and bottom of tooltip text, in pixels.
right Distance between right border and right end of tooltip text, in pixels.

All four margins default to zero when you create the tooltip control.

Version 4.70.

See also TTM_SETMARGIN

TTM_GETMAXTIPWIDTH
TTM_GETMAXTIPWIDTH
    wParam = 0;
    lParam = 0;

Retrieves the maximum width for a tooltip window.

The maximum tooltip width value does not indicate a tooltip window's actual width. Rather, if a tooltip string exceeds the maximum width, the control breaks the text into multiple lines, using spaces to determine line breaks. If the text cannot be segmented into multiple lines, it will be displayed on a single line. The length of this line may exceed the maximum tooltip width.

Version 4.70.

See also TTM_SETMAXTIPWIDTH

TTM_GETTEXT
TTM_GETTEXT 
    wParam = 0; 
    lParam = (LPARAM) (LPTOOLINFO) lpti; 

Retrieves the information a tooltip control maintains about a tool.

lpti
Address of a TOOLINFO structure.
The cbSize member of this structure must be filled in before sending this message. Set the hwnd and uId members to identify the tool for which to retrieve information. Set the lpszText member to point to a buffer that receives the text. There currently is no way to specify the size of the buffer or to determine the required buffer size.
TTM_GETTIPBKCOLOR
TTM_GETTIPBKCOLOR
    wParam = 0;
    lParam = 0;

Retrieves the background color in a tooltip window.

Version 4.70.

See also TTM_SETTIPBKCOLOR

TTM_GETTIPTEXTCOLOR
TTM_GETTIPTEXTCOLOR
    wParam = 0;
    lParam = 0;

Retrieves the text color in a tooltip window.

Version 4.70.

See also TTM_SETTIPTEXTCOLOR

TTM_GETTOOLCOUNT
TTM_GETTOOLCOUNT 
    wParam = 0; 
    lParam = 0; 

Retrieves a count of the tools maintained by a tooltip control.

TTM_GETTOOLINFO
TTM_GETTOOLINFO 
    wParam = 0; 
    lParam = (LPARAM) (LPTOOLINFO) lpti; 

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

lpti
Address of a TOOLINFO structure. When sending the message, the hwnd and uId members identify a tool, and the cbSize member must specify the size of the structure. If the tooltip control includes the tool, the structure receives information about the tool.
TTM_HITTEST
TTM_HITTEST 
    wParam = 0; 
    lParam = (LPARAM) (LPHITTESTINFO) lphti; 

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

lphti
Address of a TTHITTESTINFO structure. When sending the message, the hwnd member must specify the handle to a tool and the pt member must specify the coordinates of a point. If the return value is TRUE, the ti member (a TOOLINFO structure) receives information about the tool that occupies the point. The cbSize member of the ti structure must be filled in before sending this message.
TTM_NEWTOOLRECT
TTM_NEWTOOLRECT 
    wParam = 0; 
    lParam = (LPARAM) (LPTOOLINFO) lpti; 

Sets a new bounding rectangle for a tool.

lpti
Address of a TOOLINFO structure. The hwnd and uId members identify a tool, and the rect member specifies the new bounding rectangle. The cbSize member of this structure must be filled in before sending this message.
TTM_POP
TTM_POP
    wParam = 0;
    lParam = 0;

Removes a displayed tooltip window from view.

Version 4.70.

TTM_RELAYEVENT
TTM_RELAYEVENT 
    wParam = 0; 
    lParam = (LPARAM) (LPMSG) lpmsg; 

Passes a mouse message to a tooltip control for processing.

lpmsg
Address of an MSG structure that contains the message to relay.

A tooltip control processes only the following messages passed to it by the TTM_RELAYEVENT message:

All other messages are ignored.

TTM_SETDELAYTIME
TTM_SETDELAYTIME
    wParam = (WPARAM)(DWORD) dwDuration;
    lParam = (LPARAM)(INT) MAKELONG(iTime,0);

Sets the initial, pop-up, and reshow durations for a tooltip control.

dwDuration
Flag that specifies the duration value to set. 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.
iTime Delay time to be set, in milliseconds.

Version 4.70.

See also TTM_GETDELAYTIME

TTM_SETMARGIN
TTM_SETMARGIN
    wParam = 0;
    lParam = (LPARAM)(LPRECT) lprc;

Sets the top, left, bottom, and right margins for a tooltip window. A margin is the distance, in pixels, between the tooltip window border and the text contained within the tooltip window.

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. For the purpose of this message, the structure members are interpreted as follows:
top Distance between top border and top of tooltip text, in pixels.
left Distance between left border and left end of tooltip text, in pixels.
bottom Distance between bottom border and bottom of tooltip text, in pixels.
right Distance between right border and right end of tooltip text, in pixels.

Version 4.70.

See also TTM_GETMARGIN

TTM_SETMAXTIPWIDTH
TTM_SETMAXTIPWIDTH
    wParam = 0;
    lParam = (LPARAM)(INT) iWidth;

Sets the maximum width for a tooltip window.

iWidth
Maximum tooltip window width to be set.

The maximum tooltip width value does not indicate a tooltip window's actual width. Rather, if a tooltip string exceeds the maximum width, the control breaks the text into multiple lines, using spaces to determine line breaks. If the text cannot be segmented into multiple lines, it will be displayed on a single line. The length of this line may exceed the maximum tooltip width.

Version 4.70.

See also TTM_GETMAXTIPWIDTH

TTM_SETTIPBKCOLOR
TTM_SETTIPBKCOLOR
    wParam = (WPARAM)(COLORREF) clr;
    lParam = 0;

Sets the background color in a tooltip window.

clr
New background color.

Version 4.70.

See also TTM_GETTIPBKCOLOR

TTM_SETTIPTEXTCOLOR
TTM_SETTIPTEXTCOLOR
    wParam = (WPARAM)(COLORREF) clr;
    lParam = 0;

Sets the text color in a tooltip window.

clr
New text color.

Version 4.70.

See also TTM_GETTIPTEXTCOLOR

TTM_SETTOOLINFO
TTM_SETTOOLINFO 
    wParam = 0; 
    lParam = (LPARAM) (LPTOOLINFO) lpti; 

Sets the information that a tooltip control maintains for a tool.

lpti
Address of a TOOLINFO structure that specifies the information to set. The cbSize member of this structure must be filled in before sending this message.
TTM_TRACKACTIVATE
TTM_TRACKACTIVATE
    wParam = (WPARAM)(BOOL) bActivate;
    lParam = (LPARAM)(LPTOOLINFO) lpti;

Activates or deactivates a tracking tooltip.

bActivate
Value specifying whether tracking is being activated or deactivated. This value can be one of the following:
TRUE Activate tracking.
FALSE Deactivate tracking.
lpti
Address of a TOOLINFO structure that identifies the tool to which this message applies. The hwnd and uId members identify the tool, and the cbSize member specifies the size of the structure. All other members are ignored.

Version 4.70.

See also Tracking Tooltips, TTM_TRACKPOSITION

TTM_TRACKPOSITION
TTM_TRACKPOSITION
    wParam = 0;
    lParam = (LPARAM)(DWORD) MAKELONG(xPos, yPos);

Sets the position of a tracking tooltip.

xPos and yPos
The x- and y-coordinates of the point at which the tracking tooltip will be displayed, in screen coordinates.

The tooltip control chooses where to display the tooltip window based on the coordinates you provide with this message. This causes the tooltip window to appear beside the tool to which it corresponds. To have tooltip windows displayed at specific coordinates, include the TTF_ABSOLUTE flag in the uFlags member of the TOOLINFO structure when adding the tool.

Version 4.70.

See also Tracking Tooltips, TTM_TRACKACTIVATE

TTM_UPDATE
TTM_UPDATE
    wParam = 0;
    lParam = 0;

Forces the current tool to be redrawn.

Version 4.71.

TTM_UPDATETIPTEXT
TTM_UPDATETIPTEXT 
    wParam = 0; 
    lParam = (LPARAM) (LPTOOLINFO) lpti; 

Sets the tooltip text for a tool.

lpti
Address of a TOOLINFO structure. The hinst and lpszText members must specify the instance handle and the address of the text. The hwnd and uId members identify the tool to update. The cbSize member of this structure must be filled in before sending this message.
TTM_WINDOWFROMPOINT
TTM_WINDOWFROMPOINT 
    wParam = 0; 
    lParam = (POINT FAR *) lppt; 

Allows a subclass procedure to cause a tooltip to display text for a window other than the one beneath the mouse cursor.

lppt
Address of a POINT structure that defines the point to be checked.

This message is intended to be processed by an application that subclasses a tooltip. It is not intended to be sent by an application. A tooltip sends this message to itself before displaying the text for a window. By changing the coordinates of the point specified by lppt, the subclass procedure can cause the tooltip to display text for a window other than the one beneath the mouse cursor.

Tooltip Control Notification Messages

This section contains information about the notification messages sent by tooltip controls.

NM_CUSTOMDRAW (tooltip)
NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMTTCUSTOMDRAW) lParam;

Sent by a tooltip control to notify its parent windows about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

lpNMCustomDraw
Address of an NMTTCUSTOMDRAW structure that contains information about the drawing operation.

Version 4.70

See also Using Custom Draw

TTN_GETDISPINFO
TTN_GETDISPINFO
    lpnmtdi = (LPNMTTDISPINFO)lParam;

#define TTN_NEEDTEXT TTN_GETDISPINFO

Sent by a tooltip control to retrieve information needed to display a tooltip window. This notification supersedes the TTN_NEEDTEXT notification. This notification is sent in the form of a WM_NOTIFY message.

lpnmtdi
Address of an NMTTDISPINFO structure that identifies the tool that needs text and receives the requested information.

Fill the structure's appropriate fields to return the requested information to the tooltip control. If your message handler sets the uFlags field of the NMTTDISPINFO structure to TTF_DI_SETITEM, the tooltip control stores the information and will not request it again.

Version 4.70

TTN_POP
TTN_POP 
	idTT = (int) wParam; 
	pnmh = (LPNMHDR) lParam; 

Notifies the owner window that a tooltip is about to be hidden. This notification message is sent in the form of a WM_NOTIFY message.

idTT
Identifier of the tooltip control.
pnmh
Address of an NMHDR structure.
TTN_SHOW
TTN_SHOW 
	idTT = (int) wParam; 
	pnmh = (LPNMHDR) lParam; 

Notifies the owner window that a tooltip is about to be displayed. This notification message is sent in the form of a WM_NOTIFY message.

idTT
Identifier of the tooltip control.
pnmh
Address of an NMHDR structure.

Tooltip Control Structures

This section contains information about the structures used with tooltip controls.

NMTTCUSTOMDRAW
typedef struct tagNMTTCUSTOMDRAW {
    NMCUSTOMDRAW nmcd;
    UINT         uDrawFlags;
} NMTTCUSTOMDRAW, FAR * LPNMTTCUSTOMDRAW;

Contains information specific to an NM_CUSTOMDRAW notification message sent by a tooltip control.

nmcd
NMCUSTOMDRAW structure that contains general custom draw information.
uDrawFlags
UINT value specifying how tooltip text will be formatted when it is displayed. This value is passed to the DrawText function internally. All values for the uFormat parameter of DrawText are valid.

Version 4.70

NMTTDISPINFO
typedef struct tagNMTTDISPINFO {
    NMHDR      hdr;
    LPTSTR     lpszText;
    char       szText[80];
    HINSTANCE  hinst;
    UINT       uFlags;
#if (_WIN32_IE >= 0x0300)
    LPARAM     lParam;
#endif
} NMTTDISPINFO, FAR *LPNMTTDISPINFO;

#define TOOLTIPTEXT NMTTDISPINFO

Contains information used in handling the TTN_GETDISPINFO notification message. This structure supersedes the TOOLTIPTEXT structure.

hdr
NMHDR structure that contains additional information about the notification message.
lpszText
Address of a null-terminated string that will be displayed as the tooltip text. If hinst specifies an instance handle, this member must be the identifier of a string resource.
szText
Buffer that receives the tooltip text. An application can copy the text to this buffer instead of specifying a string address or string resource.
hinst
Handle to the instance that contains a string resource to be used as the tooltip text. If lpszText is the address of the tooltip text string, this member must be NULL.
uFlags
Flags that indicates how to interpret the idFrom member of the included NMHDR structure. If this member is the TTF_IDISHWND flag, idFrom is the tool's handle. Otherwise, it is the tool's identifier.

If you add the TTF_RTLREADING flag to this member while processing the notification, then text on Hebrew or Arabic systems is displayed using right-to-left reading order.

Version 4.70. If you add the TTF_DI_SETITEM flag to this member while processing the notification, the tooltip control will retain the supplied information and not request it again.

lParam
Version 4.70. Application-defined data associated with the tool.
TOOLINFO
typedef struct tagTOOLINFO{
    UINT      cbSize; 
    UINT      uFlags; 
    HWND      hwnd; 
    UINT      uId; 
    RECT      rect; 
    HINSTANCE hinst; 
    LPTSTR    lpszText; 
#if (_WIN32_IE >= 0x0300)
    LPARAM lParam;
#endif
} TOOLINFO, NEAR *PTOOLINFO, FAR *LPTOOLINFO; 

Contains information about a tool in a tooltip control.

cbSize
Size of the TOOLINFO structure, in bytes. This member must be specified.
uFlags
Set of bit flags. This member can be a combination of the following flags:
TTF_ABSOLUTE Version 4.70. Positions the tooltip window at the same coordinates provided by TTM_TRACKPOSITION. This flag must be used with the TTF_TRACK flag.
TTF_CENTERTIP Centers the tooltip window below the tool specified by the uId member.
TTF_IDISHWND Indicates that the uId member is the window handle to the tool. If this flag is not set, uId is the tool's identifier.
TTF_RTLREADING Displays text using right-to-left reading order on Hebrew or Arabic systems.
TTF_SUBCLASS Indicates that the tooltip control should subclass the tool's window to intercept messages, such as WM_MOUSEMOVE. If not set, you must use the TTM_RELAYEVENT message to forward messages to the tooltip control. For a list of messages that a tooltip control processes, see TTM_RELAYEVENT.
TTF_TRACK Version 4.70. Positions the tooltip window next to the tool to which it corresponds and moves the window according to coordinates supplied by the TTM_TRACKPOSITION messages. You must activate this type of tool using the TTM_TRACKACTIVATE message.
TTF_TRANSPARENT Version 4.70. Causes the tooltip control to forward mouse event messages to the parent window. This is limited to mouse events that occur within the bounds of the tip window.
hwnd
Handle to the window that contains the tool. If lpszText includes the LPSTR_TEXTCALLBACK value, this member identifies the window that receives the TTN_GETDISPINFO notification messages.
uId
Application-defined identifier of the tool. If uFlags includes the TTF_IDISHWND flag, uId must specify the window handle to the tool.
rect
Tool's bounding rectangle coordinates. The coordinates are relative to the upper-left corner of the client area of the window identified by hwnd. If uFlags includes the TTF_IDISHWND flag, this member is ignored.
hinst
Handle to the instance that contains the string resource for the tool. If lpszText specifies the identifier of a string resource, this member is used.
lpszText
Address of the buffer that contains the text for the tool, or identifier of the string resource that contains the text. If this member is set to the LPSTR_TEXTCALLBACK value, the control sends the TTN_NEEDTEXT notification message to the owner window to retrieve the text.
lParam
Version 4.70. A 32-bit application defined value that is associated with the tool.
TTHITTESTINFO
typedef struct _TT_HITTESTINFO {
    HWND hwnd; 
    POINT pt; 
    TOOLINFO ti; 
} TTHITTESTINFO, FAR * LPHITTESTINFO; 

Contains information that a tooltip control uses to determine whether a point is in the bounding rectangle of the specified tool. If the point is in the rectangle, the structure receives information about the tool.

hwnd
Handle to the tool or window with the specified tool.
pt
Client coordinates of the point to test.
ti
TOOLINFO structure. If the point specified by pt is in the tool specified by hwnd, this structure receives information about the tool. The cbSize member of this structure must be filled in before sending this message.

This structure is used with the TTM_HITTEST message.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.