Lomiri Action API
Action Contexts

Overview

Application which has different views needs to manage it actions based on the currently active view; not all of the actions supported by the application might be relevant or applicable on all of the views.

Therefore Lomiri Action API provides action contexts; a context groups actions together and by providing multiple contexts the developer is able to control the visibility of the actions. The ActionManager then exposes the actions from these different contexts.

Each application has one global context; the actions in this context are always available. The application may have one or more additional local context of which only one can be active at a time. The ActionManager merges the global context and the active local context together; the actions available at any given time is the union of the global context and the active local context.

Applications with Single Context

For applications that do not require multiple contexts using the API is straight forward as the ActionManager provides the global context automatically.

First, create the Action:

Action *globalAction = new Action(this);
globalAction->setText("My Global");

And add it to the ActionManager:

ActionManager *manager = new ActionManager(this);
manager->addAction(globalAction);

myAction is now added to the global context.

Applications with Multiple Contexts

When multiple contexts are needed the developer creates suitable number of ActionContext objects, adds the actions to the contexts, adds the contexts to the manager and sets the active one.

Setting the active context must be managed by the developer. The can only be one active local context at a time.

Create the local actions:

Action *ctx1Action1 = new Action(this);
ctx1Action1->setText("Context1, Action 1");
Action *ctx1Action2 = new Action(this);
ctx1Action2->setText("Context1, Action 2");
Action *ctx2Action1 = new Action(this);
ctx2Action1->setText("Context2, Action 1");
Action *ctx2Action2 = new Action(this);
ctx2Action2->setText("Context2, Action 2");

Create the local contexts:

ActionContext *ctx1 = new ActionContext(this);
ActionContext *ctx2 = new ActionContext(this);

Add the local actions to the contexts:

ctx1->addAction(ctx1Action1);
ctx1->addAction(ctx1Action2);
ctx2->addAction(ctx2Action1);
ctx2->addAction(ctx2Action2);

Add the local contexts to the manager:

manager->addLocalContext(ctx1);
manager->addLocalContext(ctx2);

Manage the active context by setting the active property on any of them:

ctx2->setActive(true);
// now the ActionManager has exported globalAction, ctx2Action1 and ctx2Action2

Setting an another context active later will inactivate the previously active one.


The complete example:

/* This file is part of lomiri-action-api
* Copyright 2013 Canonical Ltd.
*
* lomiri-action-api is free software: you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License version 3,
* as published by the Free Software Foundation.
*
* lomiri-action-api is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranties of
* MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
* PURPOSE. See the GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include <QApplication>
#include <QMainWindow>
#include <lomiri/action/ActionManager>
#include <lomiri/action/Action>
#include <lomiri/action/ActionContext>
#include <QDebug>
using namespace lomiri::action;
class MainWindow : public QMainWindow
{
Q_OBJECT
public:
MainWindow(QWidget *parent = 0);
~MainWindow();
};
MainWindow::MainWindow(QWidget *parent)
: QMainWindow(parent)
{
Action *globalAction = new Action(this);
globalAction->setText("My Global");
Action *ctx1Action1 = new Action(this);
ctx1Action1->setText("Context1, Action 1");
Action *ctx1Action2 = new Action(this);
ctx1Action2->setText("Context1, Action 2");
Action *ctx2Action1 = new Action(this);
ctx2Action1->setText("Context2, Action 1");
Action *ctx2Action2 = new Action(this);
ctx2Action2->setText("Context2, Action 2");
ActionContext *ctx1 = new ActionContext(this);
ActionContext *ctx2 = new ActionContext(this);
ctx1->addAction(ctx1Action1);
ctx1->addAction(ctx1Action2);
ctx2->addAction(ctx2Action1);
ctx2->addAction(ctx2Action2);
ActionManager *manager = new ActionManager(this);
manager->addAction(globalAction);
manager->addLocalContext(ctx1);
manager->addLocalContext(ctx2);
ctx2->setActive(true);
// now the ActionManager has exported globalAction, ctx2Action1 and ctx2Action2
}
MainWindow::~MainWindow()
{}
int main(int argc, char *argv[])
{
QApplication a(argc, argv);
MainWindow w;
w.show();
return a.exec();
}
#include "action-context.moc"
Definition: lomiri-action-context.h:32
Q_INVOKABLE void addAction(lomiri::action::Action *action)
Definition: lomiri-action-context.cpp:136
Definition: lomiri-action-manager.h:32
Q_INVOKABLE void addAction(lomiri::action::Action *action)
Definition: lomiri-action-manager.cpp:426
Q_INVOKABLE void addLocalContext(lomiri::action::ActionContext *context)
Definition: lomiri-action-manager.cpp:473
The main action class.
Definition: lomiri-action.h:31