CopperSpice API  1.9.1
Static Public Methods | List of all members
QWhatsThis Class Reference
CsGui | Help System

Used to provide a simple help description of a widget. More...

Static Public Methods

static QAction * createAction (QObject *parent=nullptr)
 
static void enterWhatsThisMode ()
 
static void hideText ()
 
static bool inWhatsThisMode ()
 
static void leaveWhatsThisMode ()
 
static void showText (const QPoint &pos, const QString &text, QWidget *w=nullptr)
 

Detailed Description

The QWhatsThis class provides a simple description or explanation about the current menu item, tool bar icon, push button, or some other control. This help text is typically longer and more detailed than a tool tip but not as detailed as full documentation. This help is displayed in a pop up window when the user selects the "What's This?" mode and then clicks on a widget object.

Usage

The most common way to activate this help is to move focus to the relevant widget and press Shift+F1. The help text will appear and is then hidden as soon as the user does something else. If there is some other shortcut assigned for Shift+F1 this mechanism will not work.

Some dialogs automatically contain a "?" button where a user can click to enter the "What's This?" mode. The cursor will change to a question mark and then the user simply clicks some widget to pop up the help.

Applications can also provide a menu option or toolbar button which can be used to enter the "What's This?" mode. The following example shows how to call createAction() and add the QAction to a menu and a toolbar.

QMenu *helpMenu = menuBar()->addMenu("Help");
helpMenu->addAction(QWhatsThis::createAction());
QToolBar *helpToolBar = addToolBar("Help Menu");
helpToolBar->addAction(QWhatsThis::createAction());

A program can also enter the "What's This?" mode by calling enterWhatsThisMode(), check the current mode with inWhatsThisMode() and return to a normal mode with leaveWhatsThisMode().

Advanced Usage

If you want to control the "What's This?" behavior of a widget manually refer to Qt::WA_CustomWhatsThis.

It is also possible to show different help texts for different regions of a widget by using a QHelpEvent of type QEvent::WhatsThis. Intercept the help event in your widget's QWidget::event() function and call QWhatsThis::showText() with the text you want to display for the position specified in QHelpEvent::pos(). If the text is rich text and the user clicks on a link, the widget also receives a QWhatsThisClickedEvent with the link's reference as QWhatsThisClickedEvent::href().

If a QWhatsThisClickedEvent is handled and QWidget::event() returns true, the help window remains visible. Call QWhatsThis::hideText() to hide it explicitly.

Example

To add the help text to a widget or an action call QWidget::setWhatsThis() or QAction::setWhatsThis().

The text can be either plain text or rich text. If you specify a rich text formatted string it will be rendered using the default stylesheet, making it possible to embed images in the displayed text. For speed, the default stylesheet uses a simple method to determine whether the text can be rendered as plain text. Refer to Qt::mightBeRichText() for more details.

QAction *openFile = new QAction("Open", this);
openFile->setShortcut(tr("Ctrl+O"));
openFile->setStatusTip(tr("Open a file"));
openFile->setWhatsThis(tr("Click this option to open a file."));
See also
QToolTip

Method Documentation

QAction * QWhatsThis::createAction ( QObject *  parent = nullptr)
static

Returns a QAction used to invoke "What's This?" context help with the given parent.

void QWhatsThis::enterWhatsThisMode ( )
static

This method switches the user interface into the "What's This?" mode. The user interface can be switched into the normal mode by the user input clicking the mouse or pressing Esc. The program can also call leaveWhatsThisMode().

When entering the "What's This?" mode a QEvent of type Qt::EnterWhatsThisMode is sent to all top level widgets.

See also
inWhatsThisMode(), leaveWhatsThisMode()
void QWhatsThis::hideText ( )
static

If a "What's This?" window is currently visible then calling this method hides the window.

See also
showText()
bool QWhatsThis::inWhatsThisMode ( )
static

Returns true if the user interface is in the "What's This?" mode, otherwise returns false.

See also
enterWhatsThisMode()
void QWhatsThis::leaveWhatsThisMode ( )
static

If the user interface is in the "What's This?" mode, then calling this method switches back to normal mode. When leaving "What's This?" mode a QEvent of type Qt::LeaveWhatsThisMode is sent to all top level widgets.

See also
enterWhatsThisMode(), inWhatsThisMode()
void QWhatsThis::showText ( const QPoint &  pos,
const QString &  text,
QWidget *  w = nullptr 
)
static

Shows the text in a "What's This?" window at global position pos. If provided, the argument w is used to determine the appropriate screen on multi-head systems.

See also
hideText()