SettingPages API: API description

Setting pages are usually opened from setting items that are in a list form (setting list). Individual application settings are contained in the list as setting items. A setting item is composed of two parts: a label describing the name of the setting, and some form of control that allows the user to view and change the associated application resource. There are several different types of setting items to accommodate different types of application setting management needs. Some of these types allow the user to alter the setting value in place, embedded in the list view; however setting items include separate setting pages for this task.

The main benefit of using setting lists for managing application settings is that the setting items are directly bound to variables. Any changes to application settings performed through setting items are immediately reflected in the state of the application and vice versa. This property greatly reduces the complexity of applying changes, and thus allows the application designer to concentrate his or her effort on the actual functionality of the application.

Because the number of available settings in an application is constant in one build, setting lists can be easily constructed using only a resource file. The associated resource structures used to create setting lists, setting items, and setting pages are described in this document.

Use cases

1. Creating setting lists and items
2. Creating and using different setting items
   • Binary switch setting item
   • Text setting item
   • Enumerated text setting item
   • Alphanumeric password setting item
   • Numeric password setting item
   • Slider setting item
   • Volume setting item
   • Time setting item
   • Time offset setting item
   • Date setting item
   • IP address setting item
3. Manipulating setting items
   • Editing items from code
   • Hiding setting items
   • Defining compulsory indicator
4. Defining custom setting items
5. Loading and storing setting list and items
6. Opening setting pages from code
7. Observing setting pages
8. Handling layout changes

API class structure

In order to use setting pages in an application, the application must contain a class derived from the abstract base class CAknSettingItemList. An instance of this class then provides the actual setting list control to be used. It owns a list of setting items. CAknSettingItem provides the base class for concrete setting items in the list. Each setting item also refers to a setting page, where the user can change the setting. CAknSettingPage provides the base class for concrete setting pages.

Concrete setting items are implemented by the following classes:

• Alphanumeric password: CAknPasswordSettingItem
• Binary switch: CAknBinaryPopupSettingItem
• Date: CAknTimeOrDateSettingItem
• Enumerated text: CAknEnumeratedTextPopupSettingItem
• IP address: CAknIpFieldSettingItem
• Numeric password: CAknPasswordSettingItem
• Slider: CAknSliderSettingItem
• Text: CAknTextSettingItem
• Time: CAknTimeOrDateSettingItem
• Time offset: CAknTimeOffsetSettingItem
• Volume: CAknVolumeSettingItem

There is a special base class, CAknBigSettingItemBase, which can be used for opening another view of settings list.

Concrete setting pages are implemented by the following classes:

• Check box: CAknCheckBoxSettingPage
• Date: CAknDateSettingPage
• Duration: CAknDurationSettingPage
• Edwin: CAknEdwinSettingPage
• IP address: CAknIpFieldSettingPage
• Password: CAknPasswordSettingPage
• Radio button: CAknRadioButtonSettingPage
• Slider: CAknSliderSettingPage
• Time: CAknTimeSettingPage
• Time offset: CAknTimeOffsetSettingPage
• Volume: CAknVolumeSettingPage

As it can be seen from the lists above, there is no concrete setting item for the check box, the duration and the radio button setting pages. Either custom setting item has to be implemented for them (derived from the base class CAknSettingItem, see Defining custom setting items for more details), or lower level normal list has to be used for the list of settings and these setting pages have to be opened from it.

CAknListBoxSettingPage is an intermediate setting page class to encapsulate common list box setting page code. Concrete derived setting pages are CAknCheckBoxSettingPage, CAknPopupSettingPage and CAknRadioButtonSettingPage. CAknPopupSettingPage is the more generic of the list-style setting pages. It can be used as is or derived classes may be constructed from this.

CAknMfneSettingPage is an intermediate setting page class to encapsulate common MFNE setting page code. Concrete derived setting pages are CAknDateSettingPage, CAknTimeSettingPage, CAknDurationSettingPage, CAknTimeOffsetSettingPage and CAknIpFieldSettingPage.