Home · All Namespaces · All Classes · Main Classes

Binary applets

Description

A binary controlpanel applet is an applet which is implemented as a shared object. You can find some examples under examples/binaryapplet in the repository of control panel, which can be a good starting point for creating a new binary applet.

The applet should inherit from DcpAppletIf, and compiled into a shared object. The interface has functions for specifying controlpanel the things it needs.

Like every other applet, the binary applet also needs a .desktop file.

[Desktop Entry]
Type=ControlPanelApplet
Name=Skeleton
Icon=
Exec=
X-logical-id=qtn_sett_main_display
X-translation-catalog=controlpanel-skeletonapplet

[DUI]
X-DUIApplet-Applet=libdcpskeletonapplet.so

[DCP]
Category=Applications
Order=4
WidgetType=Label

View handling: DcpWidgets

When launching an applet, control panel displays it on one special page, that provides title, menu, and back-mechanism which is handled internally, so applet developers has nothing to do with it. Thus, applet has no pages but widgets. Each widget is displayed on this special page as the main widget, so it looks like that each widget is a new "page view" of an applet.

To provide this mechanism, these widgets must be inherited by DcpWidget, which is a DuiWidget descendant with a few services:

class DcpWidget: public MWidget
{
public:
    virtual bool back ();
...
signals:
    void changeWidget (int widgetId);
...
}

Having multiple pages

The ids of the pages

When an applet has multiple pages (widgets), it associates every one of them with an id. DcpAppletIf::constructWidget() gets the id as parameter, and creates the widget for that id. These ids are referred to as partIds.

{
    DcpWidget * widget = m_Applet->constructWidget (WallpaperApplet::MainWidget);
    QVERIFY (widget);

    DcpWidget * editorWidget = m_Applet->constructWidget (WallpaperApplet::EditorWidget);
    QVERIFY (editorWidget);
...
}

These ids meant to be internal to the applet, outside the applet people refer to pages of the applet as a string. For example a part of the date applet is possibly "Clock". The DcpAppletIf::partID() call translates this string into the integer partId.

{
    QVERIFY(m_applet->partID(QString("Time")) == View::Time);
    QVERIFY(m_applet->partID(QString("TimeZone")) == View::TimeZone);
    QVERIFY(m_applet->partID(QString("Date")) == View::Date);
    QVERIFY(m_applet->partID(QString("Main")) == View::Main);
}

Changing between the applet's pages

The current widget can request changing to another widget by emitting DcpWidget::changeWidget(), where widgetId is the id of another widget, defined by the applet itself.

...
emit changeWidget(View::TimeZone);
...

Back button handling

When the back button is pressed, the current DcpWidget::back() function gets called. If the applet wants to do some extra 'cleanup', it can override the DcpWidget::back() function which is called by the page. (For example stopping threads or such.)

The back function's return value determines if the page gets closed or stays visible. By default it gets closed. See DcpWidget::back().

...
bool backAccepted = widget->back();
...

Applet Launch Buttons

Applets are launched from control panel when user presses one of the launch buttons. A button like these contains applet name, optionally a picture or a toggle button, and the current value of an applet setting.

These values (id for the picture, toggle button state, value text) can come from different places, and may need to format differently for each applet. For example Date & Time applet can display a value (the system time) and formats it according to the regional datetime format.

Also the values can change, then the applet has to notify control panel about that change. For example Date & Time applet's value can be updated in each second.

All these customizations of the launch button can be done through inheriting from the DcpBrief class, a specialized one, which returns the type of the launch button, the values which it needs to display, and emitting a signal when some of the values changes.

If you do not need that much flexibility then you can get a non interactive button by specifying these things only in the .desktop file.

Launch button for a specific applet page

Pressing a launch button of an applet leads to the main page of the applet by default. If you want to create an applet launch button for part of an applet, you can do that with creating another desktop file for it, and specify which part should be openned by default in the "Part=" attribute. See desktop file format for details.

Implementation

Each binary applet must implement DcpAppletIf interface. Here are some example which you can redefine, see DcpAppletIf for details.

Implementing settings

To provide settings that the applet can work from, the recommended way is to write an own singleton class for handling it, whose public interface does not depend on how the values are stored.

class DcpLanguageConf
{
public:
    static DcpLanguageConf *instance();
    ~DcpLanguageConf();
    QString displayLanguage();
    void setDisplayLanguage(QString displayLanguage);
protected:
    DcpLanguageConf(); 
...
}

In this way, some data can come from DuiConf, some from QSettings or can be calculated, but you can easily return test data from methods, and replace them later with live ones.

Loading your custom styles

If the applet needs to use custom styles, its widget should inherit from DcpStylableWidget instead of DcpWidget and should be returned in DcpAppletIf::createStylableWidget(). This way you can use the common library theming way of meegotouch, see their documentation on the limitations.


Copyright © 2009 Nokia Corporation Generated on Tue Jul 5 2011 15:01:31
Doxygen 1.7.1
Meego control panel