QWhatsThis Class Reference

The QWhatsThis class provides a simple description of any widget, e.g. answering the question "what's this?" More...

#include <qwhatsthis.h>

Inherits Qt.

List of all member functions.

Public Members

• QWhatsThis ( QWidget * ) 
• virtual ~QWhatsThis () 
• virtual QString text ( const QPoint & ) 

Static Public Members

• void add ( QWidget *, const QString & ) 
• void remove ( QWidget * ) 
• QString textFor ( QWidget *, const QPoint & pos = QPoint ()) 
• QToolButton* whatsThisButton ( QWidget * parent ) 
• void enterWhatsThisMode () 
• bool inWhatsThisMode () 
• void leaveWhatsThisMode ( const QString & = QString::null, const QPoint & pos = QCursor::pos ()) 

Detailed Description

What's This help is part of an application's online help systems, offering users a level of detail between tool tips and full text browsing windows.

QWhatsThis provides a single window with a single explanatory text, which pops up quickly when the user asks "what's this?", and goes away as soon as the user does something else.

To assign What's This? text to a widget, you simply call QWhatsThis::add() for the widget. To assign text to a menu item, call QMenuData::setWhatsThis(), and for a global accelerator key, call QAccel::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 also possible to embed images. See QStyleSheet::defaultSheet() for details.

By default, the user will be able to view the text for a widget by pressing Shift-F1 while the widget has focus. On window systems where a context help button is provided in the window decorations, that button enters What's This? mode. In this mode, if the user clicks on a widget, help will be given for the widget. The mode is left when help is given or when the user presses the Escape key.

An alternative way to enter What's This? mode is to use the ready-made toolbar tool button from QWhatsThis::whatsThisButton(). 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 explanatory texts depending on the position of the mouse click.

If your widget needs even more control, see QWidget::customWhatsThis().

To remove added text, you can use QWhatsThis::remove(), but since the text is automatically removed when the widget is destroyed, this is rarely needed.

See also QToolTip.

Member Function Documentation

QWhatsThis::QWhatsThis ( QWidget * widget )

Constructs a dynamic What's This object for widget.

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 text assigned by add().

QWhatsThis::~QWhatsThis () [virtual]

Destructs 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 (ie. it contains markup), it will be rendered with the default stylesheet QStyleSheet::defaultSheet().

The text is destroyed if the widget is later destroyed and so need not be explicitly removed.

See also remove().

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, then show any help available and switch out of What's This mode. Finally, Qt removes the special cursor and help window then restores ordinary event processing, at which point the left mouse button is not pressed.

The user can also use the Escape key to leave What's This? mode.

See also inWhatsThisMode() and leaveWhatsThisMode().

bool QWhatsThis::inWhatsThisMode () [static]

Returns whether the application is in What's This mode.

See also enterWhatsThisMode() and leaveWhatsThisMode().

void QWhatsThis::leaveWhatsThisMode ( const QString & text = QString::null, const QPoint & pos = QCursor::pos ()) [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 for such a kind of widget is QPopupMenu: Menus still work normally in What's This mode, but provide help texts for single menu items instead.

If text is not a null string, then a What's This help window is displayed at the global screen position pos.

See also inWhatsThisMode() and enterWhatsThisMode().

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

Removes the What's This help for widget. This happens automatically if the widget is destroyed.

See also add().

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

This virtual functions 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 a position, QString::null is returned.

The default implementation returns QString::null.

QString QWhatsThis::textFor ( QWidget * widget, const QPoint & pos = QPoint ()) [static]

Returns the text for widget, or a null string if there is no What's This help for widget.

See also add().

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

Creates a QToolButton pre-configured to enter What's This mode when clicked. You will often use this with a toolbar:

     (void)QWhatsThis::whatsThisButton( my_help_tool_bar );

Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):

This file is part of the Qt toolkit, copyright © 1995-2005 Trolltech, all rights reserved.