1QToolTip(3qt)                                                    QToolTip(3qt)
2
3
4

NAME

6       QToolTip - Tool tips (balloon help) for any widget or rectangular part
7       of a widget
8

SYNOPSIS

10       #include <qtooltip.h>
11
12       Inherits Qt.
13
14   Public Members
15       QToolTip ( QWidget * widget, QToolTipGroup * group = 0 )
16       QWidget * parentWidget () const
17       QToolTipGroup * group () const
18
19   Static Public Members
20       void add ( QWidget * widget, const QString & text )
21       void add ( QWidget * widget, const QString & text, QToolTipGroup *
22           group, const QString & longText )
23       void remove ( QWidget * widget )
24       void add ( QWidget * widget, const QRect & rect, const QString & text )
25       void add ( QWidget * widget, const QRect & rect, const QString & text,
26           QToolTipGroup * group, const QString & groupText )
27       void remove ( QWidget * widget, const QRect & rect )
28       QString textFor ( QWidget * widget, const QPoint & pos = QPoint ( ) )
29       void hide ()
30       QFont font ()
31       void setFont ( const QFont & font )
32       QPalette palette ()
33       void setPalette ( const QPalette & palette )
34       void setEnabled ( bool enable )  (obsolete)
35       bool enabled ()  (obsolete)
36       void setGloballyEnabled ( bool enable )
37       bool isGloballyEnabled ()
38       void setWakeUpDelay ( int i )
39
40   Protected Members
41       virtual void maybeTip ( const QPoint & p ) = 0
42       void tip ( const QRect & rect, const QString & text )
43       void tip ( const QRect & rect, const QString & text, const QString &
44           groupText )
45       void tip ( const QRect & rect, const QString & text, const QRect &
46           geometry )
47       void tip ( const QRect & rect, const QString & text, const QString &
48           groupText, const QRect & geometry )
49       void clear ()
50

DESCRIPTION

52       The QToolTip class provides tool tips (balloon help) for any widget or
53       rectangular part of a widget.
54
55       The tip is a short, single line of text reminding the user of the
56       widget's or rectangle's function. It is drawn immediately below the
57       region in a distinctive black-on-yellow combination.
58
59       The tip can be any Rich-Text formatted string.
60
61       QToolTipGroup provides a way for tool tips to display another text
62       elsewhere (most often in a status bar).
63
64       At any point in time, QToolTip is either dormant or active. In dormant
65       mode the tips are not shown and in active mode they are. The mode is
66       global, not particular to any one widget.
67
68       QToolTip switches from dormant to active mode when the user hovers the
69       mouse on a tip-equipped region for a second or so and remains active
70       until the user either clicks a mouse button, presses a key, lets the
71       mouse hover for five seconds or moves the mouse outside all tip-
72       equipped regions for at least a second.
73
74       The QToolTip class can be used in three different ways: <ol type=1>
75
76       1      Adding a tip to an entire widget.
77
78       2      Adding a tip to a fixed rectangle within a widget.
79
80       3      Adding a tip to a dynamic rectangle within a widget.
81
82       To add a tip to a widget, call the static function QToolTip::add() with
83       the widget and tip as arguments:
84
85               QToolTip::add( quitButton, "Leave the application" );
86
87       This is the simplest and most common use of QToolTip. The tip will be
88       deleted automatically when quitButton is deleted, but you can remove it
89       yourself, too:
90
91               QToolTip::remove( quitButton );
92
93       You can also display another text (typically in a status bar), courtesy
94       of QToolTipGroup. This example assumes that grp is a QToolTipGroup *
95       and is already connected to the appropriate status bar:
96
97               QToolTip::add( quitButton, "Leave the application", grp,
98                              "Leave the application, prompting to save if necessary" );
99               QToolTip::add( closeButton, "Close this window", grp,
100                              "Close this window, prompting to save if necessary" );
101
102       To add a tip to a fixed rectangle within a widget, call the static
103       function QToolTip::add() with the widget, rectangle and tip as
104       arguments. (See the tooltip/tooltip.cpp example.) Again, you can supply
105       a QToolTipGroup * and another text if you want.
106
107       Both of these are one-liners and cover the majority of cases. The third
108       and most general way to use QToolTip requires you to reimplement a pure
109       virtual function to decide whether to pop up a tool tip. The
110       tooltip/tooltip.cpp example demonstrates this too. This mode can be
111       used to implement tips for text that can move as the user scrolls, for
112       example.
113
114       To use QToolTip like this, you must subclass QToolTip and reimplement
115       maybeTip(). QToolTip calls maybeTip() when a tip should pop up, and
116       maybeTip() decides whether to show a tip.
117
118       Tool tips can be globally disabled using QToolTip::setGloballyEnabled()
119       or disabled in groups with QToolTipGroup::setEnabled().
120
121       You can retrieve the text of a tooltip for a given position within a
122       widget using textFor().
123
124       The global tooltip font and palette can be set with the static
125       setFont() and setPalette() functions respectively.
126
127       See also QStatusBar, QWhatsThis, QToolTipGroup, GUI Design Handbook:
128       Tool Tip, and Help System.
129

