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>
Inherits: QObject

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 QList<QKeySequence> defaultKeySequences() 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 QList<QKeySequence> keySequences() 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 setDefaultKeySequences(const QList<QKeySequence> &keys) = 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 QIcon touchBarIcon() const = 0
virtual QString touchBarText() const = 0

Signals

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

ConstantValueDescription
Core::Command::CA_UpdateText2Also update the actions text.
Core::Command::CA_UpdateIcon4Also update the actions icon.
Core::Command::CA_Hide1When there is no active action, hide the user-visible action, instead of just disabling it.
Core::Command::CA_NonConfigurable8Flag 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.

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

Appends the main 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] QList<QKeySequence> Command::defaultKeySequences() const

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

See also setDefaultKeySequences().

[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 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 main keyboard shortcut assigned to this Command.

See also defaultKeySequences().

[pure virtual] QList<QKeySequence> Command::keySequences() const

Returns the current keyboard shortcuts assigned to this Command.

See also defaultKeySequences().

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

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

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

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

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.