- Extending Qt Creator Manual
- QtCreator
- Command
- Extending Qt Creator Manual 13.0.0

# Command Class

class Core::Command

The Command class represents an action, such as a menu item, tool button, or shortcut. More...

Header: | #include <coreplugin/actionmanager/command.h>

- List of all members, including inherited members

## Public Types

enum | CommandAttribute { CA_UpdateText, CA_UpdateIcon, CA_Hide, CA_NonConfigurable }
flags | CommandAttributes

## Public Functions

QAction * | action() const
void | augmentActionWithShortcutToolTip(QAction *a) const
Core::Context | context() const
QList<QKeySequence> | defaultKeySequences() const
QString | description() const
bool | hasAttribute(Core::Command::CommandAttribute attribute) const
bool | isActive() const
bool | isScriptable() const
QKeySequence | keySequence() const
QList<QKeySequence> | keySequences() const
void | removeAttribute(Core::Command::CommandAttribute attribute)
void | setAttribute(Core::Command::CommandAttribute attribute)
void | setDefaultKeySequence(const QKeySequence &key)
void | setDefaultKeySequences(const QList<QKeySequence> &keys)
void | setDescription(const QString &text)
void | setTouchBarIcon(const QIcon &icon)
void | setTouchBarText(const QString &text)
QString | stringWithAppendedShortcut(const QString &string) const
QIcon | touchBarIcon() const
QString | touchBarText() const

## Signals

void | activeStateChanged()
void | keySequenceChanged()

## Static Public Members

QAction * | createActionWithShortcutToolTip(Utils::Id commandId, QObject *parent)
QToolButton * | createToolButtonWithShortcutToolTip(Utils::Id commandId, QWidget *parent = nullptr)
QToolButton * | toolButtonWithAppendedShortcut(QAction *action, Core::Command *cmd)
QToolButton * | toolButtonWithAppendedShortcut(QAction *action, Utils::Id commandId)

## Detailed Description

You do not create Command objects directly, but use ActionManager::registerAction() to register an action and retrieve a Command. The Command object represents the user visible action and its properties. If multiple actions are registered with the same ID (but different contexts) the returned Command is the shared one between these actions.

A Command has two basic properties: a list of default shortcuts and a default text. The default shortcuts are key sequence that the user can use to trigger the active action that the Command represents. The first shortcut in that list is the main shortcut that is for example also shown in tool tips and menus. The default text is used for representing the Command in the keyboard shortcut preference pane. If the default text is empty, the text of the visible action is used.

The user visible action is updated to represent the state of the active action (if any). For performance reasons only the enabled and visible state are considered by default though. You can tell a Command to also update the actions icon and text by setting the corresponding attribute.

If there is no active action, the default behavior of the visible action is to be disabled. You can change that behavior to make the visible action hide instead via the Command's attributes.

See The Action Manager and Commands for an overview of how Core::Command and Core::ActionManager interact.

See also Core::ActionManager and The Action Manager and Commands.

## Member Type Documentation

### enum Command::CommandAttribute
flags Command::CommandAttributes

This enum defines how the user visible action is updated when the active action changes. The default is to update the enabled and visible state, and to disable the user visible action when there is no active action.

Constant | Value | Description
--- | --- | ---
`Core::Command::CA_UpdateText` | `2` | Also update the actions text.
`Core::Command::CA_UpdateIcon` | `4` | Also update the actions icon.
`Core::Command::CA_Hide` | `1` | When there is no active action, hide the user-visible action, instead of just disabling it.
`Core::Command::CA_NonConfigurable` | `8` | Flag to indicate that the keyboard shortcuts of this Command should not be configurable by the user.

The CommandAttributes type is a typedef for QFlags<CommandAttribute>. It stores an OR combination of CommandAttribute values.

## Member Function Documentation

### `[signal]` void Command::activeStateChanged()

This signal is emitted when the active state of the command changes.

### `[signal]` void Command::keySequenceChanged()

Sent when the keyboard shortcuts assigned to this Command change, e.g. when the user sets them in the keyboard shortcut settings dialog.

### QAction *Command::action() const

Returns the user visible action for this Command. Use this action to put it on e.g. tool buttons. The action automatically forwards `triggered()` and `toggled()` signals to the action that is currently active for this Command. It also shows the current main keyboard shortcut in its tool tip (in addition to the tool tip of the active action) and gets disabled/hidden when there is no active action for the current context.

