QToolTip Class Reference

The QToolTip class provides tool tips (sometimes called balloon help) for any widget or rectangular part of a widget. More...

#include <qtooltip.h>

List of all member functions.

Public Members

• QToolTip ( QWidget *, QToolTipGroup * = 0 ) 
• QWidget* parentWidget () const
• QToolTipGroup* group () const

Static Public Members

• void add ( QWidget *, const char * ) 
• void add ( QWidget *, const char *, QToolTipGroup *, const char * ) 
• void remove ( QWidget * ) 
• void add ( QWidget *, const QRect &, const char * ) 
• void add ( QWidget *, const QRect &, const char *, QToolTipGroup *, const char * ) 
• void remove ( QWidget *, const QRect & ) 
• QFont font () 
• void setFont ( const QFont & ) 
• QPalette palette () 
• void setPalette ( const QPalette & ) 

Protected Members

• virtual void maybeTip ( const QPoint & ) 
• void tip ( const QRect &, const char * ) 
• void tip ( const QRect &, const char *, const char * ) 
• void clear () 

Detailed Description

The tip is a short, one-line text reminding the user of the widget's or rectangle's function. It is drawn immediately below the region, in a distinctive black on yellow combination. In Motif style, Qt's tool tips look much like Motif's but feel more like Windows 95 tool tips.

QToolTipGroup provides a way for tool tips to display another text elsewhere (most often in a status bar).

At any point in time, QToolTip is either dormant or active. In dormant mode the tips are not shown, and in active mode they are. The mode is global, not particular to any one widget.

QToolTip switches from dormant to active mode when the user lets the mouse rest on a tip-equipped region for a second or so, and remains in active mode until the user either clicks a mouse button, presses a key, lets the mouse rest for five seconds, or moves the mouse outside all tip-equpped regions for at least a second.

The QToolTip class can be used in three different ways:

1. Adding a tip to an entire widget.
2. Adding a tip to a fixed rectangle within a widget.
3. Adding a tip to a dynamic rectangle within a widget.

To add a tip to a widget, call the static function QToolTip::add() with the widget and tip as arguments:

    QToolTip::add( quitButton, "Leave the application" );

This is the simplest and most common use of QToolTip. The tip will be deleted automatically when quitButton is deleted, but you can remove it yourself, too:

    QToolTip::remove( quitButton );

You can also display another text (typically in a status bar), courtesy of QToolTipGroup. This example assumes that g is a QToolTipGroup * and already connected to the appropriate status bar:

    QToolTip::add( quitButton, "Leave the application", g,
                   "Leave the application, without asking for confirmation" );
    QToolTip::add( closeButton, "Close this window", g,
                   "Close this window, without asking for confirmation" );

To add a tip to a fixed rectangle within a widget, call the static function QToolTip::add() with the widget, rectangle and tip as arguments. (See the tooltip/tooltip.cpp example.) Again, you can supply a QToolTipGroup * and another text if you want.

Both of the above are one-liners and cover the vast majority of cases. The third and most general way to use QToolTip uses a pure virtual function to decide whether to pop up a tool tip. The tooltip/tooltip.cpp example demonstrates this too. This mode can be used to implement e.g. tips for text that can move as the user scrolls.

To use QToolTip like this, you need to subclass QToolTip and reimplement maybeTip(). maybeTip() will be called when there's a chance that a tip should pop up. It must decide whether to show a tip, and possibly call add() with the rectangle the tip applies to, the tip's text and optionally the QToolTipGroup details. The tip will disappear once the mouse moves outside the rectangle you supply, and not reappear - maybeTip() will be called again if the user lets the mouse rest within the same rectangle again. You can forcibly remove the tip by calling remove() with no arguments. This is handy if the widget scrolls.

See also: QStatusBar, QWhatsThis, QToolTipGroup and GUI Design Handbook: Tool Tip

Examples: tooltip/tooltip.cpp

Member Function Documentation

QToolTip::QToolTip ( QWidget * parent, QToolTipGroup * group = 0 )

