1QWhatsThis(3qt) QWhatsThis(3qt)
2
6 QWhatsThis - Simple description of any widget, i.e. answering the
7 question "What's this?"
8
10 #include <qwhatsthis.h>
11 Inherits Qt.
13 Public Members
15 QWhatsThis ( QWidget * widget )
16 virtual ~QWhatsThis ()
17 virtual QString text ( const QPoint & )
18 virtual bool clicked ( const QString & href )
19 Static Public Members
21 void setFont ( const QFont & font )
22 void add ( QWidget * widget, const QString & text )
23 void remove ( QWidget * widget )
24 QString textFor ( QWidget * w, const QPoint & pos = QPoint ( ), bool
25 includeParents = FALSE )
26 QToolButton * whatsThisButton ( QWidget * parent )
27 void enterWhatsThisMode ()
28 bool inWhatsThisMode ()
29 void leaveWhatsThisMode ( const QString & text = QString::null, const
30 QPoint & pos = QCursor::pos ( ), QWidget * w = 0 )
31 void display ( const QString & text, const QPoint & pos = QCursor::pos
32 ( ), QWidget * w = 0 )
33
35 The QWhatsThis class provides a simple description of any widget, i.e.
36 answering the question "What's this?".
37 What's this?" help is part of an application's online help system that
39 provides users with information about functionality, usage, background
40 etc., in various levels of detail from short tool tips to full text
41 browsing help windows.
42 QWhatsThis provides a single window with an explanatory text that pops
44 up when the user asks "What's this?". The default way to do this is to
45 focus the relevant widget and press Shift+F1. The help text appears
46 immediately; it goes away as soon as the user does something else.
47 (Note that if there is an accelerator for Shift+F1, this mechanism will
49 not work.)
50 To add "What's this?" text to a widget you simply call
52 QWhatsThis::add() for the widget. For example, to assign text to a menu
53 item, call QMenuData::setWhatsThis(); for a global accelerator key,
54 call QAccel::setWhatsThis() and If you're using actions, use
55 QAction::setWhatsThis().
56 The text can be either rich text or plain text. If you specify a rich
58 text formatted string, it will be rendered using the default
59 stylesheet. This makes it possible to embed images. See
60 QStyleSheet::defaultSheet() for details.
61 const char * fileOpenText = "<p><img source=\"fileopen\"> "
63 "Click this button to open a <em>new file</em>. <br>"
64 "You can also select the <b>Open</b> command "
65 "from the <b>File</b> menu.</p>";
66 QMimeSourceFactory::defaultFactory()->setPixmap( "fileopen",
67 fileOpenAction->iconSet().pixmap() );
68 fileOpenAction->setWhatsThis( fileOpenText );
69 An alternative way to enter "What's this?" mode is to use the ready-
71 made tool bar tool button from QWhatsThis::whatsThisButton(). By
72 invoking this context help button (in the picture below the first one
73 from the right) the user switches into "What's this?" mode. If they now
74 click on a widget the appropriate help text is shown. The mode is left
75 when help is given or when the user presses Esc.
76 <center>
78 [Image Omitted]
79 </center>
81 If you are using QMainWindow you can also use the
83 QMainWindow::whatsThis() slot to invoke the mode from a menu item.
84 For more control you can create a dedicated QWhatsThis object for a
86 special widget. By subclassing and reimplementing QWhatsThis::text() it
87 is possible to have different help texts, depending on the position of
88 the mouse click. By reimplementing QWhatsThis::clicked() it is possible
89 to have hyperlinks inside the help texts.
90 If you wish to control the "What's this?" behavior of a widget manually
92 see QWidget::customWhatsThis().
93 The What's This object can be removed using QWhatsThis::remove(),
95 although this is rarely necessary because it is automatically removed
96 when the widget is destroyed.
97 See also QToolTip and Help System.
99
102 Constructs a dynamic "What's this?" object for widget. The object is
103 deleted when the widget is destroyed.
104 When the widget is queried by the user the text() function of this
106 QWhatsThis will be called to provide the appropriate text, rather than
107 using the text assigned by add().
108
110 Destroys the object and frees any allocated resources.
111
113 Adds text as "What's this" help for widget. If the text is rich text
114 formatted (i.e. it contains markup) it will be rendered with the
115 default stylesheet QStyleSheet::defaultSheet().
116 The text is destroyed if the widget is later destroyed, so it need not
118 be explicitly removed.
119 See also remove().
121 Examples:
123
125 This virtual function is called when the user clicks inside the" What's
126 this?" window. href is the link the user clicked on, or QString::null
127 if there was no link.
128 If the function returns TRUE (the default), the "What's this?" window
130 is closed, otherwise it remains visible.
131 The default implementation ignores href and returns TRUE.
133
135 QCursor::pos ( ), QWidget * w = 0 ) [static]
136 Display text in a help window at the global screen position pos.
137 If widget w is not 0 and has its own dedicated QWhatsThis object, this
139 object will receive clicked() messages when the user clicks on
140 hyperlinks inside the help text.
141 See also QWhatsThis::clicked().
143
145 Enters "What's this?" mode and returns immediately.
146 Qt will install a special cursor and take over mouse input until the
148 user clicks somewhere. It then shows any help available and ends
149 "What's this?" mode. Finally, Qt removes the special cursor and help
150 window and then restores ordinary event processing, at which point the
151 left mouse button is no longer pressed.
152 The user can also use the Esc key to leave "What's this?" mode.
154 See also inWhatsThisMode() and leaveWhatsThisMode().
156
158 Returns TRUE if the application is in "What's this?" mode; otherwise
159 returns FALSE.
160 See also enterWhatsThisMode() and leaveWhatsThisMode().
162
164 const QPoint & pos = QCursor::pos ( ), QWidget * w = 0 ) [static]
165 Leaves "What's this?" question mode.
166 This function is used internally by widgets that support
168 QWidget::customWhatsThis(); applications do not usually call it. An
169 example of such a widget is QPopupMenu: menus still work normally in
170 "What's this?" mode but also provide help texts for individual menu
171 items.
172 If text is not QString::null, a "What's this?" help window is displayed
174 at the global screen position pos. If widget w is not 0 and has its own
175 dedicated QWhatsThis object, this object will receive clicked()
176 messages when the user clicks on hyperlinks inside the help text.
177 See also inWhatsThisMode(), enterWhatsThisMode(), and
179 QWhatsThis::clicked().
180
182 Removes the "What's this?" help associated with the widget. This
183 happens automatically if the widget is destroyed.
184 See also add().
186
188 Sets the font for all "What's this?" helps to font.
189
191 This virtual function returns the text for position p in the widget
192 that this "What's this?" object documents. If there is no" What's
193 this?" text for the position, QString::null is returned.
194 The default implementation returns QString::null.
196
198 bool includeParents = FALSE ) [static]
199 Returns the what's this text for widget w or QString::null if there is
200 no "What's this?" help for the widget. pos contains the mouse position;
201 this is useful, for example, if you've subclassed to make the text that
202 is displayed position dependent.
203 If includeParents is TRUE, parent widgets are taken into consideration
205 as well when looking for what's this help text.
206 See also add().
208
210 Creates a QToolButton preconfigured to enter "What's this?" mode when
211 clicked. You will often use this with a tool bar as parent:
212 (void) QWhatsThis::whatsThisButton( my_help_tool_bar );
214 Example: helpsystem/mainwindow.cpp.
216
219 http://doc.trolltech.com/qwhatsthis.html
220 http://www.trolltech.com/faq/tech.html
221
223 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
224 license file included in the distribution for a complete license
225 statement.
226
228 Generated automatically from the source code.
229
231 If you find a bug in Qt, please report it as described in
232 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
233 help you. Thank you.
234 The definitive Qt documentation is provided in HTML format; it is
236 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
237 web browser. This man page is provided as a convenience for those users
238 who prefer man pages, although this format is not officially supported
239 by Trolltech.
240 If you find errors in this manual page, please report them to qt-
242 bugs@trolltech.com. Please include the name of the manual page
243 (qwhatsthis.3qt) and the Qt version (3.3.8).
244Trolltech AS 2 February 2007 QWhatsThis(3qt)