QToolTip(3qt)QToolTip(3qt)NAME
QToolTip - Tool tips (sometimes called balloon help) for
any widget or rectangular part of a widget
#include <qtooltip.h>
Inherits Qt.
Public Members
QToolTip ( QWidget *, QToolTipGroup * = 0 )
QWidget* parentWidget () const
QToolTipGroup* group () const
Static Public Members
void add ( QWidget *, const QString & )
void add ( QWidget *, const QString &, QToolTipGroup *,
const QString & )
void remove ( QWidget * )
void add ( QWidget *, const QRect &, const QString & )
void add ( QWidget *, const QRect &, const QString &,
QToolTipGroup *, const QString & )
void remove ( QWidget *, const QRect & )
void hide ()
QFont font ()
void setFont ( const QFont & )
QPalette palette ()
void setPalette ( const QPalette & )
void setEnabled ( bool )
bool enabled ()
Protected Members
virtual void maybeTip ( const QPoint & )
void tip ( const QRect &, const QString & )
void tip ( const QRect &, const QString &, const QString &
)
void clear ()
DESCRIPTION
The QToolTip class provides tool tips (sometimes called
balloon help) for any widget or rectangular part of a
widget.
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
Trolltech AS 13 June 2001 1
QToolTip(3qt)QToolTip(3qt)
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
Trolltech AS 13 June 2001 2
QToolTip(3qt)QToolTip(3qt)
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.
Tooltips can be globally disabled using
QToolTip::setEnabled(), or disabled in groups with
QToolTipGroup::setEnabled().
See also QStatusBar, QWhatsThis, QToolTipGroup and GUI
Design Handbook: Tool Tip
MEMBER FUNCTION DOCUMENTATIONQToolTip::QToolTip ( QWidget * parent, QToolTipGroup * group = 0
)
Constructs 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 the 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
QString & 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
QString & text, QToolTipGroup * group, const QString &
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 QString & 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.
Trolltech AS 13 June 2001 3
QToolTip(3qt)QToolTip(3qt)
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.
void QToolTip::add ( QWidget * widget, const QString & text,
QToolTipGroup * group, const QString & 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]
Removes all tool tips for this tooltip's parent widget
immediately.
bool QToolTip::enabled () [static]
Returns whether tooltips are enabled globally.
See also setEnabled().
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 between tool tips and a status bar or something
else which can show a longer help text.
See also parentWidget() and QToolTipGroup.
void QToolTip::hide () [static]
Hides any tip that is currently being shown.
Normally, there is no need to call this function; QToolTip
takes care of showing and hiding the tips as the user
moves the mouse.
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.
Trolltech AS 13 June 2001 4
QToolTip(3qt)QToolTip(3qt)
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::setEnabled ( bool enable ) [static]
Sets the all tool tips to be enabled (shown when needed)
or disabled (never shown).
By default, tool tips are enabled. Note that this function
effects all tooltips in the entire application.
See also QToolTipGroup::setEnabled().
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.
Trolltech AS 13 June 2001 5
QToolTip(3qt)QToolTip(3qt)
See also palette().
void QToolTip::tip ( const QRect & rect, const QString & text )
[protected]
Pops up a tip saying text right now, and removes 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.
void QToolTip::tip ( const QRect & rect, const QString & text,
const QString & groupText ) [protected]
Pops up a tip saying text right now, and removes 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.
SEE ALSO
http://doc.trolltech.com/qtooltip.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page (qtooltip.3qt)
and the Qt version (2.3.1).
Trolltech AS 13 June 2001 6
