QAction Class▲

  • Header: QAction

  • Since: Qt 6.0

  • CMake:

    find_package(Qt6 REQUIRED COMPONENTS Gui)

    target_link_libraries(mytarget PRIVATE Qt6::Gui)

  • qmake: QT += gui

  • Inherits: QObject

  • Inherited By: QWidgetAction

Detailed Description▲

In applications many common commands can be invoked via menus, toolbar buttons, and keyboard shortcuts. Since the user expects each command to be performed in the same way, regardless of the user interface used, it is useful to represent each command as an action.

Actions can be added to user interface elements such as menus and toolbars, and will automatically keep the UI in sync. For example, in a word processor, if the user presses a Bold toolbar button, the Bold menu item will automatically be checked.

A QAction may contain an icon, descriptive text, icon text, a keyboard shortcut, status text, "What's This?" text, and a tooltip. All properties can be set independently with setIcon(), setText(), setIconText(), setShortcut(), setStatusTip(), setWhatsThis(), and setToolTip(). Icon and text, as the two most important properties, can also be set in the 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 they are used in. In most cases actions will be children of the application's main window.

QAction in widget applications▲

Once a QAction has been created, it should be added to the relevant menu and toolbar, then connected to the slot which will perform the action.

Actions are added to widgets using QWidget::addAction() or QGraphicsWidget::addAction(). Note that an action must be added to a widget before it can be used. This is also true when the shortcut should be global (i.e., Qt::ApplicationShortcut as Qt::ShortcutContext).

Actions can be created as independent objects. But they may also be created during the construction of menus. The QMenu class contains convenience functions for creating actions suitable for use as menu items.

See Also▲

See also QMenu, QToolBar

Member Type Documentation▲

 

enum QAction::ActionEvent▲

This enum type is used when calling QAction::activate()

Constant

Value

Description

QAction::Trigger

0

this will cause the QAction::triggered() signal to be emitted.

QAction::Hover

1

this will cause the QAction::hovered() signal to be emitted.

enum QAction::MenuRole▲

Constant

Value

Description

QAction::NoRole

0

This action should not be put into the application menu

QAction::TextHeuristicRole

1

This action should be put in the application menu based on the action's text as described in the QMenuBar documentation.

QAction::ApplicationSpecificRole

2

This action should be put in the application menu with an application specific role

QAction::AboutQtRole

3

This action handles the "About Qt" menu item.

QAction::AboutRole

4

This action should be placed where the "About" menu item is in the application menu. The text of the menu item will be set to "About <application name>". The application name is fetched from the Info.plist file in the application's bundle (See Qt for macOS - Deployment).

QAction::PreferencesRole

5

This action should be placed where the "Preferences..." menu item is in the application menu.

QAction::QuitRole

6

This action should be placed where the Quit menu item is in the application menu.

Setting this value only has effect on items that are in the immediate menus of the menubar, not the submenus of those menus. For example, if you have File menu in your menubar and the File menu has a submenu, setting the MenuRole for the actions in that submenu have no effect. They will never be moved.

enum QAction::Priority▲

This enum defines priorities for actions in user interface.

Constant

Value

Description

QAction::LowPriority

0

The action should not be prioritized in the user interface.

QAction::NormalPriority

128

 

QAction::HighPriority

256

The action should be prioritized in the user interface.
See Also▲

See also priority

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:

  • bool autoRepeat() const

  • void setAutoRepeat(bool)

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:

  • bool isCheckable() const

  • void setCheckable(bool)

Notifier signal:

  • void checkableChanged(bool checkable)

See Also▲

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

The notifier signal for this property is toggled(). As toggling a QAction changes its state, it will also emit a changed() signal.

Access functions:

  • bool isChecked() const

  • void setChecked(bool)

Notifier signal:

See Also▲

See also checkable, 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:

  • bool isEnabled() const

  • void setEnabled(bool)

  • void resetEnabled()

Notifier signal:

  • void enabledChanged(bool enabled)

See Also▲

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:

  • font() const

  • void setFont(const &font)

Notifier signal:

See Also▲

See also setText()

icon : QIcon▲