Creates a tool tip object. This is necessary only if you need tool tips on regions that can move within the widget (most often because the widget's contents can scroll).

parent is widget you want to add dynamic tool tips to and group (optional) is the tool tip group they should belong to.

See also: maybeTip().

void QToolTip::add ( QWidget * widget, const QRect & rect, const char * text ) [static]

Adds a tool tip to a fixed rectangle within widget. text is the text shown in the tool tip. QToolTip makes a deep copy of this string.

void QToolTip::add ( QWidget * widget, const QRect & rect, const char * text, QToolTipGroup * group, const char * groupText ) [static]

Adds a tool tip to an entire widget, and to tool tip group group.

text is the text shown in the tool tip and longText is the text emitted from group. QToolTip makes deep copies of both strings.

Normally, longText is shown in a status bar or similar.

void QToolTip::add ( QWidget * widget, const char * text ) [static]

Adds a tool tip to widget. text is the text to be shown in the tool tip. QToolTip makes a deep copy of this string.

This is the most common entry point to the QToolTip class; it is suitable for adding tool tips to buttons, check boxes, combo boxes and so on.

Examples: tooltip/tooltip.cpp widgets/widgets.cpp

void QToolTip::add ( QWidget * widget, const char * text, QToolTipGroup * group, const char * longText ) [static]

Adds a tool tip to widget, and to tool tip group group.

text is the text shown in the tool tip and longText is the text emitted from group. QToolTip makes deep copies of both strings.

Normally, longText is shown in a status bar or similar.

void QToolTip::clear () [protected]

Remove all tool tips for this widget immediately.

QFont QToolTip::font () [static]

Returns the font common to all tool tips.

See also: setFont().

QToolTipGroup * QToolTip::group () const

Returns the tool tip group this QToolTip is a member of, of 0 if it isn't a member of any group.

The tool tip group is the object responsible for relaying contact betweeen tool tips and a status bar or something else which can show a longer help text.

See also: parentWidget() and QToolTipGroup.

virtual void QToolTip::maybeTip ( const QPoint & p ) [virtual protected]

This pure virtual function is half of the most versatile interface QToolTip offers.

It is called when there is a chance that a tool tip should be shown, and must decide whether there is a tool tip for the point p in the widget this QToolTip object relates to.

\p is given in that widget's local coordinates. Most maybeTip() implementation will be of the form:

    if ( <something> ) {
        tip( <something>, <something> );
    }

The first argument to tip() (a rectangle) should include the p, or QToolTip, the user or both can be confused.

See also: tip().

QPalette QToolTip::palette () [static]

Returns the palette common to all tool tips.

See also: setPalette().

QWidget * QToolTip::parentWidget () const

Returns the widget this QToolTip applies to.

The tool tip is destroyed automatically when the parent widget is destroyed.

See also: group().

void QToolTip::remove ( QWidget * widget ) [static]

Remove the tool tip from widget.

If there are more than one tool tip on widget, only the one covering the entire widget is removed.

void QToolTip::remove ( QWidget * widget, const QRect & rect ) [static]

Remove the tool tip for rect from widget.

If there are more than one tool tip on widget, only the one covering rectangle rect is removed.

void QToolTip::setFont ( const QFont & font ) [static]

Sets the font for all tool tips to font.

See also: font().

void QToolTip::setPalette ( const QPalette & palette ) [static]

Sets the palette for all tool tips to palette.

See also: palette().

void QToolTip::tip ( const QRect & rect, const char * text ) [protected]

Pop up a tip saying text right now, and remove that tip once the cursor moves out of rectangle rect (which is given in the coordinate system of the widget this QToolTip relates to).

The tip will not come back if the cursor moves back; your maybeTip() has to reinstate it each time.

Examples: tooltip/tooltip.cpp

void QToolTip::tip ( const QRect & rect, const char * text, const char * groupText ) [protected]

Pop up a tip saying text right now, and remove that tip once the cursor moves out of rectangle rect.

The tip will not come back if the cursor moves back; your maybeTip() has to reinstate it each time.

Search the documentation, FAQ, qt-interest archive and more (uses www.troll.no):

This file is part of the Qt toolkit, copyright © 1995-98 Troll Tech, all rights reserved.

It was generated from the following files:

• qtooltip.h: 1998/07/03
• qtooltip.cpp: 1998/07/03