Commit 768dd19e authored by con's avatar con

Fixes: - API doc for ActionManager and remove some deprecated things

Details:
ActionManager::registerAction(qaction, id):
  use registerAction(qaction, id, QList<int>() << Core::C_GLOBAL_ID)
ActionManager::addAction/Menu:
  use ActionManager::actionContainer + IActionContainer::addAction/Menu
parent 0ec5f954
......@@ -79,8 +79,3 @@
\generatelist functionindex
*/
/*!
\group qtc
\title Core Plugin
*/
......@@ -177,13 +177,11 @@ bool ActionContainer::hasState(ContainerState state) const
/*!
...
*/
void ActionContainer::appendGroup(const QString &group, bool global)
void ActionContainer::appendGroup(const QString &group)
{
UniqueIDManager *idmanager = CoreImpl::instance()->uniqueIDManager();
int gid = idmanager->uniqueIdentifier(group);
m_groups << gid;
if (global)
ActionManagerPrivate::instance()->registerGlobalGroup(gid, m_id);
}
/*!
......
......@@ -62,7 +62,7 @@ public:
bool hasState(ContainerState state) const;
QAction *insertLocation(const QString &group) const;
void appendGroup(const QString &group, bool global = false);
void appendGroup(const QString &group);
void addAction(ICommand *action, const QString &group = QString());
void addMenu(IActionContainer *menu, const QString &group = QString());
......
......@@ -54,93 +54,146 @@ namespace {
/*!
\class Core::ActionManager
\mainclass
\ingroup qwb
\inheaderfile actionmanager.h
\brief All actions should be registered in the ActionManager, since this enables the user to
e.g. change their shortcuts at a central place.
\brief The action manager 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.
You get the only implementation of this class from the core interface (ICore::actionManager()).
You get the only implementation of this class from the core interface
ICore::actionManager() method, e.g.
\code
ExtensionSystem::PluginManager::instance()->getObject<Core::ICore>()->actionManager()
\endcode
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).
All actions that are registered with the same string id (but different context lists)
are considered to be overloads of the same command. The action that is visible to the user
is the one returned by ICommand::action(). (If you provide yourself a user visible
representation of your action be sure to always use ICommand::action() for this.)
If this action is invoked by the user, the signal is forwarded to the registered action that
is valid for the current context.
You use this class also to add items to registered
action containers like the applications menu bar. For this you register your action via the
are considered to be overloads of the same command, represented by an instance
of the ICommand class.
The action that is visible to the user is the one returned by ICommand::action().
If you provide yourself a user visible representation of your action you need
to use ICommand::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"
put the following in your plugin's IPlugin::initialize method:
\code
Core::ActionManager *am = ExtensionSystem::PluginManager::instance()
->getObject<Core::ICore>()->actionManager();
QAction *myAction = new QAction(tr("My Action"), this);
Core::ICommand *cmd = am->registerAction(myAction,
"myplugin.myaction",
QList<int>() << C_GLOBAL_ID);
cmd->setDefaultKeySequence(QKeySequence(tr("Ctrl+Alt+u")));
connect(myAction, SIGNAL(triggered()), this, SLOT(performMyAction()));
\endcode
So the \c 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 ICommand::action() to it:
\code
QToolButton *myButton = new QToolButton(someParentWidget);
myButton->setDefaultAction(cmd->action());
\endcode
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
Core::Constants) with a call of
the Core::Constants namespace) with a call of
actionContainer(const QString&) and add your command to this container.
Guidelines:
Following the example adding "My Action" to the "Tools" menu would be done by
\code
am->actionContainer(Core::M_TOOLS)->addAction(cmd);
\endcode
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
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 Use this class to add actions to the applications menus
\endlist
\sa Core::ICore, Core::ICommand
\sa Core::ICore
\sa Core::ICommand
\sa Core::IActionContainer
\sa Core::IContext
*/
/*!
\fn virtual IActionContainer *ActionManager::createMenu(const QString &id) = 0
...
*/
\fn IActionContainer *ActionManager::createMenu(const QString &id)
\brief Creates a new menu with the given string \a id.
/*!
\fn virtual IActionContainer *ActionManager::createMenuBar(const QString &id) = 0
...
Returns a new IActionContainer that you can use to get the QMenu instance
or to add menu items to the menu. The ActionManager owns
the returned IActionContainer.
Add your menu to some other menu or a menu bar via the
ActionManager::actionContainer and IActionContainer::addMenu methods.
*/
/*!
\fn virtual ICommand *ActionManager::registerAction(QAction *action, const QString &id, const QList<int> &context) = 0
...
*/
\fn IActionContainer *ActionManager::createMenuBar(const QString &id)
\brief Creates a new menu bar with the given string \a id.
/*!
\fn virtual ICommand *ActionManager::registerShortcut(QShortcut *shortcut, const QString &id, const QList<int> &context) = 0
...
Returns a new IActionContainer that you can use to get the QMenuBar instance
or to add menus to the menu bar. The ActionManager owns
the returned IActionContainer.
*/
/*!
\fn virtual ICommand *ActionManager::registerAction(QAction *action, const QString &id) = 0
...
\fn ICommand *ActionManager::registerAction(QAction *action, const QString &id, const QList<int> &context)
\brief Makes an \a action known to the system under the specified string \a id.
Returns a command object that represents the action in the application and is
owned by the ActionManager. You can registered several actions with the
same \a id as long as the \a context is different. In this case
a trigger of the actual action is forwarded to the registered QAction
for the currently active context.
*/
/*!
\fn virtual void ActionManager::addAction(ICommand *action, const QString &globalGroup) = 0
...
\fn ICommand *ActionManager::registerShortcut(QShortcut *shortcut, const QString &id, const QList<int> &context)
\brief Makes a \a shortcut known to the system under the specified string \a id.
Returns a command object that represents the shortcut in the application and is
owned by the ActionManager. You can registered several shortcuts with the
same \a id as long as the \a context is different. In this case
a trigger of the actual shortcut is forwarded to the registered QShortcut
for the currently active context.
*/
/*!
\fn virtual void ActionManager::addMenu(IActionContainer *menu, const QString &globalGroup) = 0
...
\fn ICommand *ActionManager::command(const QString &id) const
\brief Returns the ICommand object that is known to the system
under the given string \a id.
\sa ActionManager::registerAction()
*/
/*!
\fn virtual ICommand *ActionManager::command(const QString &id) const = 0
...
*/
\fn IActionContainer *ActionManager::actionContainer(const QString &id) const
\brief Returns the IActionContainter object that is know to the system
under the given string \a id.
\sa ActionManager::createMenu()
\sa ActionManager::createMenuBar()
*/
/*!
\fn virtual IActionContainer *ActionManager::actionContainer(const QString &id) const = 0
...
\fn ActionManager::ActionManager(QObject *parent)
\internal
*/
/*!
\fn virtual ActionManager::~ActionManager()
...
\fn ActionManager::~ActionManager()
\internal
*/
using namespace Core;
......@@ -149,16 +202,11 @@ using namespace Core::Internal;
ActionManagerPrivate* ActionManagerPrivate::m_instance = 0;
/*!
\class ActionManager
\ingroup qwb
\inheaderfile actionmanager.h
\sa ActionContainer
\class ActionManagerPrivate
\inheaderfile actionmanager_p.h
\internal
*/
/*!
...
*/
ActionManagerPrivate::ActionManagerPrivate(MainWindow *mainWnd, UniqueIDManager *uidmgr) :
ActionManager(mainWnd),
m_mainWnd(mainWnd)
......@@ -170,72 +218,37 @@ ActionManagerPrivate::ActionManagerPrivate(MainWindow *mainWnd, UniqueIDManager
}
/*!
...
*/
ActionManagerPrivate::~ActionManagerPrivate()
{
qDeleteAll(m_idCmdMap.values());
qDeleteAll(m_idContainerMap.values());
}
/*!
...
*/
ActionManagerPrivate* ActionManagerPrivate::instance()
{
return m_instance;
}
/*!
...
*/
QList<int> ActionManagerPrivate::defaultGroups() const
{
return m_defaultGroups;
}
/*!
...
*/
QList<Command *> ActionManagerPrivate::commands() const
{
return m_idCmdMap.values();
}
/*!
...
*/
QList<ActionContainer *> ActionManagerPrivate::containers() const
{
return m_idContainerMap.values();
}
/*!
...
*/
void ActionManagerPrivate::registerGlobalGroup(int groupId, int containerId)
{
if (m_globalgroups.contains(groupId)) {
qWarning() << "registerGlobalGroup: Global group "
<< m_mainWnd->uniqueIDManager()->stringForUniqueIdentifier(groupId)
<< " already registered";
} else {
m_globalgroups.insert(groupId, containerId);
}
}
/*!
...
*/
bool ActionManagerPrivate::hasContext(int context) const
{
return m_context.contains(context);
}
/*!
...
*/
void ActionManagerPrivate::setContext(const QList<int> &context)
{
// here are possibilities for speed optimization if necessary:
......@@ -251,9 +264,6 @@ void ActionManagerPrivate::setContext(const QList<int> &context)
it.value()->update();
}
/*!
\internal
*/
bool ActionManagerPrivate::hasContext(QList<int> context) const
{
for (int i=0; i<m_context.count(); ++i) {
......@@ -263,9 +273,6 @@ bool ActionManagerPrivate::hasContext(QList<int> context) const
return false;
}
/*!
...
*/
IActionContainer *ActionManagerPrivate::createMenu(const QString &id)
{
const int uid = m_mainWnd->uniqueIDManager()->uniqueIdentifier(id);
......@@ -284,9 +291,6 @@ IActionContainer *ActionManagerPrivate::createMenu(const QString &id)
return mc;
}
/*!
...
*/
IActionContainer *ActionManagerPrivate::createMenuBar(const QString &id)
{
const int uid = m_mainWnd->uniqueIDManager()->uniqueIdentifier(id);
......@@ -305,9 +309,6 @@ IActionContainer *ActionManagerPrivate::createMenuBar(const QString &id)
return mbc;
}
/*!
...
*/
ICommand *ActionManagerPrivate::registerAction(QAction *action, const QString &id, const QList<int> &context)
{
OverrideableAction *a = 0;
......@@ -318,17 +319,6 @@ ICommand *ActionManagerPrivate::registerAction(QAction *action, const QString &i
return a;
}
/*!
...
*/
ICommand *ActionManagerPrivate::registerAction(QAction *action, const QString &id)
{
return registerOverridableAction(action, id, true);
}
/*!
\internal
*/
ICommand *ActionManagerPrivate::registerOverridableAction(QAction *action, const QString &id, bool checkUnique)
{
OverrideableAction *a = 0;
......@@ -375,9 +365,6 @@ ICommand *ActionManagerPrivate::registerOverridableAction(QAction *action, const
return a;
}
/*!
...
*/
ICommand *ActionManagerPrivate::registerShortcut(QShortcut *shortcut, const QString &id, const QList<int> &context)
{
Shortcut *sc = 0;
......@@ -415,48 +402,6 @@ ICommand *ActionManagerPrivate::registerShortcut(QShortcut *shortcut, const QStr
return sc;
}
/*!
\fn void ActionManagerPrivate::addAction(Core::ICommand *action, const QString &globalGroup)
*/
void ActionManagerPrivate::addAction(ICommand *action, const QString &globalGroup)
{
const int gid = m_mainWnd->uniqueIDManager()->uniqueIdentifier(globalGroup);
if (!m_globalgroups.contains(gid)) {
qWarning() << "addAction: Unknown global group " << globalGroup;
return;
}
const int cid = m_globalgroups.value(gid);
if (IActionContainer *aci = actionContainer(cid)) {
aci->addAction(action, globalGroup);
} else {
qWarning() << "addAction: Cannot find container." << cid << '/' << gid;
}
}
/*!
\fn void ActionManagerPrivate::addMenu(Core::IActionContainer *menu, const QString &globalGroup)
*/
void ActionManagerPrivate::addMenu(IActionContainer *menu, const QString &globalGroup)
{
const int gid = m_mainWnd->uniqueIDManager()->uniqueIdentifier(globalGroup);
if (!m_globalgroups.contains(gid)) {
qWarning() << "addAction: Unknown global group " << globalGroup;
return;
}
const int cid = m_globalgroups.value(gid);
if (IActionContainer *aci = actionContainer(cid)) {
aci->addMenu(menu, globalGroup);
} else {
qWarning() << "addAction: Cannot find container." << cid << '/' << gid;
}
}
/*!
...
*/
ICommand *ActionManagerPrivate::command(const QString &id) const
{
const int uid = m_mainWnd->uniqueIDManager()->uniqueIdentifier(id);
......@@ -469,9 +414,6 @@ ICommand *ActionManagerPrivate::command(const QString &id) const
return it.value();
}
/*!
...
*/
IActionContainer *ActionManagerPrivate::actionContainer(const QString &id) const
{
const int uid = m_mainWnd->uniqueIDManager()->uniqueIdentifier(id);
......@@ -484,9 +426,6 @@ IActionContainer *ActionManagerPrivate::actionContainer(const QString &id) const
return it.value();
}
/*!
...
*/
ICommand *ActionManagerPrivate::command(int uid) const
{
const IdCmdMap::const_iterator it = m_idCmdMap.constFind(uid);
......@@ -498,9 +437,6 @@ ICommand *ActionManagerPrivate::command(int uid) const
return it.value();
}
/*!
...
*/
IActionContainer *ActionManagerPrivate::actionContainer(int uid) const
{
const IdContainerMap::const_iterator it = m_idContainerMap.constFind(uid);
......@@ -516,9 +452,6 @@ static const char *settingsGroup = "KeyBindings";
static const char *idKey = "ID";
static const char *sequenceKey = "Keysequence";
/*!
\internal
*/
void ActionManagerPrivate::initialize()
{
QSettings *settings = m_mainWnd->settings();
......@@ -536,9 +469,6 @@ void ActionManagerPrivate::initialize()
settings->endArray();
}
/*!
...
*/
void ActionManagerPrivate::saveSettings(QSettings *settings)
{
settings->beginWriteArray(QLatin1String(settingsGroup));
......
......@@ -63,11 +63,6 @@ public:
virtual ICommand *registerAction(QAction *action, const QString &id, const QList<int> &context) = 0;
virtual ICommand *registerShortcut(QShortcut *shortcut, const QString &id, const QList<int> &context) = 0;
virtual ICommand *registerAction(QAction *action, const QString &id) = 0;
virtual void addAction(ICommand *action, const QString &globalGroup) = 0;
virtual void addMenu(IActionContainer *menu, const QString &globalGroup) = 0;
virtual ICommand *command(const QString &id) const = 0;
virtual IActionContainer *actionContainer(const QString &id) const = 0;
};
......
......@@ -82,8 +82,6 @@ public:
ICommand *command(int uid) const;
IActionContainer *actionContainer(int uid) const;
void registerGlobalGroup(int groupId, int containerId);
void initialize();
//ActionManager Interface
......@@ -92,13 +90,9 @@ public:
ICommand *registerAction(QAction *action, const QString &id,
const QList<int> &context);
ICommand *registerAction(QAction *action, const QString &id);
ICommand *registerShortcut(QShortcut *shortcut, const QString &id,
const QList<int> &context);
void addAction(Core::ICommand *action, const QString &globalGroup);
void addMenu(Core::IActionContainer *menu, const QString &globalGroup);
Core::ICommand *command(const QString &id) const;
Core::IActionContainer *actionContainer(const QString &id) const;
......@@ -116,9 +110,9 @@ private:
typedef QHash<int, ActionContainer *> IdContainerMap;
IdContainerMap m_idContainerMap;
typedef QMap<int, int> GlobalGroupMap;
GlobalGroupMap m_globalgroups;
// typedef QMap<int, int> GlobalGroupMap;
// GlobalGroupMap m_globalgroups;
//
QList<int> m_context;
MainWindow *m_mainWnd;
......
......@@ -70,7 +70,7 @@ public:
virtual QMenuBar *menuBar() const = 0;
virtual QAction *insertLocation(const QString &group) const = 0;
virtual void appendGroup(const QString &group, bool global = false) = 0;
virtual void appendGroup(const QString &group) = 0;
virtual void addAction(Core::ICommand *action, const QString &group = QString()) = 0;
virtual void addMenu(Core::IActionContainer *menu, const QString &group = QString()) = 0;
......
......@@ -398,7 +398,7 @@ void MainWindow::registerDefaultContainers()
medit->appendGroup(Constants::G_EDIT_COPYPASTE);
medit->appendGroup(Constants::G_EDIT_SELECTALL);
medit->appendGroup(Constants::G_EDIT_FORMAT);
medit->appendGroup(Constants::G_EDIT_FIND, true);
medit->appendGroup(Constants::G_EDIT_FIND);
medit->appendGroup(Constants::G_EDIT_OTHER);
//Tools Menu
......@@ -417,14 +417,14 @@ void MainWindow::registerDefaultContainers()
mwindow->appendGroup(Constants::G_WINDOW_NAVIGATE);
mwindow->appendGroup(Constants::G_WINDOW_NAVIGATE_GROUPS);
mwindow->appendGroup(Constants::G_WINDOW_OTHER);
mwindow->appendGroup(Constants::G_WINDOW_LIST, true);
mwindow->appendGroup(Constants::G_WINDOW_LIST);
//Help Menu
ac = am->createMenu(Constants::M_HELP);
menubar->addMenu(ac, Constants::G_HELP);
ac->menu()->setTitle(tr("&Help"));
ac->appendGroup(Constants::G_HELP_HELP, true);
ac->appendGroup(Constants::G_HELP_ABOUT, true);
ac->appendGroup(Constants::G_HELP_HELP);
ac->appendGroup(Constants::G_HELP_ABOUT);
}
static ICommand *createSeparator(ActionManagerPrivate *am, QObject *parent,
......@@ -511,7 +511,7 @@ void MainWindow::registerDefaultActions()
//Save Action
QAction *tmpaction = new QAction(QIcon(Constants::ICON_SAVEFILE), tr("&Save"), this);
cmd = am->registerAction(tmpaction, Constants::SAVE);
cmd = am->registerAction(tmpaction, Constants::SAVE, m_globalContext);
cmd->setDefaultKeySequence(QKeySequence::Save);
cmd->setAttribute(ICommand::CA_UpdateText);
cmd->setDefaultText(tr("&Save"));
......@@ -519,7 +519,7 @@ void MainWindow::registerDefaultActions()
//Save As Action
tmpaction = new QAction(tr("Save &As..."), this);
cmd = am->registerAction(tmpaction, Constants::SAVEAS);
cmd = am->registerAction(tmpaction, Constants::SAVEAS, m_globalContext);
#ifdef Q_OS_MAC
cmd->setDefaultKeySequence(QKeySequence(tr("Ctrl+Shift+S")));
#endif
......@@ -538,7 +538,7 @@ void MainWindow::registerDefaultActions()
//Print Action
tmpaction = new QAction(tr("&Print..."), this);
cmd = am->registerAction(tmpaction, Constants::PRINT);
cmd = am->registerAction(tmpaction, Constants::PRINT, m_globalContext);
mfile->addAction(cmd, Constants::G_FILE_PRINT);
//Exit Action
......@@ -550,7 +550,7 @@ void MainWindow::registerDefaultActions()
//Undo Action
tmpaction = new QAction(QIcon(Constants::ICON_UNDO), tr("&Undo"), this);
cmd = am->registerAction(tmpaction, Constants::UNDO);
cmd = am->registerAction(tmpaction, Constants::UNDO, m_globalContext);
cmd->setDefaultKeySequence(QKeySequence::Undo);
cmd->setAttribute(ICommand::CA_UpdateText);
cmd->setDefaultText(tr("&Undo"));
......@@ -558,7 +558,7 @@ void MainWindow::registerDefaultActions()
//Redo Action
tmpaction = new QAction(QIcon(Constants::ICON_REDO), tr("&Redo"), this);
cmd = am->registerAction(tmpaction, Constants::REDO);
cmd = am->registerAction(tmpaction, Constants::REDO, m_globalContext);
cmd->setDefaultKeySequence(QKeySequence::Redo);
cmd->setAttribute(ICommand::CA_UpdateText);
cmd->setDefaultText(tr("&Redo"));
......@@ -566,31 +566,31 @@ void MainWindow::registerDefaultActions()
//Cut Action
tmpaction = new QAction(QIcon(Constants::ICON_CUT), tr("Cu&t"), this);
cmd = am->registerAction(tmpaction, Constants::CUT);
cmd = am->registerAction(tmpaction, Constants::CUT, m_globalContext);
cmd->setDefaultKeySequence(QKeySequence::Cut);
medit->addAction(cmd, Constants::G_EDIT_COPYPASTE);
//Copy Action
tmpaction = new QAction(QIcon(Constants::ICON_COPY), tr("&Copy"), this);
cmd = am->registerAction(tmpaction, Constants::COPY);
cmd = am->registerAction(tmpaction, Constants::COPY, m_globalContext);
cmd->setDefaultKeySequence(QKeySequence::Copy);
medit->addAction(cmd, Constants::G_EDIT_COPYPASTE);
//Paste Action
tmpaction = new QAction(QIcon(Constants::ICON_PASTE), tr("&Paste"), this);
cmd = am->registerAction(tmpaction, Constants::PASTE);
cmd = am->registerAction(tmpaction, Constants::PASTE, m_globalContext);
cmd->setDefaultKeySequence(QKeySequence::Paste);
medit->addAction(cmd, Constants::G_EDIT_COPYPASTE);
//Select All
tmpaction = new QAction(tr("&Select All"), this);
cmd = am->registerAction(tmpaction, Constants::SELECTALL);
cmd = am->registerAction(tmpaction, Constants::SELECTALL, m_globalContext);
cmd->setDefaultKeySequence(QKeySequence::SelectAll);
medit->addAction(cmd, Constants::G_EDIT_SELECTALL);
//Goto Action
tmpaction = new QAction(tr("&Go To Line..."), this);
cmd = am->registerAction(tmpaction, Constants::GOTO);
cmd = am->registerAction(tmpaction, Constants::GOTO, m_globalContext);
cmd->setDefaultKeySequence(QKeySequence(tr("Ctrl+L")));
medit->addAction(cmd, Constants::G_EDIT_OTHER);
......
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