1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix documentation of QAction's text property

Browse Source 
The text of an action is used as the tooltip and iconText unless those
are explicitly set, and only then does an '&' mnemonic get stripped.
An '&' in the text will generate mnemonic shortcuts in some UI controls,
such as menubars, menus, or buttons. Document that in the text property,
and add a see-also from the constructor to the relevant properties.

As a drive-by, reduce the usage of "widget" in the documentation.
QAction now lives in QtGui and can be used by both widget and Qt Quick
UIs.

Fixes: QTBUG-109060
Fixes: QTBUG-109061
Change-Id: I5e7c2a01b8029f519d7050187e486b667d3cd52b
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit f546f3700b376fb25de38958e0ab2ca880f9629a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This commit is contained in:
Volker Hilsheimer 2022-12-02 17:03:42 +01:00 committed by Qt Cherry-pick Bot
parent da7283eddc
commit c5544de393
1 changed files with 27 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
src/gui/kernel/qaction.cpp
View File

@ -150,17 +150,18 @@ QObject *QActionPrivate::menu() const
user interface used, it is useful to represent each command as user interface used, it is useful to represent each command as
an \e action. an \e action.
Actions can be added to menus and toolbars, and will Actions can be added to user interface elements such as menus and toolbars,
automatically keep them in sync. For example, in a word processor, and will automatically keep the UI in sync. For example, in a word
if the user presses a Bold toolbar button, the Bold menu item processor, if the user presses a Bold toolbar button, the Bold menu item
will automatically be checked. will automatically be checked.
A QAction may contain an icon, menu text, a shortcut, status text, A QAction may contain an icon, descriptive text, icon text, a keyboard
"What's This?" text, and a tooltip. Most of these can be set in shortcut, status text, "What's This?" text, and a tooltip. All properties
the constructor. They can also be set independently with can be set independently with setIcon(), setText(), setIconText(),
setIcon(), setText(), setIconText(), setShortcut(), setShortcut(), setStatusTip(), setWhatsThis(), and setToolTip(). Icon and
setStatusTip(), setWhatsThis(), and setToolTip(). For menu items, text, as the two most important properties, can also be set in the
it is possible to set an individual font with setFont(). constructor. It's possible to set an individual font with setFont(), which
e.g. menus respect when displaying the action as a menu item.
We recommend that actions are created as children of the window We recommend that actions are created as children of the window
they are used in. In most cases actions will be children of they are used in. In most cases actions will be children of
@ -238,13 +239,11 @@ QAction::QAction(QObject *parent)
parent is an action group the action will be automatically parent is an action group the action will be automatically
inserted into the group. inserted into the group.
The action uses a stripped version of \a text (e.g. "\&Menu A stripped version of \a text (for example, "\&Menu Option..." becomes
Option..." becomes "Menu Option") as descriptive text for "Menu Option") will be used for tooltips and icon text unless you specify a
tool buttons. You can override this by setting a specific different text using setToolTip() or setIconText(), respectively.
description with setText(). The same text will be used for
tooltips unless you specify a different text using
setToolTip().
\sa text
*/ */
QAction::QAction(const QString &text, QObject *parent) QAction::QAction(const QString &text, QObject *parent)
: QAction(parent) : QAction(parent)
@ -258,12 +257,11 @@ QAction::QAction(const QString &text, QObject *parent)
parent. If \a parent is an action group the action will be parent. If \a parent is an action group the action will be
automatically inserted into the group. automatically inserted into the group.
The action uses a stripped version of \a text (e.g. "\&Menu A stripped version of \a text (for example, "\&Menu Option..." becomes
Option..." becomes "Menu Option") as descriptive text for "Menu Option") will be used for tooltips and icon text unless you specify a
tool buttons. You can override this by setting a specific different text using setToolTip() or setIconText(), respectively.
description with setText(). The same text will be used for
tooltips unless you specify a different text using \sa text, icon
setToolTip().
*/ */
QAction::QAction(const QIcon &icon, const QString &text, QObject *parent) QAction::QAction(const QIcon &icon, const QString &text, QObject *parent)
: QAction(text, parent) : QAction(text, parent)
@ -602,6 +600,14 @@ bool QAction::isSeparator() const
by using setText(), the action's description icon text will be by using setText(), the action's description icon text will be
used as text. There is no default text. used as text. There is no default text.
Certain UI elements, such as menus or buttons, can use '&' in front of a
character to automatically create a mnemonic (a shortcut) for that
character. For example, "&File" for a menu will create the shortcut
\uicontrol Alt+F, which will open the File menu. "E&xit" will create the
shortcut \uicontrol Alt+X for a button, or in a menu allow navigating to
the menu item by pressing "x". (use '&&' to display an actual ampersand).
The widget might consume and perform an action on a given shortcut.
\sa iconText \sa iconText
*/ */
void QAction::setText(const QString &text) void QAction::setText(const QString &text)