ActionManager Class

class Core::ActionManager

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

Header: #include <coreplugin/actionmanager/actionmanager.h>
Inherits: QObject

Signals

void commandAdded(Utils::Id id)
void commandListChanged()

Static Public Members

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

Detailed Description

The action manager 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, for example for connecting to signals, call its ActionManager::instance() function.

The action manager makes it possible to provide a central place where the users can specify all their keyboard shortcuts, and provides a solution for actions that should behave differently in different contexts (like the copy/replace/undo/redo actions).

See The Action Manager and Commands for an overview of the interaction between Core::ActionManager, Core::Command, and Core::Context.

Register a globally active action "My Action" by putting the following in your plugin's ExtensionSystem::IPlugin::initialize() function.

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

The connect is done to your own QAction instance. If you create for example a tool button that should represent the action, add the action from Command::action() to it.

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

Also use the action manager to add items to registered action containers like the application's menu bar or menus in that menu bar. Register your action via the Core::ActionManager::registerAction() function, get the action container for a specific ID (as specified for example in the Core::Constants namespace) with Core::ActionManager::actionContainer(), and add your command to this container.

Building on the example, adding "My Action" to the "Tools" menu would be done with

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

See also Core::ICore, Core::Command, Core::ActionContainer, Core::IContext, and The Action Manager and Commands.

Member Function Documentation

[static] Core::ActionContainer *ActionManager::actionContainer(Utils::Id id)

Returns the ActionContainter instance that has been created with createMenu(), createMenuBar(), createTouchBar() for the specified id.

Use the ID Core::Constants::MENU_BAR to retrieve the main menu bar.

Use the IDs Core::Constants::M_FILE, Core::Constants::M_EDIT, and similar constants to retrieve the various default menus.

Use the ID Core::Constants::TOUCH_BAR to retrieve the main touch bar.

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

[static] Core::Command *ActionManager::command(Utils::Id id)

Returns the Command instance that has been created with registerAction() for the specified id.

See also registerAction().

[signal] void ActionManager::commandAdded(Utils::Id id)

Emitted when a command (with the id) is added.

[signal] void ActionManager::commandListChanged()

Emitted when the command list has changed.

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

Returns all registered commands.

[static] Core::Command *ActionManager::createCommand(Utils::Id id)

Creates a Command or returns an existing Command with the specified id.

The created command doesn't have any actions associated with it yet, so it cannot actually be triggered. But the system is aware of it, it appears in the keyboard shortcut settings, and QActions can later be registered for it. If you already have a QAction, ID and Context that you want to register, there is no need to call this. Just directly call registerAction().

[static] Core::ActionContainer *ActionManager::createMenu(Utils::Id id)

Creates a new menu action container or returns an existing container with the specified id. The ActionManager owns the returned ActionContainer. Add your menu to some other menu or a menu bar via the actionContainer() and ActionContainer::addMenu() functions.

See also actionContainer() and ActionContainer::addMenu().

[static] Core::ActionContainer *ActionManager::createMenuBar(Utils::Id id)

Creates a new menu bar action container or returns an existing container with the specified id. The ActionManager owns the returned ActionContainer.

See also createMenu() and ActionContainer::addMenu().

[static] Core::ActionContainer *ActionManager::createTouchBar(Utils::Id id, const QIcon &icon, const QString &text = QString())

Creates a new (sub) touch bar action container or returns an existing container with the specified id. The ActionManager owns the returned ActionContainer.

Note that it is only possible to create a single level of sub touch bars. The sub touch bar will be represented as a button with icon and text (either of which can be left empty), which opens the sub touch bar when touched.

See also actionContainer() and ActionContainer::addMenu().

[static] Core::ActionManager *ActionManager::instance()

Returns the pointer to the instance. Only use for connecting to signals.

[static] bool ActionManager::isPresentationModeEnabled()

Returns whether presentation mode is enabled.

The presentation mode is enabled when starting Qt Creator with the command line argument -presentationMode. In presentation mode, Qt Creator displays any pressed shortcut in an overlay box.

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

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

Returns a Command instance 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 triggering the 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::unregisterAction(QAction *action, Utils::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)

Decorates the specified text with a numbered accelerator key number, in the style of the Recent Files menu.

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