Classes - Annotated - Tree - Functions - Home - Structure

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

Static Public Members


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 system that provides users with information about functionality, usage, background etc. in various levels of detail between tool tips and full text browsing windows.

QWhatsThis provides a single window with a single explanatory text which 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. To assign text to a menu item, call QMenuData::setWhatsThis(); for a global accelerator key, call QAccel::setWhatsThis() and If you're using actions QAction::setWhatsThis() does the job.

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.

        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 );

(For an exhaustive explanation of the above code refer to the Simple Application Walkthrough featuring QAction.)

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 below picture the first one from the right) the user switches into What's this? mode. If now he or she clicks on a widget the appropriate help text is shown. The mode is left when help is given or when the user presses the Escape key.

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.

If you wish to control the What's This? behaviour of a widget manually see QWidget::customWhatsThis().

Added help text might be removed using QWhatsThis::remove(). This is however rarely needed because the text is automatically removed as soon as the widget is destroyed.

See also QToolTip.


Member Function Documentation

QWhatsThis::QWhatsThis ( QWidget * widget )

Constructs a dynamic What's This? object for widget. The object is deleted when the passed 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 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: application/application.cpp and mdi/application.cpp.

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

Display text in a help window at the global screen position pos.

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 switches out of 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 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 of this 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, 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 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 a 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 text for widget w or a null string if there is no What's This? help for widget.

If includeParents is TRUE, parent widgets are taken into consideration as well.

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 );
  

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


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


Copyright © 2001 TrolltechTrademarks
Qt version 3.0.0-beta1-beta1