MeeGo Touch Control Panel: Desktop file format of a Mcp applet

Description

Each applet should have a .desktop file. By default its location should be under /usr/share/mcontrolpanel/applets. (This can be changed with the controlpanel option -desktopdir.) The desktop file specifies information about the applet.

Format of the file

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

[Desktop Entry]
[X-MControlPanel]

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

Key=Value

The keys controlpanel 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 mcontrolpanel to pop up the applet.

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

[X-MControlPanel]

Title-Logical-Id: The translation id for the title of the applet. (The one you would write for qtTrid or trid.)

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:

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 McpAppletIf::init() function, because

each MLocale::setDefault() call will cause retranslateUi() methods to be called for all widgets which will have a big performance overhead if most applets are doing that amongs the list of a category
if you specify it though the desktop file, controlpanel can act if the language gets changed, and load the translated catalog for your applet.

Plugin

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/mcontrolpanel/applets

For a declarative applet, you have to specify "libdeclarative.so" here, and use the "Part" key to specify the xml which describes the ui.

Command: 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 Plugin will be ignored.

Category: The category name in which the launch button of the applet will be displayed. It can be one of the followings: "Look & Feel", "Sound", "Connectivity", "Regional settings", "Device utilities", "Device system", "Accounts & Applications"

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 controlpanel 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
Switch - Like "Image", but instead of the image it has a switch button next to the text
Button - A togglebutton with some text on it

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.

You will rarely need these...

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 McpAppletIf::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 controlpanel will not load the others. This key will most likely be removed soon.

Other

Binary plugin's overrides

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

An example desktop file

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

[Desktop Entry]
Type=X-McpApplet

# Name of the applet
Name=SkelButton

[X-MControlPanel]

# id for localization
Title-Logical-Id=qtn_sett_main_display

# catalog for localization
Translation-Catalog=catalog1,catalog2

# applet binary
Plugin=libmcpskeletonapplet.so

# for external app:
# Command=widgetsgallery

# The category name under which the applet will appear in Control Panel
Category=Look & Feel

# The order of the applet launch button in the Category Page of Mcp.
Order=4

# Type of the widget launch button.
WidgetType=Label