Home · All Namespaces · All Classes · Main Classes

Desktop file format of a Dcp applet

Description

Each applet should have a .desktop file. By default its location should be under "/usr/share/duicontrolpanel/desktops" (the path "/usr/lib/duicontrolpanel" is also supported for compatibility). (This can be changed with the control panel option -desktopdir.) The desktop file specifies information about the applet.

Category description format

The .desktop file is an ini format file, it has three sections:

In each section there are key-value entries, separated by an equal sign:

Key=Value

Mandatory keys

These keys are mandatory for any applet in order for the .desktop file to be able to function as a content action, and other applications to know how to pop up the applet (for example the search). See libcontentaction-doc if you are interested in the details, if not, just include the following in the .desktop file of the applet:

Mandatory keys for an external applet

[Desktop Entry]
Type=Application
Exec=<the command to execute>

Mandatory keys for any other applet

[Desktop Entry]
Type=ControlPanelApplet
X-Maemo-Service=com.nokia.DuiControlPanel
X-Maemo-Method=com.nokia.DuiControlPanelIf.appletPage
X-Maemo-Object-Path=/
X-Maemo-Fixed-Args=<the name of the applet, see Name section>

The keys control panel understands

[Desktop Entry]

Name
The name of the applet. Must be unique, other applets and programs will refer to the applet with its name, for example when they request control panel to pop up the applet.

Also suits as the engineering english translation of the applet's title.

X-logical-id
The translation id for the title of the applet. (The one you would write for qtTrid or trid.)
X-translation-catalog
The translation catalog(s) for the applet. (The filename(s) of its .qm file, without the extension and language ids.) More catalogs should be separated with a comma. Example:
X-translation-catalog=catalog1,catalog2,catalog3

NOTE: Please provide here all the catalog(s) the applet needs, instead of loading the catalogs through MLocale in the DcpAppletIf::init() function, because

[DUI]

X-DUIApplet-Applet
This contains the path of the shared object. It is enough if you specify the file name if your applet is under the default location: /usr/lib/duicontrolpanel/applets

For a declarative applet, you have to specify "libdeclarative.so" here.

X-DUIApplet-ApplicationCommand
A command which gets executed when the user clicks on the applet launch button. If you specify a command here, then your applet will be considered an external applet and the shared object you optionally specified at X-DUIApplet-Applet will be ignored.

[DCP]

Category
The category name in which the launch button of the applet will be displayed. The list of categories are described in .cpcategory ini files under /usr/share/duicontrolpanel/categories. You can identify a category by its Name or Name-logical-id.
Order
A number which specifies the position of the launch button inside its category. For example if according to the design your button is at the 3rd row in portrait mode, and in the 2nd row 1st column in landscape mode, than you should specify 3 here. However if an applet is missing which would have a lower order value, than your applet will move upper, because control panel does not put holes in place of non installed applets.
WidgetType
The widget type of the launch button. Can be one of the following:
  • Label - Button with the applet title and optionally a value text
  • Image - Like Label, and an image
  • Toggle - Like Label with a toggle button on the right
  • Button - A big button with the applet title on it which can be toggled.
  • Slider - A slider, optionally with two icons on the left and right side without any labels
HelpId
This can contain a help page id (see userguide's documentation) for the applet. If specified, a help button will be put on the icon / next to the icon of the applet, and if the user presses it, the requested page of the current help application gets openned.
Text2
Specifies the text on the second line of the launch button. It can be used for displaying a static value line, eg. explanation about what the applet is, and also with a dynamic value line, as a placeholder until the applet got loaded and supplies its value from the DcpBrief.
Text2-logical-id
Specifies the logical id for Text2 in the translation catalogs.
Image
Specifies the image name for the image type launch button. Preferably its value should be an image id, like you would do for MTheme. It also supports a direct path to the image but try to avoid using that if you can.
Part
For binary plugins, if this value contains the name of an applet part, then that part of the applet will be openned when the user presses the launch button. If you omit this, your applet will be started on its first page. You can freely choose the part name, but it should be implemented in DcpAppletIf::partID(). Example: A part string for the clock page on the time applet can be "Clock". For declarative plugins this value contains the name of the xml file, which describes the content of their main widget.
Unique
Only for testing. The first applet which has a 1 here, will be alone, and control panel will not load the others. This key will most likely be removed soon.
DoNotShowOnProduct
It can contain a list of product names (see /proc/component_version | grep product), on which the applet should be hidden by controlpanel. An invisible applet will not be displayed in any of the categories.
OnlyShowOnProduct
It can contain a list of product names, the only ones on which the applet should be visible. Overrides DoNotShowOnProduct.
HasMainView
Through the value of this key the plugin can specify if it has a main view (the applet can be openned or not). If false, the controlpanel will not show the mainpage of the applet when the user clicks on it in the list. Default is true for most, except for Button and Toggle type of applets, the letters default to having no main view.
SliderLeftImage, SliderRightImage
It can define a static icon on the left and right side of a "Slider" type briefview. Similarly to "Image", its value can be a theme id, or a path to an image.
TextOrientation
Defines the orientation of the two text label of the icon. It can have the value "Vertical" (which is the default), in which case the two labels (title and value line) will be under each other, or it can have the value "Horizontal", in which case the two labels will be next to each other.

Other

Binary plugin's overrides

A binary plugin can override some values specified in the desktop file by its interface (DcpBrief, DcpAppletIf).

An example desktop file

In case of a binary plugin for Date & Time applet, the desktop file can look like this:

[Desktop Entry]
# Some common things to specify:
Type=ControlPanelApplet
X-Maemo-Service=com.nokia.DuiControlPanel
X-Maemo-Method=com.nokia.DuiControlPanelIf.appletPage
X-Maemo-Object-Path=/
X-Maemo-Fixed-Args=Date & Time

# Name of the applet
Name=Date & Time

# id for localization
X-logical-id=qtn_sett_main_date_time

# catalog for localization
X-translation-catalog=settings-datetime

[DUI]
# applet binary
X-DUIApplet-Applet=libdatetimeapplet.so

[DCP]
# The category name under which the applet will appear in Control Panel
Category= Regional settings

# The order of the applet launch button in the Category Page of Dcp.
Order=1

# Type of the widget launch button.
WidgetType=Label

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