QAction Class

Property Documentation

autoRepeat : bool

This property holds whether the action can auto repeat

If true, the action will auto repeat when the keyboard shortcut combination is held down, provided that keyboard auto repeat is enabled on the system. The default value is true.

Access functions:

Notifier signal:

checkable : bool

This property holds whether the action is a checkable action

A checkable action is one which has an on/off state. For example, in a word processor, a Bold toolbar button may be either on or off. An action which is not a toggle action is a command action; a command action is simply executed, e.g. file save. By default, this property is false.

In some situations, the state of one toggle action should depend on the state of others. For example, "Left Align", "Center" and "Right Align" toggle actions are mutually exclusive. To achieve exclusive toggling, add the relevant toggle actions to a QActionGroup with the QActionGroup::exclusive property set to true.

Access functions:

Notifier signal:

See also setChecked().

checked : bool

This property holds whether the action is checked.

Only checkable actions can be checked. By default, this is false (the action is unchecked).

Access functions:

Notifier signal:

See also checkable and toggled().

enabled : bool

This property holds whether the action is enabled

Disabled actions cannot be chosen by the user. They do not disappear from menus or toolbars, but they are displayed in a way which indicates that they are unavailable. For example, they might be displayed using only shades of gray.

What's This? help on disabled actions is still available, provided that the QAction::whatsThis property is set.

An action will be disabled when all widgets to which it is added (with QWidget::addAction()) are disabled or not visible. When an action is disabled, it is not possible to trigger it through its shortcut.

By default, this property is true (actions are enabled).

Access functions:

Notifier signal:

See also text.

font : QFont

This property holds the action's font

The font property is used to render the text set on the QAction. The font can be considered a hint as it will not be consulted in all cases based upon application and style.

By default, this property contains the application's default font.

Access functions:

Notifier signal:

See also setText().

icon : QIcon

This property holds the action's icon

In toolbars, the icon is used as the tool button icon; in menus, it is displayed to the left of the menu text, as long as QAction::iconVisibleInMenu returns true.

There is no default icon.

If a null icon (QIcon::isNull()) is passed into this function, the icon of the action is cleared.

Access functions:

Notifier signal:

iconText : QString

This property holds the action's descriptive icon text

If QToolBar::toolButtonStyle is set to a value that permits text to be displayed, the text defined held in this property appears as a label in the relevant tool button.

It also serves as the default text in menus and tooltips if the action has not been defined with setText() or setToolTip(), and will also be used in toolbar buttons if no icon has been defined using setIcon().

If the icon text is not explicitly set, the action's normal text will be used for the icon text.

By default, this property contains an empty string.

Access functions:

Notifier signal:

See also setToolTip() and setStatusTip().

iconVisibleInMenu : bool

This property holds whether or not an action should show an icon in a menu

In some applications, it may make sense to have actions with icons in the toolbar, but not in menus. If true, the icon (if valid) is shown in the menu, when it is false, it is not shown.

The default is to follow whether the Qt::AA_DontShowIconsInMenus attribute is set for the application. Explicitly settings this property overrides the presence (or absence) of the attribute.

For example:

QApplication app(argc, argv);
app.setAttribute(Qt::AA_DontShowIconsInMenus);  // Icons are *no longer shown* in menus
// ...
QAction *myAction = new QAction();
// ...
myAction->setIcon(SomeIcon);
myAction->setIconVisibleInMenu(true);   // Icon *will* be shown in menus for *this* action.

Access functions:

Notifier signal:

See also icon and QCoreApplication::setAttribute().

menuRole : MenuRole

This property holds the action's menu role

This indicates what role the action serves in the application menu on macOS. By default all actions have the TextHeuristicRole, which means that the action is added based on its text (see QMenuBar for more information).

The menu role can only be changed before the actions are put into the menu bar in macOS (usually just before the first application window is shown).

Access functions:

Notifier signal:

priority : Priority

This property holds the actions's priority in the user interface.

This property can be set to indicate how the action should be prioritized in the user interface.

For instance, when toolbars have the Qt::ToolButtonTextBesideIcon mode set, then actions with LowPriority will not show the text labels.

Access functions:

Notifier signal:

shortcut : QKeySequence

This property holds the action's primary shortcut key

Valid keycodes for this property can be found in Qt::Key and Qt::Modifier. There is no default shortcut key.

Access functions:

Notifier signal:

shortcutContext : Qt::ShortcutContext

This property holds the context for the action's shortcut

Valid values for this property can be found in Qt::ShortcutContext. The default value is Qt::WindowShortcut.

Access functions:

Notifier signal:

shortcutVisibleInContextMenu : bool

This property holds whether or not an action should show a shortcut in a context menu

In some applications, it may make sense to have actions with shortcuts in context menus. If true, the shortcut (if valid) is shown when the action is shown via a context menu, when it is false, it is not shown.

The default is to follow whether the Qt::AA_DontShowShortcutsInContextMenus attribute is set for the application. Explicitly setting this property overrides the attribute.

Access functions:

Notifier signal:

See also shortcut and QCoreApplication::setAttribute().

statusTip : QString

This property holds the action's status tip

The status tip is displayed on all status bars provided by the action's top-level parent widget.

By default, this property contains an empty string.

Access functions:

Notifier signal:

See also setToolTip() and showStatusText().

text : QString

This property holds the action's descriptive text

If the action is added to a menu, the menu option will consist of the icon (if there is one), the text, and the shortcut (if there is one). If the text is not explicitly set in the constructor, or by using setText(), the action's description icon text will be 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 Alt+F, which will open the File menu. "E&xit" will create the shortcut 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.

Access functions:

Notifier signal:

See also iconText.

toolTip : QString

This property holds the action's tooltip

This text is used for the tooltip. If no tooltip is specified, the action's text is used.

By default, this property contains the action's text.

Access functions:

Notifier signal:

See also setStatusTip() and setShortcut().

visible : bool

This property holds whether the action can be seen (e.g. in menus and toolbars)

If visible is true the action can be seen (e.g. in menus and toolbars) and chosen by the user; if visible is false the action cannot be seen or chosen by the user.

Actions which are not visible are not grayed out; they do not appear at all.

By default, this property is true (actions are visible).

Access functions:

Notifier signal:

whatsThis : QString

This property holds the action's "What's This?" help text

The "What's This?" text is used to provide a brief description of the action. The text may contain rich text. There is no default "What's This?" text.

Access functions:

Notifier signal:

See also QWhatsThis.