MeeGo Touch: Application extension development How-To

Application extensions are plugins that can be embedded into an application extension area. They can be run either in the same process as the application or a separate process in the application extension runner. An application extension can optionally have an UI.

Development environment

For developing application extensions you need:

libmeegotouch-dev

Developing application extensions and applications that use them

From a developers point of view an application extension consists of a shared library, a desktop entry file and possibly some resources (such as images). All of these are put into a debian package to enable installation of application extensions to devices.

An application extension is implemented as a Qt plugin. It is a good practice to name the shared library so that the related application is mentioned in the name in addition to the extension name (for example libmyapplication-myextension.so). The interface class used as the base class of all application extensions is MApplicationExtensionInterface. The interface provides a method for initializing the plugin, which must be implemented by the application extension:

 bool MApplicationExtensionInterface::initialize(const QString &interface)

The extension gets the name of the interface as a parameter. The extension can but does not need to use this information for any purpose. The boolean return value should indicate whether the initialization was successful or not.

The interface also has an method for returning the widget used for the UI of the application extension:

 MWidget *widget()

In this method you need to return a pointer to the MWidget of your application extension. In case an UI is not required, this method can be left out. Note: The ownership of the MWidget is left to the application extension, so you should destroy the widget yourself in the destructor of the extension.

To use application extensions of particular interface in an application, an instance of MApplicationExtensionArea is created:

new MApplicationExtensionArea(interface, parent);

where interface is the name of the interface the extensions in the area implement and parent is the parent QGraphicsItem. The area will only be populated after init() is called.

It is possible to define which extensions are allowed to be loaded in the same process as the extension area and which extensions are ran in separate processes using setInProcessFilter() and setOutOfProcessFilter() before calling init(). These take QRegExp objects as their parameter, so it is for example possible to use QRegExp("$^") to allow no extensions, QRegExp("/test(1|A).desktop$") to allow extensions test1.desktop and testA.desktop and QRegExp() to allow all extensions.

Differences between in-process and out-of-process application extensions

Developing application extensions and the application that uses them is done differently depending whether the extensions can be run in-process or out-of-process.

In-process

direct communication between application and extension supported by subclassing MApplicationExtensionInterface
the extension can open dialogs and views
the extension can extend the applications UI
the extension can crash the host application

Out-of-process

direct communication between application and extension not supported
the extension can not open dialogs or views
the extension can not draw outside the extensions area
the extension can not crash the host application

Example of an in-process extension

// demoextensioninterface.h
#ifndef DEMOEXTENSIONINTERFACE_H
#define DEMOEXTENSIONINTERFACE_H

#include <duiapplicationextensioninterface.h>

class DemoExtensionInterface : public MApplicationExtensionInterface
{
    Q_INTERFACES(MApplicationExtensionInterface)

public:
    virtual void demoExtensionSpecificOperation() = 0;
};

Q_DECLARE_INTERFACE(DemoExtensionInterface, "com.meego.core.DemoExtensionInterface/1.0")

#endif

// demoextension.h
#ifndef DEMOEXTENSION_H_
#define DEMOEXTENSION_H_

#include <QObject>
#include <MApplicationExtensionInterface>

class MButton;

class DemoApplicationExtension : public QObject, public DemoExtensionInterface
{
    Q_OBJECT
    Q_INTERFACES(DemoExtensionInterface MApplicationExtensionInterface)

public:
    DemoApplicationExtension();
    virtual ~DemoApplicationExtension();

    virtual void demoExtensionSpecificOperation();

    virtual bool initialize(const QString &interface);
    virtual MWidget *widget();

private:
    MButton *button;
};

#endif

Note that the Q_INTERFACES list must include both the demo specific interface DemoExtensionInterface and the base interface MApplicationExtensionInterface.

 // demoextension.cpp
#include <MButton>
#include "demoextension.h"
#include <MLibrary>

M_LIBRARY
Q_EXPORT_PLUGIN2(demoextension, DemoApplicationExtension)

DemoApplicationExtension::DemoApplicationExtension() : button(0)
{
}

DemoApplicationExtension::~DemoApplicationExtension()
{
    delete button;
}

void DemoApplicationExtension::demoExtensionSpecificOperation()
{
    // do something specific to the demo extension interface
}

bool DemoApplicationExtension::initialize(const QString &)
{
    button = new MButton("Hello World");

    return true;
}

MWidget *DemoApplicationExtension::widget()
{
    return button;
}

In the application that wants to use the extensions implementing the com.meego.core.DemoExtensionInterface/1.0 defined above, the application should create an application extension area like this:

#include <duiapplicationextensionarea.h>
#include <demoextensioninterface.h>