### void Command::augmentActionWithShortcutToolTip(QAction *a) const

Sets the tool tip of action a to the action's text, augmented with the command's main keyboard shortcut. The tool tip automatically updates whenever the main keyboard shortcut or the action's text changes.

See also stringWithAppendedShortcut() and createActionWithShortcutToolTip().

### Core::Context Command::context() const

Returns the context for this command.

### `[static]` QAction *Command::createActionWithShortcutToolTip(Utils::Id commandId, QObject *parent)

Returns a new QAction with the command's icon, icon text, and text, that given by commandId. Sets the button's parent to parent. The action's tool tip is the action's text, augmented with the command's main keyboard shortcut. Other properties of the action are not updated automatically.

See also augmentActionWithShortcutToolTip().

### `[static]` QToolButton *Command::createToolButtonWithShortcutToolTip(Utils::Id commandId, QWidget *parent = nullptr)

Returns a new QToolButton with the command's icon, icon text, and text, that given by commandId. Sets the button's parent to parent. The action's tool tip is the action's text, augmented with the command's main keyboard shortcut. Other properties of the button are not updated automatically.

See also createActionWithShortcutToolTip().

### QList<QKeySequence> Command::defaultKeySequences() const

Returns the default keyboard shortcuts that can be used to activate this command.

See also setDefaultKeySequences().

### QString Command::description() const

Returns the text that is used to present this Command to the user.

See also setDescription().

### bool Command::hasAttribute(Core::Command::CommandAttribute attribute) const

Returns whether the Command has the attribute set.

See also CommandAttribute, removeAttribute(), and setAttribute().

### bool Command::isActive() const

Returns whether the Command has an active action for the current context.

### bool Command::isScriptable() const

Returns whether the Command is scriptable. A scriptable command can be called from a script without the need for the user to interact with it.

### QKeySequence Command::keySequence() const

Returns the current main keyboard shortcut assigned to this Command.

See also defaultKeySequences().

### QList<QKeySequence> Command::keySequences() const

Returns the current keyboard shortcuts assigned to this Command.

See also defaultKeySequences().

### void Command::removeAttribute(Core::Command::CommandAttribute attribute)

Removes attribute from the attributes of this Command.

See also CommandAttribute and setAttribute().

### void Command::setAttribute(Core::Command::CommandAttribute attribute)

Adds attribute to the attributes of this Command.

See also CommandAttribute, removeAttribute(), and hasAttribute().

### void Command::setDefaultKeySequence(const QKeySequence &key)

Sets the default keyboard shortcut that can be used to activate this command to key. This is used if the user didn't customize the shortcut, or resets the shortcut to the default.

### void Command::setDefaultKeySequences(const QList<QKeySequence> &keys)

Sets the default keyboard shortcuts that can be used to activate this command to keys. This is used if the user didn't customize the shortcuts, or resets the shortcuts to the default.

See also defaultKeySequences().

### void Command::setDescription(const QString &text)

Sets the text that is used to represent the Command in the keyboard shortcut settings dialog. If you do not set this, the current text from the user visible action is taken (which is fine in many cases).

See also description().

### void Command::setTouchBarIcon(const QIcon &icon)

Sets the icon for the action on the touch bar to icon.

See also touchBarIcon().

### void Command::setTouchBarText(const QString &text)

Sets the text for the action on the touch bar to text.

See also touchBarText().

### QString Command::stringWithAppendedShortcut(const QString &string) const

Returns the string with an appended representation of the main keyboard shortcut that is currently assigned to this Command.

### `[static]` QToolButton *Command::toolButtonWithAppendedShortcut(QAction *action, Core::Command *cmd)

Returns a tool button for action.

Appends the main keyboard shortcut cmd to the tool tip of the action.

### `[static]` QToolButton *Command::toolButtonWithAppendedShortcut(QAction *action, Utils::Id commandId)

Returns a tool button for action.

Appends the main keyboard shortcut of the command with ID commandId to the tool tip of the button.

### QIcon Command::touchBarIcon() const

Returns the icon for the action on the touch bar.

See also setTouchBarIcon().

### QString Command::touchBarText() const

Returns the text for the action on the touch bar.

See also setTouchBarText().