QAction Class

The QAction class describes something that a user can do, which a menu, a tool button and a shortcut share. More…

List of all members, including inherited members

Public Types

Public Functions

Public Slots

Signals

Detailed Description

An action has a text, a check state, a shortcut, and a state of being enabled and visible, in one place. A widget that shows the action, such as a QMenu, follows it: when the action is disabled, so is the menu entry, and when the user chooses the entry the action is triggered. Connect to triggered() to do the work:

QAction *open = new QAction("&Open...", this);
open->setShortcut(QKeySequence::Open);
connect(open, &QAction::triggered, this, &Editor::openFile);
menu->addAction(open);

A checkable action toggles each time it is triggered; toggled() reports the new state. Actions in a QActionGroup can be exclusive, like radio buttons. An action with a shortcut is triggered by that key combination whenever it has been added to a widget of the window that has the focus, with QWidget::addAction() or to a menu.

See also QActionGroup, QMenu and QKeySequence.

Differences from Qt

Member Type Documentation

enum QAction::ActionEvent

This enum says what activate() does.

Member Function Documentation

[explicit] QAction::QAction(QObject *parent = nullptr)

Constructs an action with the given parent.

[explicit] QAction::QAction(const QString &text, QObject *parent = nullptr)

Constructs an action with the given text and parent. A & in the text marks the mnemonic, the letter that a menu underlines.

[override] QAction::~QAction()

Destroys the action, and removes it from its group.

QActionGroup * QAction::actionGroup() const

Returns the group that the action is in; nullptr if it is in none.

See also setActionGroup().

void QAction::activate(ActionEvent event)

Does what the user does to the action, as event says: Trigger triggers it, and Hover reports that it is hovered. An action that is not enabled does not trigger, but it can be hovered. Triggering a checkable action toggles it first, except that the checked action of an exclusive group stays checked.

See also trigger() and hover().

QList<QObject *> QAction::associatedObjects() const

Returns the widgets that the action has been added to, such as menus and menu bars.

[signal] void QAction::changed()

This signal is emitted when anything about the action changes: its text, tool tip, shortcut, font, whether it is checkable, checked, enabled or visible, or whether it is a separator.

[signal] void QAction::checkableChanged(bool checkable)

This signal is emitted when the action becomes checkable or stops being it, with the new state checkable.

QVariant QAction::data() const

Returns the data that the application has put in the action; an invalid variant if none.

See also setData().

[signal] void QAction::enabledChanged(bool enabled)

This signal is emitted when the action is enabled or disabled, with the new state enabled. An action that is not visible is not enabled.

QFont QAction::font() const

Returns the font that a menu uses for the action; the default font if none was set.

See also setFont().

[slot] void QAction::hover()

Emits hovered(), as if the user had moved to the action in a menu.

See also trigger().

[signal] void QAction::hovered()

This signal is emitted when the user hovers over the action in a menu, and by hover().

QString QAction::iconText() const

Returns the text of the action without the mnemonic marks: "&Open" gives "Open".

bool QAction::isCheckable() const

Returns true if the action can be checked; otherwise returns false.

See also setCheckable().

bool QAction::isChecked() const

Returns true if the action is checkable and checked; otherwise returns false.

See also setChecked().

bool QAction::isEnabled() const

Returns true if the action is enabled and visible; otherwise returns false.

See also setEnabled().

bool QAction::isSeparator() const

Returns true if the action is a separator, a line between the entries of a menu; otherwise returns false.

See also setSeparator().

bool QAction::isVisible() const

Returns true if the action is shown; otherwise returns false.

See also setVisible().

template <typename T>T QAction::menu() const

Returns the menu of the action cast to the pointer type T, as in action->menu<QMenu *>(). It is nullptr if the action has no menu, or if it is not a T.

See also setMenu().

void QAction::setActionGroup(QActionGroup *group)

Puts the action in the group, and takes it out of the one it was in. A nullptr takes it out of its group.

See also actionGroup() and QActionGroup::addAction().

void QAction::setCheckable(bool checkable)

Sets whether the action can be checked to checkable. A checkable action is checked or not, and each trigger toggles it.

See also isCheckable().

[slot] void QAction::setChecked(bool checked)

Sets whether the action is checked to checked. Nothing happens on a change if the action is not checkable, though it is remembered. toggled() is emitted when the state changes, and in a QActionGroup that is exclusive the other action that was checked is unchecked first.

See also isChecked() and toggle().

void QAction::setData(const QVariant &data)

Sets the data of the action to data. It is for the application, which can tell actions of a menu apart with it.

See also data().

[slot] void QAction::setDisabled(bool disabled)

Disables the action if disabled is true, and enables it if it is false.

See also setEnabled().

[slot] void QAction::setEnabled(bool enabled)

Sets whether the action is enabled to enabled. A disabled action does not trigger, and a menu shows it dimmed.

See also isEnabled() and setVisible().

void QAction::setFont(const QFont &font)

Sets the font that a menu uses for the action to font.

See also font().

void QAction::setMenu(QObject *menu)

Sets the menu of the action to menu, a QMenu. A menu bar and a menu show the action as a submenu. The action does not own the menu.

See also menu().

void QAction::setSeparator(bool separator)

Sets whether the action is a separator to separator. QMenu::addSeparator() makes one.

See also isSeparator().

void QAction::setShortcut(const QKeySequence &shortcut)

Sets the key combination that triggers the action to shortcut. It works when the action has been added to a widget of the window that has the focus, or to a menu of one.

See also shortcut().

void QAction::setStatusTip(const QString &tip)

Sets the status tip of the action to tip.

See also statusTip().

void QAction::setText(const QString &text)

Sets the text of the action to text.

See also text().

void QAction::setToolTip(const QString &tip)

Sets the tool tip of the action to tip.

See also toolTip().

[slot] void QAction::setVisible(bool visible)

Sets whether the action is shown to visible. A menu leaves a hidden action out, and it cannot be triggered.

See also isVisible().

QKeySequence QAction::shortcut() const

Returns the key combination that triggers the action.

See also setShortcut().

QString QAction::statusTip() const

Returns the status tip of the action.

See also setStatusTip().

QString QAction::text() const

Returns the text of the action.

See also setText().

[slot] void QAction::toggle()

Toggles the check state of the action.

See also setChecked().

[signal] void QAction::toggled(bool checked)

This signal is emitted when a checkable action is checked or unchecked, with the new state checked.

QString QAction::toolTip() const

Returns the tool tip of the action, or iconText() if it has none.

See also setToolTip().

[slot] void QAction::trigger()

Triggers the action, as if the user had chosen it: a checkable action toggles, and triggered() is emitted. It does nothing if the action is not enabled.

See also activate() and hover().

[signal] void QAction::triggered(bool checked = false)

This signal is emitted when the action is triggered, by the user or by trigger(). checked is the state of a checkable action after it has toggled, and false for any other.

[signal] void QAction::visibleChanged()

This signal is emitted when the action is shown or hidden.