Commit 38d7c52d authored by con's avatar con
Browse files

Some more documentation about contexts and action containers.

parent b2598d00
......@@ -51,63 +51,98 @@ using namespace Core::Internal;
\brief The ActionContainer class represents a menu or menu bar in Qt Creator.
*/
/*!
\enum ActionContainer::ContainerType
You don't create instances of this class directly, but instead use the
\l{ActionManager::createMenu()}
and \l{ActionManager::createMenuBar()} methods.
Retrieve existing action containers for an ID with
\l{ActionManager::actionContainer()}.
Within a menu or menu bar you can group menus and items together by defining groups
(the order of the groups is defined by the order of the \l{ActionContainer::appendGroup()} calls), and
adding menus/actions to these groups. If no custom groups are defined, an action container
has three default groups \c{Core::Constants::G_DEFAULT_ONE}, \c{Core::Constants::G_DEFAULT_TWO}
and \c{Core::Constants::G_DEFAULT_THREE}.
You can define if the menu represented by this action container should automatically disable
or hide whenever it only contains disabled items and submenus by setting the corresponding
\l{ActionContainer::setEmptyAction()}{EmptyAction}.
*/
/*!
\enum ActionContainer::EmptyAction
Defines what happens when the represented menu is empty or contains only disabled/invisible items.
\omitvalue EA_Mask
\value EA_None
The menu will still be visible and active.
\value EA_Disable
The menu will be visible but disabled.
\value EA_Hide
The menu will not be visible until the state of the subitems change.
*/
/*!
\fn virtual ActionContainer::setEmptyAction(EmptyAction ea)
*/
/*!
\fn virtual int ActionContainer::id() const
\fn ActionContainer::setEmptyAction(EmptyAction disableOrHide)
Defines if the menu represented by this action container should automatically \a disableOrHide
whenever it only contains disabled items and submenus.
\sa ActionContainer::EmptyAction
*/
/*!
\fn virtual ContainerType ActionContainer::type() const
*/
/*!
\fn virtual QMenu *ActionContainer::menu() const
\fn int ActionContainer::id() const
\internal
*/
/*!
\fn virtual QToolBar *ActionContainer::toolBar() const
\fn QMenu *ActionContainer::menu() const
Returns the QMenu instance that is represented by this action container, or
0 if this action container represents a menu bar.
*/
/*!
\fn virtual QMenuBar *ActionContainer::menuBar() const
\fn QMenuBar *ActionContainer::menuBar() const
Returns the QMenuBar instance that is represented by this action container, or
0 if this action container represents a menu.
*/
/*!
\fn virtual QAction *ActionContainer::insertLocation(const QString &group) const
\fn QAction *ActionContainer::insertLocation(const QString &group) const
Returns an action representing the \a group,
that could be used with \c{QWidget::insertAction}.
*/
/*!
\fn virtual void ActionContainer::appendGroup(const QString &group, bool global)
\fn void ActionContainer::appendGroup(const QString &identifier)
Adds a group with the given \a identifier to the action container. Using groups
you can segment your action container into logical parts and add actions and
menus directly to these parts.
\sa addAction()
\sa addMenu()
*/
/*!
\fn virtual void ActionContainer::addAction(Core::Command *action, const QString &group)
\fn void ActionContainer::addAction(Core::Command *action, const QString &group)
Add the \a action as a menu item to this action container. The action is added as the
last item of the specified \a group.
\sa appendGroup()
\sa addMenu()
*/
/*!
\fn virtual void ActionContainer::addMenu(Core::ActionContainer *menu, const QString &group)
\fn void ActionContainer::addMenu(Core::ActionContainer *menu, const QString &group)
Add the \a menu as a submenu to this action container. The menu is added as the
last item of the specified \a group.
\sa appendGroup()
\sa addAction()
*/
/*!
\fn virtual bool ActionContainer::update()
\fn bool ActionContainer::update()
\internal
*/
/*!
\fn virtual ActionContainer::~ActionContainer()
\fn ActionContainer::~ActionContainer()
\internal
*/
// ---------- ActionContainerPrivate ------------
......
......@@ -64,16 +64,32 @@ namespace {
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).
All actions that are registered with the same string id (but different context lists)
\section1 Contexts
All actions that are registered with the same string 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 \l{ICore::addContextObject()},
all the contexts returned by its IContext object are active. In addition all
contexts set via \l{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 \c triggered and \c 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 \l{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.
So to register a globally active action "My Action"
\section1 Registering Actions
To register a globally active action "My Action"
put the following in your plugin's IPlugin::initialize method:
\code
Core::ActionManager *am = Core::ICore::instance()->actionManager();
......@@ -96,7 +112,7 @@ namespace {
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 methods, get the action container for a specific id (like specified in
registerAction methods, get the action container for a specific ID (like specified in
the Core::Constants namespace) with a call of
actionContainer(const QString&) and add your command to this container.
......@@ -105,15 +121,15 @@ namespace {
am->actionContainer(Core::M_TOOLS)->addAction(cmd);
\endcode
Important guidelines:
\section1 Important Guidelines:
\list
\o Always register your actions and shortcuts!
\o Register your actions and shortcuts during your plugin's IPlugin::initialize
or IPlugin::extensionsInitialized methods, otherwise the shortcuts won't appear
\o Register your actions and shortcuts during your plugin's \l{ExtensionSystem::IPlugin::initialize()}
or \l{ExtensionSystem::IPlugin::extensionsInitialized()} methods, otherwise the shortcuts won't appear
in the keyboard settings dialog from the beginning.
\o 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()).
\o When registering an action with \c{cmd=registerAction(action, id, contexts)} be sure to connect
your own action \c{connect(action, SIGNAL...)} but make \c{cmd->action()} visible to the user, i.e.
\c{widget->addAction(cmd->action())}.
\o Use this class to add actions to the applications menus
\endlist
......
......@@ -37,9 +37,8 @@
\class Core::Command
\mainclass
\brief The class...
\brief The class Command represents an action like a menu item, tool button, or shortcut.
The Command interface...
*/
/*!
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment