Home · All Namespaces · All Classes · Main Classes

Creating a control panel applet

Introduction

In control panel, applets provides interface for the user to modify some configurations of the device.

All applets have:

You can create three types of control panel applets:

To declare applets and add applets to Dcp, create a .desktop file. For instructions, see desktop file format of applets.

Creating applets

Note:
You can find examples/skeletons from each applet type under controlpanel's gitorious repository or by checking the source package of duicontrolpanel-skeletonapplet.

Binary applet

The following example shows how to create a simple binary applet called 'skeleton applet'. You need the following files:

/***************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Karoliina T. Salminen <karoliina.t.salminen@nokia.com>
**
** This file is part of duicontrolpanel.
**
**
** This program is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation
** and appearing in the file LICENSE.LGPL included in the packaging
** of this file.
**
****************************************************************************/

#ifndef SKELETONAPPLET_H
#define SKELETONAPPLET_H

#include <DcpAppletIf>
#include <QObject>
class DcpStylableWidget;
class MAction;

class SkeletonApplet : public QObject, public DcpAppletIf 
{
        Q_OBJECT
        Q_INTERFACES(DcpAppletIf)

public:
    virtual void init();
        virtual DcpWidget* constructWidget(int) { return 0; } // FIXME XXX
        virtual DcpStylableWidget* constructStylableWidget(int widgetId);

        virtual DcpStylableWidget* pageMain();
/*  Applet can have more 'pages'. Each page must be a DcpStylableWidget subclass
        virtual DcpStylableWidget* page1();
        virtual DcpStylableWidget* page2();
*/
    virtual QString title() const;
    virtual QVector<MAction *> viewMenuItems();
    virtual DcpBrief* constructBrief(int);
};

#endif // SKELETONAPPLET_H

dcpskeletonapplet.h 

/***************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Karoliina T. Salminen <karoliina.t.salminen@nokia.com>
**
** This file is part of duicontrolpanel.
**
**
** This program is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation
** and appearing in the file LICENSE.LGPL included in the packaging
** of this file.
**
****************************************************************************/

#include <QtGui>
#include <QDebug>
#include <MAction>
#include <MLibrary>

#include <DcpStylableWidget>
#include "dcpskeletonapplet.h"
#include "dcpskeletonwidget.h"
#include "dcpskeleton.h"
#include "dcpskeletonbrief.h"

M_LIBRARY
Q_EXPORT_PLUGIN2(skeletonapplet, SkeletonApplet)

void SkeletonApplet::init()
{
    /* Do not do this, as this wont support switching themes and will cause
     * performance problems when loading the category pages.
     * See the documentation package for details.
     *
    MTheme::loadCSS("/usr/share/themes/base/meegotouch/"
                    "libdcpskeletonapplet/style/libdcpskeletonapplet.css");
     */
};

DcpStylableWidget* SkeletonApplet::constructStylableWidget(int widgetId)
{
        switch (widgetId)
    {
        case DcpSkeleton::Main:
                    return pageMain();
                    break;
        // more cases here if applet has more pages
        default:
                    qDebug() << "Page Unknown";
                    return 0;
                    break;
    };
}

DcpStylableWidget* SkeletonApplet::pageMain()
{
        return new SkeletonWidget();
}



QString SkeletonApplet::title() const
{
    //% "Skeleton applet"
    return qtTrId("dcp_skel_appl_titl");
}

QVector<MAction*> SkeletonApplet::viewMenuItems()
{
    QVector<MAction*> vector(1);
    //% "Example action"
    vector[0] = new MAction(qtTrId("dcp_skel_appl_action"), this);
    vector[0]->setLocation(MAction::ApplicationMenuLocation);
    return vector;
}

DcpBrief* SkeletonApplet::constructBrief(int)
{
    return new SkeletonBrief();
}

dcpskeletonapplet.cpp 

/***************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Karoliina T. Salminen <karoliina.t.salminen@nokia.com>
**
** This file is part of duicontrolpanel.
**
**
** This program is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation
** and appearing in the file LICENSE.LGPL included in the packaging
** of this file.
**
****************************************************************************/

