Command Class | Extending Qt Creator Manual

Extending Qt Creator Manual | Command

Extending Qt Creator Manual 4.12.0

# Command Class

(Core::Command)

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

Header: | #include <Command>

- List of all members, including inherited members

## Public Types

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

## Public Functions

virtual QAction * | action() const = 0
void | augmentActionWithShortcutToolTip(QAction *a) const
virtual Core::Context | context() const = 0
virtual QKeySequence | defaultKeySequence() const = 0
virtual QString | description() const = 0
virtual bool | hasAttribute(Core::Command::CommandAttribute attribute) const = 0
virtual bool | isActive() const = 0
virtual bool | isScriptable() const = 0
virtual QKeySequence | keySequence() const = 0
virtual void | removeAttribute(Core::Command::CommandAttribute attribute) = 0
virtual void | setAttribute(Core::Command::CommandAttribute attribute) = 0
virtual void | setDefaultKeySequence(const QKeySequence &key) = 0
virtual void | setDescription(const QString &text) = 0
virtual void | setTouchBarIcon(const QIcon &icon) = 0
virtual void | setTouchBarText(const QString &text) = 0
virtual QString | stringWithAppendedShortcut(const QString &string) const = 0
virtual QAction * | touchBarAction() const = 0
virtual QIcon | touchBarIcon() const = 0
virtual QString | touchBarText() const = 0

## Signals

void | activeStateChanged()
void | keySequenceChanged()

## Static Public Members

QToolButton * | toolButtonWithAppendedShortcut(QAction *action, Core::Command *cmd)

## 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 default shortcut and a default text. The default shortcut is a key sequence that the user can use to trigger the active action that the Command represents. The default text is e.g. 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.

## 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 shortcut 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 shortcut assigned to this Command changes, e.g. when the user sets it in the keyboard shortcut settings dialog.

### `[pure virtual]` QAction *Command::action() const

Returns the user visible action for this Command. If the Command represents a shortcut, it returns null. Use this action to put it on e.g. tool buttons. The action automatically forwards trigger and toggle signals to the action that is currently active for this Command. It also shows the current 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

Appends the keyboard shortcut that is currently assigned to the action a to its tool tip.

### `[pure virtual]` Core::Context Command::context() const

Returns the context for this command.

### `[pure virtual]` QKeySequence Command::defaultKeySequence() const

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

See also setDefaultKeySequence().

### `[pure virtual]` QString Command::description() const

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

See also setDescription().

### `[pure virtual]` bool Command::hasAttribute(Core::Command::CommandAttribute attribute) const

Returns whether the Command has the attribute set.

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

### `[pure virtual]` bool Command::isActive() const

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

### `[pure virtual]` 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.

### `[pure virtual]` QKeySequence Command::keySequence() const

Returns the current keyboard shortcut assigned to this Command.

See also defaultKeySequence().

### `[pure virtual]` void Command::removeAttribute(Core::Command::CommandAttribute attribute)

Removes attribute from the attributes of this Command.

See also CommandAttribute and setAttribute().

### `[pure virtual]` void Command::setAttribute(Core::Command::CommandAttribute attribute)

Adds attribute to the attributes of this Command.

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

### `[pure virtual]` 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 one.

See also defaultKeySequence().

### `[pure virtual]` 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().

### `[pure virtual]` void Command::setTouchBarIcon(const QIcon &icon)

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

See also touchBarIcon().

### `[pure virtual]` void Command::setTouchBarText(const QString &text)

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

See also touchBarText().

### `[pure virtual]` QString Command::stringWithAppendedShortcut(const QString &string) const

Returns the string with an appended representation of the 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 keyboard shortcut cmd to the tool tip of the action.

### `[pure virtual]` QAction *Command::touchBarAction() const

Adds an action to the touch bar.

### `[pure virtual]` QIcon Command::touchBarIcon() const

Returns the icon for the action on the touch bar.

See also setTouchBarIcon().

### `[pure virtual]` QString Command::touchBarText() const

Returns the text for the action on the touch bar.

See also setTouchBarText().