MEMBER FUNCTION DOCUMENTATION

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

132       Constructs a tool tip object. This is only necessary if you need tool
133       tips on regions that can move within the widget (most often because the
134       widget's contents can scroll).
135
136       widget is the widget you want to add dynamic tool tips to and group
137       (optional) is the tool tip group they should belong to.
138
139       Warning: QToolTip is not a subclass of QObject, so the instance of
140       QToolTip is not deleted when widget is deleted.
141
142       Warning: If you delete the tool tip before you have deleted widget then
143       you need to make sure you call remove() yourself from widget in your
144       reimplemented QToolTip destructor.
145
146               MyToolTip::~MyToolTip()
147               {
148                   remove( widget );
149               }
150
151       See also maybeTip().
152

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

154       Adds a tool tip to widget. text is the text to be shown in the tool
155       tip.
156
157       This is the most common entry point to the QToolTip class; it is
158       suitable for adding tool tips to buttons, checkboxes, comboboxes and so
159       on.
160
161       Examples:
162

void QToolTip::add ( QWidget * widget, const QString & text, QToolTipGroup *

164       group, const QString & longText ) [static]
165       This is an overloaded member function, provided for convenience. It
166       behaves essentially like the above function.
167
168       Adds a tool tip to widget and to tool tip group group.
169
170       text is the text shown in the tool tip and longText is the text emitted
171       from group.
172
173       Normally, longText is shown in a status bar or similar.
174

void QToolTip::add ( QWidget * widget, const QRect & rect, const QString &

176       text ) [static]
177       This is an overloaded member function, provided for convenience. It
178       behaves essentially like the above function.
179
180       Adds a tool tip to a fixed rectangle, rect, within widget. text is the
181       text shown in the tool tip.
182

void QToolTip::add ( QWidget * widget, const QRect & rect, const QString &

184       text, QToolTipGroup * group, const QString & groupText ) [static]
185       This is an overloaded member function, provided for convenience. It
186       behaves essentially like the above function.
187
188       Adds a tool tip to an entire widget and to tool tip group group. The
189       tooltip will disappear when the mouse leaves the rect.
190
191       text is the text shown in the tool tip and groupText is the text
192       emitted from group.
193
194       Normally, groupText is shown in a status bar or similar.
195

void QToolTip::clear () [protected]

197       Immediately removes all tool tips for this tooltip's parent widget.
198

bool QToolTip::enabled () [static]

200       This function is obsolete. It is provided to keep old source working.
201       We strongly advise against using it in new code.
202

QFont QToolTip::font () [static]

204       Returns the font common to all tool tips.
205
206       See also setFont().
207

QToolTipGroup * QToolTip::group () const

209       Returns the tool tip group this QToolTip is a member of or 0 if it
210       isn't a member of any group.
211
212       The tool tip group is the object responsible for maintaining contact
213       between tool tips and a status bar or something else which can show the
214       longer help text.
215
216       See also parentWidget() and QToolTipGroup.
217

void QToolTip::hide () [static]

219       Hides any tip that is currently being shown.
220
221       Normally, there is no need to call this function; QToolTip takes care
222       of showing and hiding the tips as the user moves the mouse.
223

bool QToolTip::isGloballyEnabled () [static]

225       Returns whether tool tips are enabled globally.
226
227       See also setGloballyEnabled().
228

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

230       This pure virtual function is half of the most versatile interface
231       QToolTip offers.
232
233       It is called when there is a possibility that a tool tip should be
234       shown and must decide whether there is a tool tip for the point p in
235       the widget that this QToolTip object relates to. If so, maybeTip() must
236       call tip() with the rectangle the tip applies to, the tip's text and
237       optionally the QToolTipGroup details and the geometry in screen
238       coordinates.
239
240       p is given in that widget's local coordinates. Most maybeTip()
241       implementations will be of the form:
242
243               if ( <something> ) {
244                   tip( <something>, <something> );
245               }
246
247       The first argument to tip() (a rectangle) must encompass p, i.e. the
248       tip must apply to the current mouse position; otherwise QToolTip's
249       operation is undefined.
250
251       Note that the tip will disappear once the mouse moves outside the
252       rectangle you give to tip(), and will not reappear if the mouse moves
253       back in: maybeTip() is called again instead.
254
255       See also tip().
256
257       Examples:
258

QPalette QToolTip::palette () [static]

260       Returns the palette common to all tool tips.
261
262       See also setPalette().
263

QWidget * QToolTip::parentWidget () const

265       Returns the widget this QToolTip applies to.
266
267       The tool tip is destroyed automatically when the parent widget is
268       destroyed.
269
270       See also group().
271

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

273       Removes the tool tip from widget.
274
275       If there is more than one tool tip on widget, only the one covering the
276       entire widget is removed.
277

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

279       This is an overloaded member function, provided for convenience. It
280       behaves essentially like the above function.
281
282       Removes any tool tip for rect from widget.
283
284       If there is more than one tool tip on widget, only the one covering
285       rectangle rect is removed.
286

void QToolTip::setEnabled ( bool enable ) [static]

288       This function is obsolete. It is provided to keep old source working.
289       We strongly advise against using it in new code.
290

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

292       Sets the font for all tool tips to font.
293
294       See also font().
295

void QToolTip::setGloballyEnabled ( bool enable ) [static]

297       If enable is TRUE sets all tool tips to be enabled (shown when needed);
298       if enable is FALSE sets all tool tips to be disabled (never shown).
299
300       By default, tool tips are enabled. Note that this function affects all
301       tool tips in the entire application.
302
303       See also QToolTipGroup::enabled.
304

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

306       Sets the palette for all tool tips to palette.
307
308       See also palette().
309

void QToolTip::setWakeUpDelay ( int i ) [static]

311       Sets the wakeup delay for all tooltips to i milliseconds.
312

QString QToolTip::textFor ( QWidget * widget, const QPoint & pos = QPoint ( )

314       ) [static]
315       Returns the tool tip text for widget at position pos, or QString::null
316       if there is no tool tip for the given widget and position.
317

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

319       Immediately pops up a tip saying text and removes the tip once the
320       cursor moves out of rectangle rect (which is given in the coordinate
321       system of the widget this QToolTip relates to).
322
323       The tip will not reappear if the cursor moves back; your maybeTip()
324       must reinstate it each time.
325

void QToolTip::tip ( const QRect & rect, const QString & text, const QString &

327       groupText ) [protected]
328       This is an overloaded member function, provided for convenience. It
329       behaves essentially like the above function.
330
331       Immediately pops up a tip saying text and removes that tip once the
332       cursor moves out of rectangle rect (which is given in the coordinate
333       system of the widget this QToolTip relates to). groupText is the text
334       emitted from the group.
335
336       The tip will not reappear if the cursor moves back; your maybeTip()
337       must reinstate it each time.
338

void QToolTip::tip ( const QRect & rect, const QString & text, const QRect &

340       geometry ) [protected]
341       This is an overloaded member function, provided for convenience. It
342       behaves essentially like the above function.
343
344       Immediately pops up a tip within the rectangle geometry, saying text
345       and removes the tip once the cursor moves out of rectangle rect. Both
346       rectangles are given in the coordinate system of the widget this
347       QToolTip relates to.
348
349       The tip will not reappear if the cursor moves back; your maybeTip()
350       must reinstate it each time.
351
352       If the tip does not fit inside geometry, the tip expands.
353

void QToolTip::tip ( const QRect & rect, const QString & text, const QString &

355       groupText, const QRect & geometry ) [protected]
356       This is an overloaded member function, provided for convenience. It
357       behaves essentially like the above function.
358
359       Immediately pops up a tip within the rectangle geometry, saying text
360       and removes the tip once the cursor moves out of rectangle rect.
361       groupText is the text emitted from the group. Both rectangles are given
362       in the coordinate system of the widget this QToolTip relates to.
363
364       The tip will not reappear if the cursor moves back; your maybeTip()
365       must reinstate it each time.
366
367       If the tip does not fit inside geometry, the tip expands.
368
369

SEE ALSO

371       http://doc.trolltech.com/qtooltip.html
372       http://www.trolltech.com/faq/tech.html
373
375       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
376       license file included in the distribution for a complete license
377       statement.
378

AUTHOR

380       Generated automatically from the source code.
381

BUGS

383       If you find a bug in Qt, please report it as described in
384       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
385       help you. Thank you.
386
387       The definitive Qt documentation is provided in HTML format; it is
388       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
389       web browser. This man page is provided as a convenience for those users
390       who prefer man pages, although this format is not officially supported
391       by Trolltech.
392
393       If you find errors in this manual page, please report them to qt-
394       bugs@trolltech.com.  Please include the name of the manual page
395       (qtooltip.3qt) and the Qt version (3.3.8).
396
397
398
399Trolltech AS                    2 February 2007                  QToolTip(3qt)
Impressum