#ifndef SKELETONBRIEF_H
#define SKELETONBRIEF_H

#include <DcpBrief>

class SkeletonBrief: public DcpBrief{
    Q_OBJECT
public:
    SkeletonBrief();
    virtual QString valueText() const;
    virtual QString titleText() const;

    /* You can specify the widgettype here if you need something else
     * than Label
    virtual int widgetTypeID() const;

    virtual bool toggle() const;
    virtual void setToggle (bool toggle);
    */

    virtual void timerEvent(QTimerEvent*);

    // this returns the id of the applet's help
    virtual QString helpId () const;

private:
    bool m_ToggleState;
    int m_Value;
};


#endif // SKELETONBRIEF

dcpskeletonbrief.h 

/***************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Karoliina T. Salminen <karoliina.t.salminen@nokia.com>
**
** This file is part of duicontrolpanel.
**
**
** This program is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation
** and appearing in the file LICENSE.LGPL included in the packaging
** of this file.
**
****************************************************************************/

#include <DcpWidgetTypes>
#include "dcpskeletonbrief.h"
#include <QtDebug>

SkeletonBrief::SkeletonBrief():
    m_ToggleState(true),
    m_Value(0)
{
    startTimer(1000);
}

QString SkeletonBrief::valueText() const
{
    return "value text " + QString::number(m_Value);
}

QString SkeletonBrief::titleText() const
{
    return "title text " + QString::number(m_Value);
}

/* The plugin can specify that it has a toggle like this:
int SkeletonBrief::widgetTypeID() const
{
    return DcpWidgetType::Toggle;
}

bool SkeletonBrief::toggle() const
{
    return m_ToggleState;
}

void SkeletonBrief::setToggle (bool toggle)
{
    m_ToggleState = toggle;
    qDebug() << "Skeleton brief got toggle state:" << toggle;
}
*/

void SkeletonBrief::timerEvent(QTimerEvent*)
{
    ++m_Value;
    emit valuesChanged();
}

QString SkeletonBrief::helpId () const
{
    return "test.cfg";
}

dcpskeletonbrief.cpp 

/***************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Karoliina T. Salminen <karoliina.t.salminen@nokia.com>
**
** This file is part of duicontrolpanel.
**
**
** This program is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation
** and appearing in the file LICENSE.LGPL included in the packaging
** of this file.
**
****************************************************************************/

#ifndef SKELETONWIDGET_H
#define SKELETONWIDGET_H

#include <DcpStylableWidget>

class MLabel;

class SkeletonWidget : public DcpStylableWidget
{
    Q_OBJECT

public:
    SkeletonWidget(QGraphicsWidget *parent = 0);
    virtual ~SkeletonWidget();

protected:
    void initWidget();

protected slots:
    void loadingFinished();

private:
    MLabel *m_aboutLabel;
};

#endif // SKELETONWIDGET_H

dcpskeletonwidget.h 

/***************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Karoliina T. Salminen <karoliina.t.salminen@nokia.com>
**
** This file is part of duicontrolpanel.
**
**
** This program is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation
** and appearing in the file LICENSE.LGPL included in the packaging
** of this file.
**
****************************************************************************/


#include "dcpskeletonwidget.h"
#include "dcpskeleton.h"
#include <mlayout.h>
#include <mlinearlayoutpolicy.h>
#include <mlabel.h>
#include <QTimer>
#include <mwidgetcreator.h>

M_REGISTER_WIDGET_NO_CREATE (SkeletonWidget)

SkeletonWidget::SkeletonWidget(QGraphicsWidget *parent)
            :DcpStylableWidget(parent)
{
    setReferer(DcpSkeleton::NoReferer);
    initWidget();

    // this demonstrates the usage of the progress indicator:
    setProgressIndicatorVisible (true);
    QTimer::singleShot ( 3000, this, SLOT(loadingFinished()) );
}

