Command Class
class Core::CommandThe 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
| 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
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.
[signal] void Command::activeStateChanged()
This signal is emitted when the active state of the command changes.
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().
[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.
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().
Copyright © The Qt Company Ltd. and other contributors. 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.
