From 38d7c52d4977980e0aa260d95e5c30c295d7e45b Mon Sep 17 00:00:00 2001
From: con <qtc-committer@nokia.com>
Date: Mon, 4 May 2009 15:09:31 +0200
Subject: [PATCH] Some more documentation about contexts and action containers.
---
.../actionmanager/actioncontainer.cpp | 81 +++++++++++++------
.../actionmanager/actionmanager.cpp | 34 +++++---
.../coreplugin/actionmanager/command.cpp | 3 +-
3 files changed, 84 insertions(+), 34 deletions(-)
diff --git a/src/plugins/coreplugin/actionmanager/actioncontainer.cpp b/src/plugins/coreplugin/actionmanager/actioncontainer.cpp
index 15038c81d5c..960d3e4246f 100644
--- a/src/plugins/coreplugin/actionmanager/actioncontainer.cpp
+++ b/src/plugins/coreplugin/actionmanager/actioncontainer.cpp
@@ -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 ------------
diff --git a/src/plugins/coreplugin/actionmanager/actionmanager.cpp b/src/plugins/coreplugin/actionmanager/actionmanager.cpp
index 56f1ced6690..ca8130d8ec1 100644
--- a/src/plugins/coreplugin/actionmanager/actionmanager.cpp
+++ b/src/plugins/coreplugin/actionmanager/actionmanager.cpp
@@ -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
diff --git a/src/plugins/coreplugin/actionmanager/command.cpp b/src/plugins/coreplugin/actionmanager/command.cpp
index 28ff14195e2..aab4f0fbad4 100644
--- a/src/plugins/coreplugin/actionmanager/command.cpp
+++ b/src/plugins/coreplugin/actionmanager/command.cpp
@@ -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...
*/
/*!
--
GitLab