| Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions | |
The QToolTip class provides tool tips (balloon help) for any widget or rectangular part of a widget. More...
#include <qtooltip.h>
Inherits Qt.
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:
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.
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().
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: helpsystem/mainwindow.cpp, qdir/qdir.cpp, scribble/scribble.cpp, and tooltip/tooltip.cpp.
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.
Adds a tool tip to a fixed rectangle, rect, within widget. text is the text shown in the tool tip.
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.
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
See also setFont().
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.
Normally, there is no need to call this function; QToolTip takes care of showing and hiding the tips as the user moves the mouse.
See also setGloballyEnabled().
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: helpsystem/tooltip.cpp and tooltip/tooltip.cpp.
See also setPalette().
Returns the widget this QToolTip applies to.
The tool tip is destroyed automatically when the parent widget is destroyed.
See also group().
If there is more than one tool tip on widget, only the one covering the entire widget is removed.
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.
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
See also font().
By default, tool tips are enabled. Note that this function affects all tool tips in the entire application.
See also QToolTipGroup::enabled.
See also palette().
The tip will not reappear if the cursor moves back; your maybeTip() must reinstate it each time.
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.
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.
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.
This file is part of the Qt toolkit. Copyright © 1995-2005 Trolltech. All Rights Reserved.
| Copyright © 2005 Trolltech | Trademarks | Qt 3.3.6
|