1QWhatsThis(3qt)                                                QWhatsThis(3qt)
2
3
4

NAME

6       QWhatsThis - Simple description of any widget, i.e. answering the
7       question "What's this?"
8

SYNOPSIS

10       #include <qwhatsthis.h>
11
12       Inherits Qt.
13
14   Public Members
15       QWhatsThis ( QWidget * widget )
16       virtual ~QWhatsThis ()
17       virtual QString text ( const QPoint & )
18       virtual bool clicked ( const QString & href )
19
20   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

DESCRIPTION

35       The QWhatsThis class provides a simple description of any widget, i.e.
36       answering the question "What's this?".
37
38       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
43       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
48       (Note that if there is an accelerator for Shift+F1, this mechanism will
49       not work.)
50
51       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
57       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
62               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
70       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
77       <center>
78                                   [Image Omitted]
79
80       </center>
81
82       If you are using QMainWindow you can also use the
83       QMainWindow::whatsThis() slot to invoke the mode from a menu item.
84
85       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
91       If you wish to control the "What's this?" behavior of a widget manually
92       see QWidget::customWhatsThis().
93
94       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
98       See also QToolTip and Help System.
99

MEMBER FUNCTION DOCUMENTATION

QWhatsThis::QWhatsThis ( QWidget * widget )

102       Constructs a dynamic "What's this?" object for widget. The object is
103       deleted when the widget is destroyed.
104
105       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

QWhatsThis::~QWhatsThis () [virtual]

110       Destroys the object and frees any allocated resources.
111

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

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
117       The text is destroyed if the widget is later destroyed, so it need not
118       be explicitly removed.
119
120       See also remove().
121
122       Examples:
123

bool QWhatsThis::clicked ( const QString & href ) [virtual]

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
129       If the function returns TRUE (the default), the "What's this?" window
130       is closed, otherwise it remains visible.
131
132       The default implementation ignores href and returns TRUE.
133

void QWhatsThis::display ( const QString & text, const QPoint & pos =

135       QCursor::pos ( ), QWidget * w = 0 ) [static]
136       Display text in a help window at the global screen position pos.
137
138       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
142       See also QWhatsThis::clicked().
143

void QWhatsThis::enterWhatsThisMode () [static]

145       Enters "What's this?" mode and returns immediately.
146
147       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
153       The user can also use the Esc key to leave "What's this?" mode.
154
155       See also inWhatsThisMode() and leaveWhatsThisMode().
156

bool QWhatsThis::inWhatsThisMode () [static]

158       Returns TRUE if the application is in "What's this?" mode; otherwise
159       returns FALSE.
160
161       See also enterWhatsThisMode() and leaveWhatsThisMode().
162

void QWhatsThis::leaveWhatsThisMode ( const QString & text = QString::null,

164       const QPoint & pos = QCursor::pos ( ), QWidget * w = 0 ) [static]
165       Leaves "What's this?" question mode.
166
167       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
173       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
178       See also inWhatsThisMode(), enterWhatsThisMode(), and
179       QWhatsThis::clicked().
180

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

182       Removes the "What's this?" help associated with the widget. This
183       happens automatically if the widget is destroyed.
184
185       See also add().
186

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

188       Sets the font for all "What's this?" helps to font.
189

QString QWhatsThis::text ( const QPoint & ) [virtual]

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
195       The default implementation returns QString::null.
196

QString QWhatsThis::textFor ( QWidget * w, const QPoint & pos = QPoint ( ),

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
204       If includeParents is TRUE, parent widgets are taken into consideration
205       as well when looking for what's this help text.
206
207       See also add().
208

QToolButton * QWhatsThis::whatsThisButton ( QWidget * parent ) [static]

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
213               (void) QWhatsThis::whatsThisButton( my_help_tool_bar );
214
215       Example: helpsystem/mainwindow.cpp.
216
217

SEE ALSO

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

AUTHOR

228       Generated automatically from the source code.
229

BUGS

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
235       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
241       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).
244
245
246
247Trolltech AS                    2 February 2007                QWhatsThis(3qt)
Impressum