Changes

None.

Purpose

The HS Settings API is an interface that enables developers to fetch and update settings of the Home screen widget.

S60 or Symbian Excpetions

This API is valid for all platforms running on S60 release 5.2 or later.

Emulator support

This API is fully supported in the WINSCW emulator environment.

API description

The Home screen Settings API was introduced as an alternative interface to the Home screen Service API (SAPI). It provides means to access widget specific settings from non-Home screen processes, such as Control Panel. The Home screen application itself uses the Home screen Plug-in Service API to access the settings via a Language Interworking (LIW) interface. This solution requires that the inputs are both LIW wrapped and that the whole active application configuration is read from Home Screen Plug-in Service (HSPS). Due to the previous performance demanding requirements, the HS Settings API was implemented. It provides a simple and quick C++ interface for accessing the Home screen settings.

When the Home screen Settings API is instantiated, it gets stored to a thread local storage (TLS). While the Home screen Service API is instantiated, a client - server session is established between the Service API and the HSPS server. As soon as the active application configuration has been fetched to the Service API, the settings can be manipulated via the Settings API.

Use cases

Related use cases are as follows:

  • Instantiate the service/get an existing API instance

  • Get settings

  • Set settings

  • Add observer

  • Remove observer

  • Close the service

API class structure

The CHomescreenSettings class is instantiated by the client process. The Settings API instance creates an LIW interface, which is used by the Home screen plug-in Service API - indicated by the CHSPSProvider and CHSPSConfigurationIf classes in the diagram below. When the CHSPSConfigurationIf class is instantiated, an IPC session is created between the server and the client. The CHSPSThemeServer server finds the active application configuration, from which the settings are finally either retrieved or manipulated. Callbacks are provided via the LIW interfaces to the Settings API, which then notifies the observers.

Settings are defined by zero or more items, which are instantiated from the CItemMap class. Each item may have zero or more properties that were instantiated from the CPropertyMap class.


Related APIs
  • CHSPSConfigurationIf
  • CHSPSProvider
  • CHSPSThemeServer
  • CHomescreenSettings
  • CItemMap
  • CPropertyMap

Using the Home screen Settings API

Get settings

The following sequence diagram illustrates a typical use case where the end user personalizes the settings of a widget:


Example of the settings

Each widget on Home screen has its own XML-based plug-in configuration. A plug-in configuration can be retrieved from the active application configuration with a plug-in ID, which is reserved from a related pool after the widget has been added to a Home screen page.

The below example illustrates a plug-in configuration that could be used by the Desktop widget.

There is always the settings element, which has zero or more child elements with any number of "key" and "value" attributes. In the example, the Desktop widget defines four shortcut items, from which various applications can be started.


Error handling

Normal Symbian leave mechanism is used.

Memory overhead

Homescreenpluginsrv is launched automatically by the system starter when the device is switched on and sapi_homescreenplugin sessions are shared between the threads. Therefore, the memory consumption is low.

Extensions to the API

There are no extensions to the API.

Limitations of the API

There are no limitations in the API.