About the Tool Tip Control

The TTooltip encapsulates a tooltip control: a small pop-up window that displays a single line of descriptive text giving the purpose of a tool in an application.

The tool is either a window, such as a child window or control, or an application-defined rectangular area within a window's client area.

The tooltip control appears only when the user puts the cursor on a tool and leaves it there for approximately one-half second. It appears near the cursor and disappears when the user clicks a mouse button or moves the cursor away from the tool.

The TTooltip class offers two constructors: one for creating a new control and one for aliasing an existing control.

Creating a ToolTip Object

The following code fragment shows how to create a tooltip control.

void TMyWindow::SetupWindow()
{
 TWindow::SetupWindow();
 tooltip = new TTooltip(this);
 tooltip->Create();
}

Specifying Tools to the Tooltip Control

Once you have created a tooltip control, you must specify the tools that it will work with. You do this by creating a TToolInfo for each tool. For example, the following code designates a rectangular area of a window as a tool:

void TMyWindow::AddTopLeftTool()
{
 uint toolId = ID_TOPLEFT_TOOL;   // Tool ID
 TRect rect(0, 0, 20, 20);      // Tool Rectangle
 TToolInfo ti(this, rect, ID_TOPLEFT_TOOL);
 tooltip->AddTool(ti);
}

Providing the Tooltip Text

When adding a tool, you may provide the text to be used when describing the tool as the last parameter to the constructor of the TToolInfo structure. For example, the following code specifies "Top Left" as the tool tip text:

TToolInfo ti(this, rect, ID_TOPLEFT_TOOL, "Top Left");
tooltip->AddTool(ti);

However, you may opt to provide the text on demand. This allows you to customize the message display to the user. The EV_TTN_NEEDTEXT macro allows you to specify a member function which can provide the text at runtime. The following code fragement illustrates:

class TMyWindow : public TWindow {
// Additional definitions ommitted for clarity
protected:
void HandleTooltipText(TTooltipText& tiTxt);
};
 
DEFINE_RESPONSE_TABLE1(TMyWindow, TWindow)
 EV_TTN_NEEDTEXT(ID_TOPLEFT_TOOL, HandleTooltipText),
END_RESPONSE_TABLE;
 
void
TMyWindow::HandleTooltipText(TTooltipText& tiTxt)
{
tiTxt.CopyText("Top Left square");
}

Additional Information

The notification handler of the ObjectWindows TDecoratedFrame class enhances the mechanism for specifying the tooltip text by sending a TTooltipEnabler up the command chain. This allows the context window to provide the text even if it did not setup the tool. For example, a grid control in focus can customize the cut, paste and copy tools to specify the data type being manipulated ("Copy Cell" instead of just "Copy").

The EvCommandEnable handler of TDecoratedFrame attempts to provide the tooltip text by looking in two locations:

1. First the window's menu is scanned for a menuitem with an id corresponding to that of the tool. If found, the menustring is provided.
2. Next, TDecoratedFrame attempts to load a string resource with an id corresponding to that of the tool. If found, the string is scanned for a line-feed character. If successful, TDecoratedFrame provides the string following the line-feed as tooltip text.

Note

You should structure your hint text string using the following format:

<string to be displayed on statusbar>\n<tooltip hint text>