void
SkeletonWidget::loadingFinished()
{
    setProgressIndicatorVisible (false);
}

SkeletonWidget::~SkeletonWidget()
{
}


void SkeletonWidget::initWidget()
{
    MLayout *mainLayout = new MLayout(this);
    MLinearLayoutPolicy *mainLayoutPolicy =
            new MLinearLayoutPolicy(mainLayout, Qt::Horizontal);
    mainLayout->setPolicy(mainLayoutPolicy);
        
    //% "This is a skeleton applet, a minimal binaryapplet for controlpanel"
        m_aboutLabel = new MLabel(qtTrId("dcp_skel_appl_label"), this);
        m_aboutLabel->setStyleName("LabelAbout");
        
        mainLayoutPolicy->addItem(m_aboutLabel, Qt::AlignLeft);
    setLayout(mainLayout);
}

dcpskeletonwidget.cpp 

[Desktop Entry]
Type=ControlPanelApplet
Name=Skeleton
Icon=
Exec=
X-logical-id=qtn_sett_main_display
X-translation-catalog=skeletonapplet1,skeletonapplet2

# This has to be specified in order that the .desktop file can also be
# used as an action (for example for search to know how to
# open the applet)
X-Maemo-Service=com.nokia.DuiControlPanel
X-Maemo-Method=com.nokia.DuiControlPanelIf.appletPage
X-Maemo-Object-Path=/
# this has to be the same as Name
X-Maemo-Fixed-Args=Skeleton


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

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

skeleton.desktop 

TEMPLATE      = lib
CONFIG       += plugin gui meegotouch duicontrolpanel silent debug

HEADERS       = dcpskeletonapplet.h \
                dcpskeletonwidget.h \
                dcpskeletonbrief.h

SOURCES       = dcpskeletonapplet.cpp \
                dcpskeletonwidget.cpp \
                dcpskeletonbrief.cpp

DESTDIR       = ./lib
TARGET        = $$qtLibraryTarget(dcpskeletonapplet)
desktop.files += *.desktop
desktop.path = /usr/lib/duicontrolpanel
target.path += /usr/lib/duicontrolpanel/applet

INSTALLS += target \
            desktop

skeleton.pro


After unpacking them you can build, compile, and install 

qmake skeleton.pro
make
make install

After that you can start it from control panel. You can find it under "Applications" category

See also binary applets section for details.

Declarative applet

The following example illustrates how to create a declarative applet.

<?xml version='1.0' encoding='UTF-8'?>
<settings>
    <group>
        <text 
            key="/apps/ControlPanel/Example/Text1" 
            title="Example text:" >
          something
        </text>
        <text 
            key="/apps/ControlPanel/Example/Text2" 
            title="Please specify a text:">
        </text>
        <selection key="/apps/ControlPanel/Example/Enum1">
            <option title="first value">1</option>
            <option title="second value">2</option>
            <option title="third value">3</option>
            <option title="fourth value">4</option>
        </selection>
    </group>
    <group>
        <boolean 
            key="/apps/ControlPanel/Example/Bool1" 
            title="Boolean value example">
        </boolean>
        <integer 
            key="/apps/ControlPanel/Example/Integer1"
            title="Select a number" min="30" max="60">
        </integer>
    </group>
</settings>

This is the easiest way of creating an applet, but it is less flexible (currently):

See declarative applets section for details.

External applet

The following example illustrates how to create an external applet.

[Desktop Entry]
Type=Application
Name="Example External Application"
Icon=

# If this property is declared, and the applet is not loaded using the 
# X-DUIApplet-Applet property, the command will be executed when the 
# user activates the plugin in the control panel.
# This has to be specified in order that the .desktop file can also be
# used as an action (for example for search to know how to
# open the "applet")
Exec=widgetsgallery

X-logical-id=controlpanel_example_applet
X-translation-catalog=catalog1

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

See external applets section for details.

Copyright © 2009 Nokia Corporation Generated on Thu Feb 24 06:03:39 2011
Doxygen 1.6.1
Meego control panel