...
void DemoApp::createExtensionArea()
{
    MApplicationExtensionArea *extensionArea =
        new MApplicationExtensionArea("com.meego.core.DemoApplicationExtensionInterface/1.0");
    extensionArea->setInProcessFilter(QRegExp("/demoapp-demoextension2?\\.desktop$"));
    extensionArea->init();
    layout->addItem(extensionArea);

    // Listen to signals about new and removed extensions
    connect(area, SIGNAL(extensionInstantiated(MApplicationExtensionInterface*)),
            this, SLOT(addExtension(MApplicationExtensionInterface*)));
    connect(area, SIGNAL(extensionRemoved(MApplicationExtensionInterface*)),
            this, SLOT(removeExtension(MApplicationExtensionInterface*)));
}

void DemoApp::addExtension(MApplicationExtensionInterface *extension)
{
    DemoExtensionInterface *demoExtension = static_cast<DemoExtensionInterface *>(extension);

    // do some extension interface specific things with the extension
    demoExtension->demoExtensionSpecificOperation();
}
...

Application extension desktop file

Application extension must have a .desktop file written according to freedesktop.org desktop entry specification. It is a good practice to name the file in a similar manner to naming the shared library (for example myapplication-myextension.desktop). The keys Type and Name are required as specified in the desktop entry specification. The type must be X-MeeGoApplicationExtension. The Exec key is optionally used to specify a runner binary (usually mapplicationextensionrunner) which is launched in separate process to run the application extension binary. If the key is not used, the application extension is run inside the host process.

Application extensions extend the specification by defining a new type MApplicationExtension and the following new keys that are put inside the X-MeeGoApplicationExtension group:

Key	Description	Value Type	Required
Interface	Defines the name of the interface implemented by this extension.	string	YES
Extension	Defines the application extension binary. This binary needs to be located in `/usr/lib/dui/applicationextensions/` - directory.	string	YES
Identifier	Defines an identifier for the application extension. The identifier is used for example defining the application extension specific style resource locations when it's run as out-of-process.	string (can contain characters [a-zA-Z0-9_-])	NO

Following is an example of application extension desktop file:

[Desktop Entry]
Type=X-MeeGoApplicationExtension
Name=ExampleExtension
Exec=mapplicationextensionrunner

[X-MeeGoApplicationExtension]
Interface=com.meego.core.DemoExtensionInterface/1.0
Extension=libdemoapplication-demoextension.so

Container communication API

Application extension widgets are by default reparented to a MContainer. MContainer can expose optional application extension information on its titlebar, including icon, title and additional informative text. To make an application extension not reside in a container, set the container-mode property of the application extension area to false:

MApplicationExtensionAreaStyle {
    container-mode: false;
}

Use following properties and signals in your application extension widget class to communicate container information:

Q_PROPERTY(QString applicationExtensionIcon  READ icon  WRITE setIcon)
Q_PROPERTY(QString applicationExtensionTitle READ title WRITE setTitle)
Q_PROPERTY(QString applicationExtensionText  READ text  WRITE setText)

signals:
    // change icon in MContainer
    void applicationExtensionIconChanged(QString newIcon);

    // change title in MContainer
    void applicationExtensionTitleChanged(QString newTitle);

    // change additional text in MContainer
    void applicationExtensionTextChanged(QString newText);

The property and signal names must be as stated above. The property access function names can differ.

Application extension identifier

Every application extension has an application extension identifier string that uniquely identifies the application extension.

The application extension identifier is determined like this:

if an identifier (DUIApplicationExtension-Identifier) is specified in the Application extension desktop file desktop file (and it is valid), that is used
otherwise, an identifier is extracted from the application extension shared library name: assuming your application extension is packaged to a shared library called libexampleapplicationextension.so, the identifier will be exampleapplicationextension.

Application extension styling

Application extensions can define their own styles just like any other application in the DUI world. Styling is done with style sheets and images in the usual way. The only important thing with application extensions is the location of the style resources.

The application extension identifier is used in the construction of the resource location when the application extension is run as out-of-process. The application extension identifier is used as the application name in the directory name.

When the application extension is run as in-process, the resource location is constructed from the library name.

See Theme directory structure for more information about the directory locations.

The layout orientation of the application extension area can be modified using the layout-orientation style parameter:

MApplicationExtensionAreaStyle {
    layout-orientation: horizontal;
}

Tools to help development

The dui-dev-tools package includes a tool called duiapplicationextensiontester. This tool can be used to test application extensions that have an UI. The tool loads application extensions implementing a specified interface to a window where they can be tested by interacting with them and visually checking the results. It's also easy to run the extension in a debugger with this tool.

You can load an application extension with the tool by giving the command:

duiapplicationextensiontester <interfacename>

where <interfacename> is the interface the extensions to be loaded must implement.

Note that the application extensions must be installed to the system before duiapplicationextensiontester can use them.