Creating a ToolTip Control

  • Article

Other versions of this page are also available for the following:

Windows Mobile Not SupportedWindows Embedded CE Supported

8/28/2008

A ToolTip appears to the upper-left of the point where the user first taps the screen. You can use ToolTips to extend the name of a control. For example, a New button can have a ToolTip that displays New Mail Message. A ToolTip can also direct a user to Help files or printed documentation.

In addition to the UI elements that can have ToolTips, you can declare static and button controls as ToolTip controls. You can also place ToolTip controls in dialog boxes and other application windows.

As of Windows CE .NET 4.2, you can use either a window class or resource file to create ToolTips. Resource files are used to create cross-operating system applications that can run on both Windows Embedded CE and Windows Mobile operating systems.

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 that currently is selected into the device context for the ToolTip control. The width depends on the length of the string that the ToolTip window currently displays.

A ToolTip control exists in either an active or inactive state. When the ToolTip control is active, it appears when the cursor remains stationary over a tool. When the ToolTip control is inactive, it does not appear, even when the cursor remains stationary over a tool. Use the TTM_ACTIVATE message to activate or deactivate a ToolTip control.

To create a ToolTip control using a window class

  • Call the CreateWindowEx function and specify the TOOLTIPS_CLASS window class.

    The class registers when you load the DLL for the common control. To load the DLL for the common control, include a call to the InitCommonControls function in your application.

    The following code example shows how to create a ToolTip using a window class.

    HWND hwndTip = CreateWindowEx(NULL, TOOLTIPS_CLASS, NULL,
                              WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
                              CW_USEDEFAULT, CW_USEDEFAULT,
                              CW_USEDEFAULT, CW_USEDEFAULT,
                              hWndParent, NULL, 
                              hinstMyDll, NULL);

To create a ToolTip control using a resource file

  1. Call SHInitExtraControls.

    This initializes the ToolTip control. If you are programming multiple ToolTip controls, you need to call SHInitExtraControls only once.

  2. Declare the ToolTip control in your resource file.

    • Declare buttons, group boxes, check boxes, and radio buttons as TTBUTTON.
    • Declare static controls as TTSTATIC.
    • Declare all other ToolTips as standard Windows Embedded CE ToolTips.

  3. Write the ToolTip control text in two sections. Separate the sections with a double tilde: ~~.

    The text before the double tilde is the text that appears on the control. The text after the double tilde is the text that appears in the ToolTip. This text can be up to 253 characters long. If you do not add any text after the double tilde, the shell displays No Help provided when the user accesses the control's ToolTip.

    The following code example shows how to declare a button ToolTip control in a resource file.

    CONTROL        "CheckBox~~A Checkbox ToolTip",IDC_SAVE,"TTBUTTON",
               BS_AUTOCHECKBOX|WS_GROUP|WS_TABSTOP,3,0,95,11

    If the ToolTip is wider than the screen, it wraps to a new line. You can force a line break by placing the \r character within the ToolTip text. However, do not use \r as a first or last character. Also, do not use \r consecutively, such as \r\r.

    The following code shows how to use the \r character in a control declaration of a resource file.

    CONTROL        "Static Text~~First ToolTip line\rSecond ToolTip 
               line",IDC_STATIC,"TTSTATIC",WS_VISIBLE,19,24,56,8

Modifying a ToolTip

The following code sample shows how to modify ToolTips and the control text of a button control:

// Change the ToolTip text but keep the current control text. 
SetWindowText (hwndBtn, TEXT("~~New ToolTip text"));

// Keep the current ToolTip text but change the control text. 
SetWindowText (hwndBtn, TEXT("New Control Text"));

// Change the ToolTip text and the control text. 
SetWindowText (hwndBtn, TEXT("New Control Text~~New ToolTip text")); 

// Remove the ToolTip text and keep the control text. 
// After this call, the ToolTip display "No Help provided". 
SetWindowText (hwndBtn, TEXT("Old Control Text~~"));

See Also

Reference

CreateWindowEx
InitCommonControls
TTM_ACTIVATE
SHInitExtraControls

Concepts

Using ToolTips
Working with Common Controls
Creating Controls

Other Resources