1QToolTip(3qt) QToolTip(3qt)
2
6 QToolTip - Tool tips (balloon help) for any widget or rectangular part
7 of a widget
8
10 #include <qtooltip.h>
11 Inherits Qt.
13 Public Members
15 QToolTip ( QWidget * widget, QToolTipGroup * group = 0 )
16 QWidget * parentWidget () const
17 QToolTipGroup * group () const
18 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 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
52 The QToolTip class provides tool tips (balloon help) for any widget or
53 rectangular part of a widget.
54 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 The tip can be any Rich-Text formatted string.
60 QToolTipGroup provides a way for tool tips to display another text
62 elsewhere (most often in a status bar).
63 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 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 The QToolTip class can be used in three different ways: <ol type=1>
75 1 Adding a tip to an entire widget.
77 2 Adding a tip to a fixed rectangle within a widget.
79 3 Adding a tip to a dynamic rectangle within a widget.
81 To add a tip to a widget, call the static function QToolTip::add() with
83 the widget and tip as arguments:
84 QToolTip::add( quitButton, "Leave the application" );
86 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 QToolTip::remove( quitButton );
92 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 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 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 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 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 Tool tips can be globally disabled using QToolTip::setGloballyEnabled()
119 or disabled in groups with QToolTipGroup::setEnabled().
120 You can retrieve the text of a tooltip for a given position within a
122 widget using textFor().
123 The global tooltip font and palette can be set with the static
125 setFont() and setPalette() functions respectively.
126 See also QStatusBar, QWhatsThis, QToolTipGroup, GUI Design Handbook:
128 Tool Tip, and Help System.
129
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 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 Warning: QToolTip is not a subclass of QObject, so the instance of
140 QToolTip is not deleted when widget is deleted.
141 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 MyToolTip::~MyToolTip()
147 {
148 remove( widget );
149 }
150 See also maybeTip().
152
154 Adds a tool tip to widget. text is the text to be shown in the tool
155 tip.
156 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 Examples:
162
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 Adds a tool tip to widget and to tool tip group group.
169 text is the text shown in the tool tip and longText is the text emitted
171 from group.
172 Normally, longText is shown in a status bar or similar.
174
176 text ) [static]
177 This is an overloaded member function, provided for convenience. It
178 behaves essentially like the above function.
179 Adds a tool tip to a fixed rectangle, rect, within widget. text is the
181 text shown in the tool tip.
182
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 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 text is the text shown in the tool tip and groupText is the text
192 emitted from group.
193 Normally, groupText is shown in a status bar or similar.
195
197 Immediately removes all tool tips for this tooltip's parent widget.
198
200 This function is obsolete. It is provided to keep old source working.
201 We strongly advise against using it in new code.
202
204 Returns the font common to all tool tips.
205 See also setFont().
207
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 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 See also parentWidget() and QToolTipGroup.
217
219 Hides any tip that is currently being shown.
220 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
225 Returns whether tool tips are enabled globally.
226 See also setGloballyEnabled().
228
230 This pure virtual function is half of the most versatile interface
231 QToolTip offers.
232 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 p is given in that widget's local coordinates. Most maybeTip()
241 implementations will be of the form:
242 if ( <something> ) {
244 tip( <something>, <something> );
245 }
246 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 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 See also tip().
256 Examples:
258
260 Returns the palette common to all tool tips.
261 See also setPalette().
263
265 Returns the widget this QToolTip applies to.
266 The tool tip is destroyed automatically when the parent widget is
268 destroyed.
269 See also group().
271
273 Removes the tool tip from widget.
274 If there is more than one tool tip on widget, only the one covering the
276 entire widget is removed.
277
279 This is an overloaded member function, provided for convenience. It
280 behaves essentially like the above function.
281 Removes any tool tip for rect from widget.
283 If there is more than one tool tip on widget, only the one covering
285 rectangle rect is removed.
286
288 This function is obsolete. It is provided to keep old source working.
289 We strongly advise against using it in new code.
290
292 Sets the font for all tool tips to font.
293 See also font().
295
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 By default, tool tips are enabled. Note that this function affects all
301 tool tips in the entire application.
302 See also QToolTipGroup::enabled.
304
306 Sets the palette for all tool tips to palette.
307 See also palette().
309
311 Sets the wakeup delay for all tooltips to i milliseconds.
312
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
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 The tip will not reappear if the cursor moves back; your maybeTip()
324 must reinstate it each time.
325
327 groupText ) [protected]
328 This is an overloaded member function, provided for convenience. It
329 behaves essentially like the above function.
330 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 The tip will not reappear if the cursor moves back; your maybeTip()
337 must reinstate it each time.
338
340 geometry ) [protected]
341 This is an overloaded member function, provided for convenience. It
342 behaves essentially like the above function.
343 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 The tip will not reappear if the cursor moves back; your maybeTip()
350 must reinstate it each time.
351 If the tip does not fit inside geometry, the tip expands.
353
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 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 The tip will not reappear if the cursor moves back; your maybeTip()
365 must reinstate it each time.
366 If the tip does not fit inside geometry, the tip expands.
368
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
380 Generated automatically from the source code.
381
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 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 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).
396Trolltech AS 2 February 2007 QToolTip(3qt)