MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Storing and managing application settings

MeeGo 1.2 Harmattan platform allows the user to configure system and application settings conveniently in one central system, GConf, which can be accessed through the device Control Panel. The Control Panel contains Applets - also known as Settings pages - which are separate pages for individual application settings. To make your own application similarly user-friendly, consider creating an Applet for the user-editable settings of your application and making that page visible in Control Panel.

Control Panel Applets can be used to allow the device user a convenient way to customise application behaviour without having to launch the application itself. They can also be launched directly from the application with a D-Bus call.

The available options in an application's Control Panel Applet can be properties for application UI elements, enabling and disabling the event feed, or selecting the visible UI view after application launch, among other possibilities.

Control Panel Applets can be created using the declarative applet API provided by the libduicontrolpanel library in the Platform API reference. In that case you only need to create a simple XML description of the page and one .desktop file.

A declarative applet reads its information from two files:

Control Panel Applet file locations
File Location on device Description
.desktop file /usr/share/duicontrolpanel/desktops/ Contains basic information such as the name and type of the applet, and its location in the device Control Panel.
XML file /usr/share/duicontrolpanel/uidescriptions/ Describes the setup options and layout of the applet in MeeGo Touch declarative language.

A declarative applet reads all its structural information and its actions from the XML file. The declarative language allows you to create elements such as boolean toggles and sliders with integer values for this purpose. For more information on MeeGo Touch declarative syntax, see libduicontrolpanel in the Platform API reference.

When using the declarative applet API in libduicontrolpanel, the settings edited by the user are automatically stored in GConf with the keys given in the XML file. GConf key and value pairs can then be easily read and written using the libgq-gconf API. In many cases, it is a good idea to use GConf also for other, non-user editable settings such as application state information. An additional benefit of using GConf is that the data stored there is included in the system backup by default, as described in section Using Backup Framework.

In Harmattan, storing application settings in GConf with a Control Panel Applet is not the only way or the only location for storing settings, but it is the recommended one. For examples on how to use Control Panel Applets and GConf, see the following sections: