Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

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 * widget )
• virtual ~QWhatsThis ()
• virtual QString text ( const QPoint & )

Static Public Members

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

Detailed Description

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

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 )

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]

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

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

See also remove().

void QWhatsThis::enterWhatsThisMode () [static]

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]

See also enterWhatsThisMode() and leaveWhatsThisMode().

void QWhatsThis::leaveWhatsThisMode ( const QString & text = QString::null, const QPoint & pos = QCursor::pos ( ) ) [static]

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]

See also add().

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

The default implementation returns QString::null.

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

See also add().

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

     (void)QWhatsThis::whatsThisButton( my_help_tool_bar );
  

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