Extending Qt Creator Manual | ActionManager

Extending Qt Creator Manual 4.4.0

# ActionManager Class

(Core::ActionManager)

The ActionManager class is responsible for registration of menus and menu items and keyboard shortcuts. More...

Header: | #include <ActionManager>

- List of all members, including inherited members

## Signals

void | commandAdded(Core::Id id)
void | commandListChanged()

## Static Public Members

ActionContainer * | actionContainer(Id id)
Command * | command(Id id)
QList<Command *> | commands()
ActionContainer * | createMenu(Id id)
ActionContainer * | createMenuBar(Id id)
ActionManager * | instance()
bool | isPresentationModeEnabled()
Command * | registerAction(QAction *action, Id id, const Context &context = Context( Constants::C_GLOBAL ), bool scriptable = false)
void | setPresentationModeEnabled(bool enabled)
void | unregisterAction(QAction *action, Id id)
QString | withNumberAccelerator(const QString &text, const int number)

## Detailed Description

The ActionManager class is responsible for registration of menus and menu items and keyboard shortcuts.

The ActionManager is the central bookkeeper of actions and their shortcuts and layout. It is a singleton containing mostly static functions. If you need access to the instance, e.g. for connecting to signals, is its ActionManager::instance() function.

The main reasons for the need of this class is to provide a central place where the user can specify all his keyboard shortcuts, and to provide a solution for actions that should behave differently in different contexts (like the copy/replace/undo/redo actions).

### Contexts

All actions that are registered with the same Id (but different context lists) are considered to be overloads of the same command, represented by an instance of the Command class. Exactly only one of the registered actions with the same ID is active at any time. Which action this is, is defined by the context list that the actions were registered with:

If the current focus widget was registered via ICore::addContextObject(), all the contexts returned by its IContext object are active. In addition all contexts set via ICore::addAdditionalContext() are active as well. If one of the actions was registered for one of these active contexts, it is the one active action, and receives `triggered` and `toggled` signals. Also the appearance of the visible action for this ID might be adapted to this active action (depending on the settings of the corresponding Command object).

The action that is visible to the user is the one returned by Command::action(). If you provide yourself a user visible representation of your action you need to use Command::action() for this. When this action is invoked by the user, the signal is forwarded to the registered action that is valid for the current context.

### Registering Actions

To register a globally active action "My Action" put the following in your plugin's IPlugin::initialize function:

      QAction *myAction = new QAction(tr("My Action"), this);
      Command *cmd = ActionManager::registerAction(myAction,
                                               "myplugin.myaction",
                                               Context(C_GLOBAL));
      cmd->setDefaultKeySequence(QKeySequence(tr("Ctrl+Alt+u")));
      connect(myAction, &QAction::triggered, this, &MyPlugin::performMyAction);

So the `connect` is done to your own QAction instance. If you create e.g. a tool button that should represent the action you add the action from Command::action() to it:

      QToolButton *myButton = new QToolButton(someParentWidget);
      myButton->setDefaultAction(cmd->action());

Also use the ActionManager to add items to registered action containers like the applications menu bar or menus in that menu bar. To do this, you register your action via the registerAction functions, get the action container for a specific ID (like specified in the Core::Constants namespace) with a call of actionContainer(const Id&) and add your command to this container.

Following the example adding "My Action" to the "Tools" menu would be done by

      ActionManager::actionContainer(M_TOOLS)->addAction(cmd);

### Important Guidelines:

- Always register your actions and shortcuts!
- Register your actions and shortcuts during your plugin's ExtensionSystem::IPlugin::initialize() or ExtensionSystem::IPlugin::extensionsInitialized() functions, otherwise the shortcuts won't appear in the keyboard settings dialog from the beginning.
- When registering an action with `cmd=registerAction(action, id, contexts)` be sure to connect your own action `connect(action, SIGNAL...)` but make `cmd->action()` visible to the user, i.e. `widget->addAction(cmd->action())`.
- Use this class to add actions to the applications menus

See also Core::ICore, Core::Command, Core::ActionContainer, and Core::IContext.

## Member Function Documentation

### `[static]` ActionContainer *ActionManager::actionContainer(Id id)

Returns the IActionContainter object that is know to the system under the given id.

See also ActionManager::createMenu() and ActionManager::createMenuBar().

### `[static]` Command *ActionManager::command(Id id)

Returns the Command object that is known to the system under the given id.

See also ActionManager::registerAction().

### `[signal]` void ActionManager::commandAdded(Core::Id id)

### `[signal]` void ActionManager::commandListChanged()

Emitted when the command list has changed.

### `[static]` QList<Command *> ActionManager::commands()

Returns all commands that have been registered.

### `[static]` ActionContainer *ActionManager::createMenu(Id id)

Creates a new menu with the given id.

Returns a new ActionContainer that you can use to get the QMenu instance or to add menu items to the menu. The ActionManager owns the returned ActionContainer. Add your menu to some other menu or a menu bar via the ActionManager::actionContainer and ActionContainer::addMenu functions.

### `[static]` ActionContainer *ActionManager::createMenuBar(Id id)

Creates a new menu bar with the given id.

Returns a new ActionContainer that you can use to get the QMenuBar instance or to add menus to the menu bar. The ActionManager owns the returned ActionContainer.

### `[static]` ActionManager *ActionManager::instance()

Returns the pointer to the instance, which is only used for connecting to signals.

### `[static]` bool ActionManager::isPresentationModeEnabled()

### `[static]` Command *ActionManager::registerAction(QAction *action, Id id, const Context &context = Context( Constants::C_GLOBAL ), bool scriptable = false)

Makes an action known to the system under the specified id.

Returns a command object that represents the action in the application and is owned by the ActionManager. You can register several actions with the same id as long as the context is different. In this case a trigger of the actual action is forwarded to the registered QAction for the currently active context. If the optional context argument is not specified, the global context will be assumed. A scriptable action can be called from a script without the need for the user to interact with it.

### `[static]` void ActionManager::setPresentationModeEnabled(bool enabled)

Handles the display of the used shortcuts in the presentation mode. The presentation mode is enabled when starting Qt Creator with the command line argument `-presentationMode`. In the presentation mode, Qt Creator displays any pressed shortcut in a grey box.

See also isPresentationModeEnabled().

### `[static]` void ActionManager::unregisterAction(QAction *action, Id id)

Removes the knowledge about an action under the specified id.

Usually you do not need to unregister actions. The only valid use case for unregistering actions, is for actions that represent user definable actions, like for the custom Locator filters. If the user removes such an action, it also has to be unregistered from the action manager, to make it disappear from shortcut settings etc.

### `[static]` QString ActionManager::withNumberAccelerator(const QString &text, const int number)