Tooltips, Status Tips, and Whats This? Help

Tooltips, Status Tips, and What s This? Help

A tooltip is a small piece of text that appears when the mouse hovers over a widget for a certain period of time. Tooltips are presented with black text on a yellow background. Their primary use is to provide textual descriptions of toolbar buttons.

We can add tooltips to arbitrary widgets in code using QToolTip::add(). For example:

QToolTip::add(findButton, tr("Find next"));

To set the tooltip of a toolbar button that corresponds to a QAction, we can simply call setToolTip() on the action. For example:

newAct = new QAction(tr("&New"), tr("Ctrl+N"), this);
newAct->setToolTip(tr("New file"));

If we don't explicitly set a tooltip, QAction will automatically derive one from the action text and the accelerator key (for example, "New (Ctrl+N)").

A status tip is also a short piece of descriptive text, usually a little longer than a tooltip. When the mouse hovers over a toolbar button or a menu option, a status tip appears in the status bar. Call setStatusTip() to add a status tip to an action:

newAct->setStatusTip(tr("Create a new file"));

In the absence of a status tip, QAction will use the tooltip text instead.

If we don't use QActions, we need to pass a QToolTipGroup object and a status tip as the third and fourth arguments to QToolTip::add():

QToolTip::add(findButton, tr("Find next"), toolTipGroup,
 tr("Find the next occurrence of the search text"));

The application can be made to show the longer text in the status bar by connecting the QToolTipGroup'sshowTip() and removeTip() signals to the status bar's message() and clear() slots. The QToolTipGroup object is responsible for maintaining contact between tooltips and a widget that can show the longer help text.

Figure 16.1. An application showing a tooltip and a status tip

In Qt Designer, tooltips and status tips are accessible through the toolTip and statusTip properties of a widget or action.

In some situations, it is desirable to provide more information about a widget than can be given by tooltips or status tips. For example, we might want to provide a complex dialog with explanatory text about each field without forcing the user to invoke a separate help window. "What's This?" mode is an ideal solution for this. When a window is in "What's This?" mode, the cursor changes to and the user can click on any user interface component to obtain its help text. To enter "What's This?" mode, the user can either click the ? button in the dialog's title bar (on Windows and KDE) or press Shift+F1.

The help text can be set by calling QWhatsThis::add(). Here's an example:

QWhatsThis::add(sourceLineEdit,
 tr(""
 " The meaning of the Source field depends on the "
 "Type field:"
 "

• " "
• Books have a Publisher
• " "
• Articles have a Journal name with volume and " "issue number
• " "
• Thesis have an Institution name and a " "department name
• " "

"));

As with many other Qt widgets, we can use HTML-style tags to format the text of a tooltip. In the example, we include an image (which is listed in the application's .pro file IMAGE entry), a bulleted list, and some text in bold. The tags that Qt supports are specified in the QStyleSheet documentation.

Figure 16.2. A dialog showing a "What's This?" help text

We can also set a "What's This?" text on an action:

openAct->setWhatsThis(tr(" "
 "Click this option to open an "
 "existing file."));

The text will be shown when the user clicks the menu item or toolbar button or presses the accelerator key while in "What's This?" mode. In Qt Designer, the "What's This?" text for a widget or action is available through the whatsThis property.

When the user interface components of an application's main window provide "What's This?" text, it is customary to provide a What's This? option in the Help menu as well as a What's This? toolbar button. This can be done by creating a What's This? action and connecting its activated() signal to the QMainWindow's whatsThis() slot, which enters "What's This?" mode when executed.