QToolTip(3qt)QToolTip(3qt)NAME
QToolTip - Tool tips (balloon help) for any widget or rectangular part
of a widget
SYNOPSIS
#include <qtooltip.h>
Inherits Qt.
Public Members
QToolTip ( QWidget * widget, QToolTipGroup * group = 0 )
QWidget * parentWidget () const
QToolTipGroup * group () const
Static Public Members
void add ( QWidget * widget, const QString & text )
void add ( QWidget * widget, const QString & text, QToolTipGroup *
group, const QString & longText )
void remove ( QWidget * widget )
void add ( QWidget * widget, const QRect & rect, const QString & text )
void add ( QWidget * widget, const QRect & rect, const QString & text,
QToolTipGroup * group, const QString & groupText )
void remove ( QWidget * widget, const QRect & rect )
QString textFor ( QWidget * widget, const QPoint & pos = QPoint ( ) )
void hide ()
QFont font ()
void setFont ( const QFont & font )
QPalette palette ()
void setPalette ( const QPalette & palette )
void setEnabled ( bool enable ) (obsolete)
bool enabled () (obsolete)
void setGloballyEnabled ( bool enable )
bool isGloballyEnabled ()
void setWakeUpDelay ( int i )
Protected Members
virtual void maybeTip ( const QPoint & p ) = 0
void tip ( const QRect & rect, const QString & text )
void tip ( const QRect & rect, const QString & text, const QString &
groupText )
void tip ( const QRect & rect, const QString & text, const QRect &
geometry )
void tip ( const QRect & rect, const QString & text, const QString &
groupText, const QRect & geometry )
void clear ()
DESCRIPTION
The QToolTip class provides tool tips (balloon help) for any widget or
rectangular part of a widget.
The tip is a short, single line of 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.
The tip can be any Rich-Text formatted string.
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 hovers the
mouse on a tip-equipped region for a second or so and remains active
until the user either clicks a mouse button, presses a key, lets the
mouse hover for five seconds or moves the mouse outside all tip-
equipped regions for at least a second.
The QToolTip class can be used in three different ways: <ol type=1>
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 grp is a QToolTipGroup *
and is already connected to the appropriate status bar:
QToolTip::add( quitButton, "Leave the application", grp,
"Leave the application, prompting to save if necessary" );
QToolTip::add( closeButton, "Close this window", grp,
"Close this window, prompting to save if necessary" );
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 these are one-liners and cover the majority of cases. The third
and most general way to use QToolTip requires you to reimplement 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 tips for text that can move as the user scrolls, for
example.
To use QToolTip like this, you must subclass QToolTip and reimplement
maybeTip(). QToolTip calls maybeTip() when a tip should pop up, and
maybeTip() decides whether to show a tip.
Tool tips can be globally disabled using QToolTip::setGloballyEnabled()
or disabled in groups with QToolTipGroup::setEnabled().
You can retrieve the text of a tooltip for a given position within a
widget using textFor().
The global tooltip font and palette can be set with the static
setFont() and setPalette() functions respectively.
See also QStatusBar, QWhatsThis, QToolTipGroup, GUI Design Handbook:
Tool Tip, and Help System.
MEMBER FUNCTION DOCUMENTATIONQToolTip::QToolTip ( QWidget * widget, QToolTipGroup * group = 0 )
Constructs a tool tip object. This is only necessary if you need tool
tips on regions that can move within the widget (most often because the
widget's contents can scroll).
widget is the widget you want to add dynamic tool tips to and group
(optional) is the tool tip group they should belong to.
Warning: QToolTip is not a subclass of QObject, so the instance of
QToolTip is not deleted when widget is deleted.
Warning: If you delete the tool tip before you have deleted widget then
you need to make sure you call remove() yourself from widget in your
reimplemented QToolTip destructor.
MyToolTip::~MyToolTip()
{
remove( widget );
}
See also maybeTip().
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.
This is the most common entry point to the QToolTip class; it is
suitable for adding tool tips to buttons, checkboxes, comboboxes and so
on.
Examples:
void QToolTip::add ( QWidget * widget, const QString & text, QToolTipGroup *
group, const QString & longText ) [static]
This is an overloaded member function, provided for convenience. It
behaves essentially like the above function.
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.
Normally, longText is shown in a status bar or similar.
void QToolTip::add ( QWidget * widget, const QRect & rect, const QString &
text ) [static]
This is an overloaded member function, provided for convenience. It
behaves essentially like the above function.
Adds a tool tip to a fixed rectangle, rect, within widget. text is the
text shown in the tool tip.
void QToolTip::add ( QWidget * widget, const QRect & rect, const QString &
text, QToolTipGroup * group, const QString & groupText ) [static]
This is an overloaded member function, provided for convenience. It
behaves essentially like the above function.
Adds a tool tip to an entire widget and to tool tip group group. The
tooltip will disappear when the mouse leaves the rect.
text is the text shown in the tool tip and groupText is the text
emitted from group.
Normally, groupText is shown in a status bar or similar.
void QToolTip::clear () [protected]
Immediately removes all tool tips for this tooltip's parent widget.
bool QToolTip::enabled () [static]
This function is obsolete. It is provided to keep old source working.
We strongly advise against using it in new code.
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 or 0 if it
isn't a member of any group.
The tool tip group is the object responsible for maintaining contact
between tool tips and a status bar or something else which can show the
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.
bool QToolTip::isGloballyEnabled () [static]
Returns whether tool tips are enabled globally.
See also setGloballyEnabled().
void QToolTip::maybeTip ( const QPoint & p ) [pure virtual protected]
This pure virtual function is half of the most versatile interface
QToolTip offers.
It is called when there is a possibility that a tool tip should be
shown and must decide whether there is a tool tip for the point p in
the widget that this QToolTip object relates to. If so, maybeTip() must
call tip() with the rectangle the tip applies to, the tip's text and
optionally the QToolTipGroup details and the geometry in screen
coordinates.
p is given in that widget's local coordinates. Most maybeTip()
implementations will be of the form:
if ( <something> ) {
tip( <something>, <something> );
}
The first argument to tip() (a rectangle) must encompass p, i.e. the
tip must apply to the current mouse position; otherwise QToolTip's
operation is undefined.
Note that the tip will disappear once the mouse moves outside the
rectangle you give to tip(), and will not reappear if the mouse moves
back in: maybeTip() is called again instead.
See also tip().
Examples:
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]
Removes the tool tip from widget.
If there is 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]
This is an overloaded member function, provided for convenience. It
behaves essentially like the above function.
Removes any tool tip for rect from widget.
If there is more than one tool tip on widget, only the one covering
rectangle rect is removed.
void QToolTip::setEnabled ( bool enable ) [static]
This function is obsolete. It is provided to keep old source working.
We strongly advise against using it in new code.
void QToolTip::setFont ( const QFont & font ) [static]
Sets the font for all tool tips to font.
See also font().
void QToolTip::setGloballyEnabled ( bool enable ) [static]
If enable is TRUE sets all tool tips to be enabled (shown when needed);
if enable is FALSE sets all tool tips to be disabled (never shown).
By default, tool tips are enabled. Note that this function affects all
tool tips in the entire application.
See also QToolTipGroup::enabled.
void QToolTip::setPalette ( const QPalette & palette ) [static]
Sets the palette for all tool tips to palette.
See also palette().
void QToolTip::setWakeUpDelay ( int i ) [static]
Sets the wakeup delay for all tooltips to i milliseconds.
QString QToolTip::textFor ( QWidget * widget, const QPoint & pos = QPoint ( )
) [static]
Returns the tool tip text for widget at position pos, or QString::null
if there is no tool tip for the given widget and position.
void QToolTip::tip ( const QRect & rect, const QString & text ) [protected]
Immediately pops up a tip saying text and removes the 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 reappear if the cursor moves back; your maybeTip()
must reinstate it each time.
void QToolTip::tip ( const QRect & rect, const QString & text, const QString &
groupText ) [protected]
This is an overloaded member function, provided for convenience. It
behaves essentially like the above function.
Immediately pops up a tip saying text 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). groupText is the text
emitted from the group.
The tip will not reappear if the cursor moves back; your maybeTip()
must reinstate it each time.
void QToolTip::tip ( const QRect & rect, const QString & text, const QRect &
geometry ) [protected]
This is an overloaded member function, provided for convenience. It
behaves essentially like the above function.
Immediately pops up a tip within the rectangle geometry, saying text
and removes the tip once the cursor moves out of rectangle rect. Both
rectangles are given in the coordinate system of the widget this
QToolTip relates to.
The tip will not reappear if the cursor moves back; your maybeTip()
must reinstate it each time.
If the tip does not fit inside geometry, the tip expands.
void QToolTip::tip ( const QRect & rect, const QString & text, const QString &
groupText, const QRect & geometry ) [protected]
This is an overloaded member function, provided for convenience. It
behaves essentially like the above function.
Immediately pops up a tip within the rectangle geometry, saying text
and removes the tip once the cursor moves out of rectangle rect.
groupText is the text emitted from the group. Both rectangles are given
in the coordinate system of the widget this QToolTip relates to.
The tip will not reappear if the cursor moves back; your maybeTip()
must reinstate it each time.
If the tip does not fit inside geometry, the tip expands.
SEE ALSO
http://doc.trolltech.com/qtooltip.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2007 Trolltech ASA, 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 help us to
help you. Thank you.
The definitive Qt documentation is provided in HTML format; it is
located at $QTDIR/doc/html and can be read using Qt Assistant or with a
web browser. This man page is provided as a convenience for those users
who prefer man pages, although this format is not officially supported
by Trolltech.
If you find errors in 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 (3.3.8).
Trolltech AS 2 February 2007 QToolTip(3qt)
