QWhatsThis(3qt)QWhatsThis(3qt)NAME
QWhatsThis - Simple description of any widget, i.e. answering the
question "What's this?"
SYNOPSIS
#include <qwhatsthis.h>
Inherits Qt.
Public Members
QWhatsThis ( QWidget * widget )
virtual ~QWhatsThis ()
virtual QString text ( const QPoint & )
virtual bool clicked ( const QString & href )
Static Public Members
void setFont ( const QFont & font )
void add ( QWidget * widget, const QString & text )
void remove ( QWidget * widget )
QString textFor ( QWidget * w, const QPoint & pos = QPoint ( ), bool
includeParents = FALSE )
QToolButton * whatsThisButton ( QWidget * parent )
void enterWhatsThisMode ()
bool inWhatsThisMode ()
void leaveWhatsThisMode ( const QString & text = QString::null, const
QPoint & pos = QCursor::pos ( ), QWidget * w = 0 )
void display ( const QString & text, const QPoint & pos = QCursor::pos
( ), QWidget * w = 0 )
DESCRIPTION
The QWhatsThis class provides a simple description of any widget, i.e.
answering the question "What's this?".
What's this?" help is part of an application's online help system that
provides users with information about functionality, usage, background
etc., in various levels of detail from short tool tips to full text
browsing help windows.
QWhatsThis provides a single window with an explanatory text that pops
up when the user asks "What's this?". The default way to do this is to
focus the relevant widget and press Shift+F1. The help text appears
immediately; it goes away as soon as the user does something else.
(Note that if there is an accelerator for Shift+F1, this mechanism will
not work.)
To add "What's this?" text to a widget you simply call
QWhatsThis::add() for the widget. For example, to assign text to a menu
item, call QMenuData::setWhatsThis(); for a global accelerator key,
call QAccel::setWhatsThis() and If you're using actions, use
QAction::setWhatsThis().
The text can be either rich text or plain text. If you specify a rich
text formatted string, it will be rendered using the default
stylesheet. This makes it possible to embed images. See
QStyleSheet::defaultSheet() for details.
const char * fileOpenText = "<p><img source=\"fileopen\"> "
"Click this button to open a <em>new file</em>. <br>"
"You can also select the <b>Open</b> command "
"from the <b>File</b> menu.</p>";
QMimeSourceFactory::defaultFactory()->setPixmap( "fileopen",
fileOpenAction->iconSet().pixmap() );
fileOpenAction->setWhatsThis( fileOpenText );
An alternative way to enter "What's this?" mode is to use the ready-
made tool bar tool button from QWhatsThis::whatsThisButton(). By
invoking this context help button (in the picture below the first one
from the right) the user switches into "What's this?" mode. If they now
click on a widget the appropriate help text is shown. The mode is left
when help is given or when the user presses Esc.
<center>
[Image Omitted]
</center>
If you are using QMainWindow you can also use the
QMainWindow::whatsThis() slot to invoke the mode from a menu item.
For more control you can create a dedicated QWhatsThis object for a
special widget. By subclassing and reimplementing QWhatsThis::text() it
is possible to have different help texts, depending on the position of
the mouse click. By reimplementing QWhatsThis::clicked() it is possible
to have hyperlinks inside the help texts.
If you wish to control the "What's this?" behavior of a widget manually
see QWidget::customWhatsThis().
The What's This object can be removed using QWhatsThis::remove(),
although this is rarely necessary because it is automatically removed
when the widget is destroyed.
See also QToolTip and Help System.
MEMBER FUNCTION DOCUMENTATIONQWhatsThis::QWhatsThis ( QWidget * widget )
Constructs a dynamic "What's this?" object for widget. The object is
deleted when the widget is destroyed.
When the widget is queried by the user the text() function of this
QWhatsThis will be called to provide the appropriate text, rather than
using the text assigned by add().
QWhatsThis::~QWhatsThis () [virtual]
Destroys the object and frees any allocated resources.
void QWhatsThis::add ( QWidget * widget, const QString & text ) [static]
Adds text as "What's this" help for widget. If the text is rich text
formatted (i.e. it contains markup) it will be rendered with the
default stylesheet QStyleSheet::defaultSheet().
The text is destroyed if the widget is later destroyed, so it need not
be explicitly removed.
See also remove().
Examples:
bool QWhatsThis::clicked ( const QString & href ) [virtual]
This virtual function is called when the user clicks inside the" What's
this?" window. href is the link the user clicked on, or QString::null
if there was no link.
If the function returns TRUE (the default), the "What's this?" window
is closed, otherwise it remains visible.
The default implementation ignores href and returns TRUE.
void QWhatsThis::display ( const QString & text, const QPoint & pos =
QCursor::pos ( ), QWidget * w = 0 ) [static]
Display text in a help window at the global screen position pos.
If widget w is not 0 and has its own dedicated QWhatsThis object, this
object will receive clicked() messages when the user clicks on
hyperlinks inside the help text.
See also QWhatsThis::clicked().
void QWhatsThis::enterWhatsThisMode () [static]
Enters "What's this?" mode and returns immediately.
Qt will install a special cursor and take over mouse input until the
user clicks somewhere. It then shows any help available and ends
"What's this?" mode. Finally, Qt removes the special cursor and help
window and then restores ordinary event processing, at which point the
left mouse button is no longer pressed.
The user can also use the Esc key to leave "What's this?" mode.
See also inWhatsThisMode() and leaveWhatsThisMode().
bool QWhatsThis::inWhatsThisMode () [static]
Returns TRUE if the application is in "What's this?" mode; otherwise
returns FALSE.
See also enterWhatsThisMode() and leaveWhatsThisMode().
void QWhatsThis::leaveWhatsThisMode ( const QString & text = QString::null,
const QPoint & pos = QCursor::pos ( ), QWidget * w = 0 ) [static]
Leaves "What's this?" question mode.
This function is used internally by widgets that support
QWidget::customWhatsThis(); applications do not usually call it. An
example of such a widget is QPopupMenu: menus still work normally in
"What's this?" mode but also provide help texts for individual menu
items.
If text is not QString::null, a "What's this?" help window is displayed
at the global screen position pos. If widget w is not 0 and has its own
dedicated QWhatsThis object, this object will receive clicked()
messages when the user clicks on hyperlinks inside the help text.
See also inWhatsThisMode(), enterWhatsThisMode(), and
QWhatsThis::clicked().
void QWhatsThis::remove ( QWidget * widget ) [static]
Removes the "What's this?" help associated with the widget. This
happens automatically if the widget is destroyed.
See also add().
void QWhatsThis::setFont ( const QFont & font ) [static]
Sets the font for all "What's this?" helps to font.
QString QWhatsThis::text ( const QPoint & ) [virtual]
This virtual function returns the text for position p in the widget
that this "What's this?" object documents. If there is no" What's
this?" text for the position, QString::null is returned.
The default implementation returns QString::null.
QString QWhatsThis::textFor ( QWidget * w, const QPoint & pos = QPoint ( ),
bool includeParents = FALSE ) [static]
Returns the what's this text for widget w or QString::null if there is
no "What's this?" help for the widget. pos contains the mouse position;
this is useful, for example, if you've subclassed to make the text that
is displayed position dependent.
If includeParents is TRUE, parent widgets are taken into consideration
as well when looking for what's this help text.
See also add().
QToolButton * QWhatsThis::whatsThisButton ( QWidget * parent ) [static]
Creates a QToolButton preconfigured to enter "What's this?" mode when
clicked. You will often use this with a tool bar as parent:
(void) QWhatsThis::whatsThisButton( my_help_tool_bar );
Example: helpsystem/mainwindow.cpp.
SEE ALSO
http://doc.trolltech.com/qwhatsthis.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
license file included in the distribution for a complete license
statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports help us to
help you. Thank you.
The definitive Qt documentation is provided in HTML format; it is
located at $QTDIR/doc/html and can be read using Qt Assistant or with a
web browser. This man page is provided as a convenience for those users
who prefer man pages, although this format is not officially supported
by Trolltech.
If you find errors in this manual page, please report them to qt-
bugs@trolltech.com. Please include the name of the manual page
(qwhatsthis.3qt) and the Qt version (3.3.8).
Trolltech AS 2 February 2007 QWhatsThis(3qt)