Setting Pages API Specification

Contents 1 Overview 1.1 Description 1.2 Changes 1.3 Use Cases 1.4 Class Structure 2 Using The API 2.1 Creating setting lists and items 2.2 Creating and using different setting items 2.2.1 Binary switch setting item 2.2.2 Text setting item 2.2.3 Enumerated text setting item 2.2.4 Alphanumeric password setting item 2.2.5 Numeric password setting item 2.2.6 Slider setting item 2.2.7 Volume setting item 2.2.8 Time setting item 2.2.9 Time offset setting item 2.2.10 Date setting item 2.2.11 IP address setting item 2.3 Manipulating setting items 2.3.1 Editing items from code 2.3.2 Hiding Setting Items 2.3.3 Defining compulsory indicator 2.4 Defining custom setting items 2.5 Loading and storing setting list and items 2.6 Opening setting pages from code 2.7 Observing setting pages 2.8 Handling layout changes 2.9 Error handling 2.10 Memory and Performance Considerations 3 Glossary 3.1 Abbreviations

1 Overview

Setting pages provide a uniform way to present application settings to users on the S60 platform. This document describes the creation, use, and manipulation of setting lists, setting items and setting pages.

API category	public
API type	c++
Existed since	Legacy S60 0.9
API libraries	avkon.lib
Location	/sf/mw/classicui/classicui_pub/setting_pages_api
Buildfiles	/sf/mw/classicui/classicui_pub/setting_pages_api/group/bld.inf

1.1 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.

1.2 Changes

Setting Pages API is an SDK API and was first published in S60 release 0.9.

This API is valid for all platforms running on Symbian OS 9.1 or later.

1.3 Use Cases

• Creating setting lists and items
• 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

• Manipulating setting items
• Editing items from code
• Hiding setting items
• Defining compulsory indicator

• Defining custom setting items
• Loading and storing setting list and items
• Opening setting pages from code
• Observing setting pages
• Handling layout changes

1.4 Class Structure

Summary of API classes and header files

Classes	Files

CAknAlphaPasswordSettingPage /epoc32/include/mw/aknpasswordsettingpage.h CAknBigSettingItemBase /epoc32/include/mw/aknsettingitemlist.h CAknBinaryPopupSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknCheckBoxSettingPage /epoc32/include/mw/akncheckboxsettingpage.h CAknDateSettingPage /epoc32/include/mw/aknmfnesettingpage.h CAknDurationSettingPage /epoc32/include/mw/aknmfnesettingpage.h CAknEdwinSettingPage /epoc32/include/mw/akntextsettingpage.h CAknEnumeratedItem /epoc32/include/mw/aknsettingitemlist.h CAknEnumeratedItemBase /epoc32/include/mw/aknsettingitemlist.h CAknEnumeratedTextPopupSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknEnumeratedTextSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknIntegerEdwinSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknIntegerSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknIntegerSettingPage /epoc32/include/mw/akntextsettingpage.h CAknIpFieldSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknIpFieldSettingPage /epoc32/include/mw/aknmfnesettingpage.h CAknMfneSettingPage /epoc32/include/mw/aknmfnesettingpage.h CAknNumericPasswordSettingPage /epoc32/include/mw/aknpasswordsettingpage.h CAknPasswordSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknPasswordSettingPage /epoc32/include/mw/aknpasswordsettingpage.h CAknRadioButtonSettingPage /epoc32/include/mw/aknradiobuttonsettingpage.h CAknSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknSettingItemArray /epoc32/include/mw/aknsettingitemlist.h CAknSettingItemList /epoc32/include/mw/aknsettingitemlist.h CAknSettingPage /epoc32/include/mw/aknsettingpage.h CAknSliderSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknSliderSettingPage /epoc32/include/mw/aknslidersettingpage.h CAknTextSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknTextSettingPage /epoc32/include/mw/akntextsettingpage.h CAknTimeOffsetSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknTimeOffsetSettingPage /epoc32/include/mw/aknmfnesettingpage.h CAknTimeOrDateSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknTimeSettingPage /epoc32/include/mw/aknmfnesettingpage.h CAknVolumeSettingItem /epoc32/include/mw/aknsettingitemlist.h CAknVolumeSettingPage /epoc32/include/mw/aknvolumesettingpage.h CSelectableItem /epoc32/include/mw/akncheckboxsettingpage.h CSelectionItemList /epoc32/include/mw/akncheckboxsettingpage.h CSettingpageSplitInputHelper /epoc32/include/mw/aknsettingpage.h MAknSettingPageObserver /epoc32/include/mw/aknsettingpage.h SAknConfirmationResource /epoc32/include/mw/aknpasswordsettingpage.h TAknDesCArrayDecorator /epoc32/include/mw/AknDesCArrayDecorator.h

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 [Setting_Pages_API_Specification.topic3.4 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 .

2 Using The API

2.1 Creating setting lists and items

In order to use setting lists 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. This derived class is required to override and implement the method used to create the setting items. Minimal declaration of this derived setting list class is presented in the following code sample:

class CMySettingList : public CAknSettingItemList
    {
    public:

        void ConstructL();
        CAknSettingItem* CreateSettingItemL( TInt aIdentifier );

    private:

        TBool iFlag;
    };

The declaration of the class CMySettingList provides one data member iFlag , which contains the binary value of the only setting item - the binary switch - in our example setting list.

The construction requires initialization of the base class with the resource of type AVKON_SETTING_ITEM_LIST . This resource will be described later with concrete examples.

void CMySettingList::ConstructL()
    {
    CAknSettingItemList::ConstructFromResourceL( R_MY_SETTING_LIST_RESOURCE );
    }

Note that CAknSettingItemList::ConstructFromResourceL creates a window if none has been defined!

The construction of CMySettingList in the application UI's ConstructL would then look like:

void CMyAppUi::ConstructL()
    {
    BaseConstructL( EAknEnableSkin );
    iSettingView = new (ELeave) CMySettingList;
    // Destructor will delete iSettingView.
    iSettingView->SetMopParent(this);
    iSettingView->ConstructL();
    AddToStackL(iSettingView);
    iSettingView->MakeVisible(ETrue);
    iSettingView->SetRect(ClientRect());
    iSettingView->ActivateL();
    }

The implementation of the method CreateSettingItemL is presented in the following code sample:

CAknSettingItem* CMySettingList::CreateSettingItemL( TInt aIdentifier )
    {
    CAknSettingItem* settingItem = NULL;

    switch (aIdentifier)
        {
        case EMySettingItemBinary:
            settingItem =
                new (ELeave) CAknBinaryPopupSettingItem(aIdentifier, iFlag);
            break;
        }

    return settingItem;
    }

This method reveals a common pattern used with setting lists: the CreateSettingItemL contains a switch-case block with a case statement block for each setting item. This case block typically contains only one statement - the instantiation of the respective setting item object. Also, this instantiation follows the same pattern for each setting item. The constructor of the specific setting item class takes two parameters: the setting item identifier as passed to the CreateSettingItemL method and a reference to the associated variable.

The example setting list class described in this chapter has one shortcoming - it does not follow the Model-View-Controller (MVC) design pattern. In the MVC design pattern, the view, the model, and the controller should be separated, and in the example, all of these components are implemented in one class. In a real-world application it is useful to have a separate class for the settings data, and pass an instance of this class to the derived setting list class. Doing so also ensures the proper separation of the user interface and the application engine.

The setting lists are created from resource definitions. The main resource structure used is AVKON_SETTING_ITEM_LIST , defined in avkon.rh as follows:

STRUCT AVKON_SETTING_ITEM_LIST
    {
    WORD flags = 0; // Allowed values: EAknSettingItemListNumberedStyle
    LTEXT title = "";
    WORD initial_number = 1;
    STRUCT items();
    }

Setting item list resource structure

Field	Meaning
Flags	Specifies the numbering style applied to the setting list. With no flags specified, the setting list is not numbered and the flag EAknSettingItemNumberedStyle enables numbering. In conjunction with this, flag EAknSettingItemIncludeHiddenInOrdinal also enables numbering of hidden setting items on the list.
Title	This field is not used.
Items	An array of all setting items contained in this setting list. The setting items are declared using the AVKON_SETTING_ITEM resource structure.
initial_number	Specifies the number of the first item in the setting list. The default value is 1.

STRUCT AVKON_SETTING_ITEM
    {
    WORD identifier = 0;
    LTEXT name = "";
    LLINK setting_page_resource = 0;
    WORD type = 0xffff;
    LLINK setting_editor_resource = 0;
    LLINK associated_resource = 0;
    LTEXT empty_item_text = "";
    LTEXT compulsory_ind_string = "";
    LLINK reserved = 0;  // Added for extensions
    }

Setting item resource structure

Field	Meaning
identifier	Specifies an identifier to the setting item. This code is passed to the CreateSettingItemL method as an aIdentifier argument. These values are typically defined in an enumeration in the project's HRH file.
setting_page_resource	Reference to a resource defining the setting page associated with this setting item. The setting page resource is declared using the AVKON_SETTING_PAGE resource structure.
Name	Specifies the title of the item.
compulsory_ind_string	Specifies the compulsory indicator string for the setting item (see Figure 27).
associated_resource	Reference to an associated resource. The interpretation of this field depends on the setting item. For example, it is used to specify the pop-up list containing the choices associated with the enumerated text setting item.

The identifier and setting_page_resource fields are mandatory in the AVKON_SETTING_ITEM structure; others are optional.

The setting page associated with a setting item is specified with the AVKON_SETTING_PAGE resource structure.

STRUCT AVKON_SETTING_PAGE
    {
    WORD number = EAknSettingPageNoOrdinalDisplayed;
    LTEXT label;
    LTEXT hint_text;
    LLINK softkey_resource = 0;
    LLINK menubar = 0;
    WORD type=0xffff;
    LLINK editor_resource_id = 0;
    LLINK invalid_contents_softkey_resource = 0;
    LLINK extension = 0;
    }

The most important fields in this structure are summarized below.

Setting page resource structure

Field	Meaning
Type	Specifies the type of control used to edit the setting item.
editor_resource_id	Reference to the editor control resource.
Label	Specifies the title of the setting page.
hint_text	Specifies the hint text displayed in the navigation pane.
number	Specifies the number of the setting item. This number is displayed in the top left corner of the setting page. The default for this field is the special value EAknSettingPageNoOrdinalDisplayed , which specifies that the number is not displayed.

Even though the default resources here for the menu bar and the soft keys (CBA) are zero, there are defaults provided in the class implementation: the menubar resource is R_AVKON_MENUPANE_EMPTY , the softkeys resource is R_AVKON_SOFTKEYS_OK_CANCEL .

2.2 Creating and using different setting items

There are different setting items available on the S60 platform. These items, associated resource structures and classes are described in the following sections.

2.2.1 Binary switch setting item

The binary switch is the simplest of the setting items: it allows the setting to be either on or off. Due to its simplicity it is not necessary to open a setting page to change the value of it: if the Selection key is pressed, then the value is changed. However, the binary switch setting item has a separate setting page; the binary value can be changed from there too. The value of the binary switch setting item is backed up with a Boolean variable of type TBool in the application setting data.

The setting item class used with the binary switch type is CAknBinaryPopupSettingItem .

Here is an example of a binary switch resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_binary
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting list";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemBinary;
            setting_page_resource = r_binary_setting_page;
            associated_resource = r_popup_setting_binary_texts;
            name = "Message reception";
            }
        };
    }

RESOURCE AVKON_POPUP_SETTING_TEXTS r_popup_setting_binary_texts
    {
    flags = 0;
    setting_texts_resource = r_on_off_texts;
    popped_up_texts_resource = r_popped_up_on_off_texts;
    }

RESOURCE ARRAY r_on_off_texts
    {
    items =
        {
        AVKON_ENUMERATED_TEXT { value = 1; text = "On"; },
        AVKON_ENUMERATED_TEXT { value = 0; text = "Off"; }
        };
    }

RESOURCE ARRAY r_popped_up_on_off_texts
    {
    items =
        {
        LBUF { txt = "Enabled"; },
        LBUF { txt = "Disabled"; }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_binary_setting_page
    {
    number = 0;
    label = "Message reception";
    type = EAknCtPopupSettingList;
    editor_resource_id = r_binary_popup_setting_list;
    }

RESOURCE POPUP_SETTING_LIST r_binary_popup_setting_list
    {
    flags= 0;
    }

The corresponding CreateSettingItemL must construct the item:

CAknSettingItem* CMySettingList::CreateSettingItemL( TInt aIdentifier )
    {
    CAknSettingItem* settingItem = NULL;

    switch (aIdentifier)
        {
        case EMySettingItemBinary:
            settingItem =
                new (ELeave) CAknBinaryPopupSettingItem(aIdentifier, iFlag);
            break;
        }

    return settingItem;
    }

2.2.2 Text setting item

The text setting item allows users to enter text as the value of the setting. The value of the setting is stored in a user-specified descriptor. The setting item class used with the text editor type is CAknTextSettingItem .

Here is an example of a text editor setting item resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_text
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting list";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemText;
            setting_page_resource = r_text_setting_page;
            name = "Company name";
            }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_text_setting_page
    {
    number = 1;
    label = "Company name";
    type = EEikCtEdwin;
    editor_resource_id = r_settinglist_edwin;
    }

RESOURCE EDWIN r_settinglist_edwin
    {
    maxlength = 30;
    }

The corresponding CreateSettingItemL must construct the item:

        …
        case EMySettingItemText:
            settingItem =
                new (ELeave) CAknTextSettingItem(aIdentifier, iTextBuf);
            // where iTextBuf is TBuf<KMyAppMaxSettingTextSize>
            break;

About proper initialization of the EDWIN resource, see Editors API for more information.

2.2.3 Enumerated text setting item

The enumerated text setting item gives users a list of options to select from. It is also possible to enter a text value to the setting item other than the ones listed; this can be done by selecting "Other" from the pop-up list. This option is available only if EAknPopupSettingListFlagAllowsUserDefinedEntry flag is set in POPUP_SETTING_LIST resource (also there is a SetAllowsUserDefinedEntry method). Thus, there are actually three different views for the enumerated text setting item: the setting item contained in the setting list, the setting page showing the available choices, and the text editor page for entering free-formed text, which allows inputting of non-predefined values. The setting value is stored in the descriptor supplied on construction of the setting item.

The setting item class used with enumerated text type is CAknEnumeratedTextPopupSettingItem .

Here is an example of an enumerated text setting item resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_enumtext
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting list";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemEnumText;
            setting_page_resource = r_enumtext_setting_page;
            associated_resource = r_popup_setting_list;
            name = "My favourite color";
            }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_enumtext_setting_page
    {
    number = 1;
    label = "My favourite color";
    type = EAknCtPopupSettingList;
    editor_resource_id = r_popup_setting_list_new_entry
    }

RESOURCE AVKON_POPUP_SETTING_TEXTS r_popup_setting_list
    {
    setting_texts_resource = r_settinglist_page_list;
    }

RESOURCE ARRAY r_settinglist_page_list
    {
    items =
        {
        AVKON_ENUMERATED_TEXT {value = 0; text = "Red";},
        AVKON_ENUMERATED_TEXT {value = 1; text = "Green";},
        AVKON_ENUMERATED_TEXT {value = 2; text = "Blue";}
        };
    }

RESOURCE POPUP_SETTING_LIST r_popup_setting_list_new_entry
    {
    flags = EAknPopupSettingListFlagAllowsUserDefinedEntry;
    }

The corresponding CreateSettingItemL must construct the item:

        …
        case EMySettingItemEnumText:
            settingItem = new (ELeave) CAknEnumeratedTextPopupSettingItem
                                       (aIdentifier, iSelectedItemIndex);
            break;

2.2.4 Alphanumeric password setting item

The password setting item allows the input of secret data. Password setting items can be either alphanumeric (for passwords) or numeric (see [Setting_Pages_API_Specification.topic3.2.5 Numeric password setting item]). The setting value is stored in the descriptor supplied on construction of the setting item.

The setting item class used with password type is CAknPasswordSettingItem .

Here is an example of an alphanumeric password setting item resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_pw
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting list";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemPassAlph;
            setting_page_resource = r_alpha_password_setting_page;
            name = "Password";
            }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_alpha_password_setting_page
    {
    number = 1;
    label = "Enter Password";
    type = EEikCtSecretEd;
    editor_resource_id = r_settinglist_alpha_password;
    }

RESOURCE SECRETED r_settinglist_alpha_password
    {
    num_letters = 8;
    }

The corresponding CreateSettingItemL must construct the item:

        …
        case EMySettingItemPassAlph:
            settingItem = new (ELeave) CSettingAppPasswordSettingItem
                                       (aIdentifier,
                                       CAknPasswordSettingItem::EAlpha,
                                       iPwd );
            // where iPwd is TBuf<KMyAppMaxPasswordTextSize>
            break;

2.2.5 Numeric password setting item

The password setting item allows the input of secret data. Password setting items can be either alphanumeric (see [Setting_Pages_API_Specification.topic3.2.4 Alphanumeric password setting item]) or numeric (for PIN codes). The setting value is stored in the descriptor supplied on construction of the setting item.

The setting item class used with password type is CAknPasswordSettingItem .

Here is an example of a numeric password setting item resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_pin
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting list";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemPassNumber;
            setting_page_resource = r_numeric_password_setting_page;
            name = "PIN code";
            }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_numeric_password_setting_page
    {
    number = 1;
    label = "Enter PIN code";
    type = EAknCtNumericSecretEditor;
    editor_resource_id = r_settinglist_numeric_password;
    }

RESOURCE NUMSECRETED r_settinglist_numeric_password
    {
    num_code_chars = 4;
    }

The corresponding CreateSettingItemL must construct the item:

        …
        case EMySettingItemPassNumber:
            settingItem = new (ELeave) CSettingAppPasswordSettingItem
                                       (aIdentifier,
                                       CAknPasswordSettingItem::ENumeric,
                                       iPin );
            // where iPin is TBuf<KMyAppMaxPasswordTextSize>
            break;

2.2.6 Slider setting item

The slider setting item allows users to specify an integer value. The integer value has a minimum and maximum value and the control visualization is done using a slider control. The slider setting item value is stored to the supplied integer variable of type TInt .

The setting item class used with slider type is CAknSliderSettingItem .

Here is an example of a slider setting item resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_slider
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting page";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemSlider;
            setting_page_resource = r_slider_setting_page;
            name = "Brightness";
            }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_slider_setting_page
    {
    number = 1;
    label = "Brightness";
    type = EAknCtSlider;
    editor_resource_id = r_settinglist_slider;
    }

RESOURCE SLIDER r_settinglist_slider
    {
    layout = EAknSettingsItemSliderLayout;
    minvalue = 0;
    maxvalue = 100;
    step = 5;
    valuetype = EAknSliderValueDecimal;
    minlabel = "Dark";
    maxlabel = "Bright";
    }

The corresponding CreateSettingItemL must construct the item:

        …
        case EMySettingItemSlider:
            settingItem = new (ELeave) CAknSliderSettingItem
                                       (aIdentifier, iSliderValue);
            break;

2.2.7 Volume setting item

The volume setting item is similar to the slider setting item because it stores its value in an integer variable. However, the range of the volume control is fixed between 1 and 10. In addition, there is no layout control for the setting page.

The setting item class used with volume control type is CAknVolumeSettingItem .

Here is an example of a volume control setting item resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_volume
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting list";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemVolume;
            setting_page_resource = r_volume_setting_page;
            name = "Volume";
            }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_volume_setting_page
    {
    number = 1;
    label = "Volume";
    type = EAknCtVolumeControl;
    editor_resource_id = r_settinglist_volume;
    }

RESOURCE VOLUME r_settinglist_volume
    {
    flags = ESettingsVolumeControl;
    value = 1;
    }

The corresponding CreateSettingItemL must construct the item:

        …
        case EMySettingItemVolume:
            settingItem = new (ELeave) CAknVolumeSettingItem
                                       (aIdentifier, iVolume);
            break;

2.2.8 Time setting item

The time setting item is used with settings with a time value. The associated variable type with this setting item is TTime . The setting item class used with time and date setting items is CAknTimeOrDateSettingItem . The exact type (time or date) is specified by the second argument of the constructor.

Here is an example of a time setting item resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_time
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting list";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemTime;
            setting_page_resource = r_time_setting_page;
            name = "Current time";
            }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_time_setting_page
    {
    number = 1;
    label = "Enter current time";
    type = EEikCtTimeEditor;
    editor_resource_id = r_settinglist_time_editor;
    }

RESOURCE TIME_EDITOR r_settinglist_time_editor
    {
    minTime = TIME
        {
        second = 0;
        minute = 0;
        hour = 0;
        };
    maxTime = TIME
        {
        second = 59;
        minute = 59;
        hour = 23;
        };
    }

The corresponding CreateSettingItemL must construct the item:

        …
    case EMySettingItemTime:
        settingItem = new (ELeave) CAknTimeOrDateSettingItem
                                   (aIdentifier,
                                   CAknTimeOrDateSettingItem::ETime,
                                   iTime);
        break;

2.2.9 Time offset setting item

The time offset setting item is used with settings with a time interval value. The associated variable type with this setting item is TTimeIntervalSeconds . The setting item class used with time offset setting item is CAknTimeOffsetSettingItem .

Here is an example of a time offset setting item resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_time_offset
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting list";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemTimeOffset;
            setting_page_resource = r_timeoffset_setting_page;
            name = "Time offset";
            }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_timeoffset_setting_page
    {
    number = 1;
    label = "Enter time offset";
    type = EEikCtTimeOffsetEditor;
    editor_resource_id = r_settinglist_timeoffset_editor;
    }

RESOURCE TIME_OFFSET_EDITOR r_settinglist_timeoffset_editor
    {
    minTimeOffset = TIME_OFFSET { seconds = -43200; };
    maxTimeOffset = TIME_OFFSET { seconds = 43200; };
    flags = EEikTimeWithoutSecondsField | EEikTimeZoneOffsetFormat;
    }

The corresponding CreateSettingItemL must construct the item:

      …
    case EMySettingItemTimeOffset:
        settingItem = new (ELeave) CAknTimeOffsetSettingItem
                                   (aIdentifier,
                                   iTimeOffset);
        break;

2.2.10 Date setting item

The date setting item is similar to the time setting item, with the obvious exception that it accepts date values.

Here is an example of a time setting item resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_date
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting list";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemDate;
            setting_page_resource = r_date_setting_page;
            name = "Current date";
            }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_date_setting_page
    {
    label = "Enter current date";
    type = EEikCtDateEditor;
    editor_resource_id = r_settinglist_date;
    }

RESOURCE DATE_EDITOR r_settinglist_date
    {
    minDate = DATE { year = 1980; };
    maxDate = DATE { year = 2060; };
    flags = 0;
    }

The corresponding CreateSettingItemL must construct the item:

        …
    case EMySettingItemDate:
        settingItem = new (ELeave) CAknTimeOrDateSettingItem
                                   (aIdentifier,
                                   CAknTimeOrDateSettingItem::EDate,
                                   iDate);
        break;

2.2.11 IP address setting item

The IP address setting item allows users to manipulate IP address settings. The variable type associated with this setting item is TInetAddr .

The setting item class used with the IP address type is CAknIpFieldSettingItem . Note that IPv6 is not supported by the class.

Here is an example of an IP address setting item resource definition:

RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_ip
    {
    flags = EAknSettingItemNumberedStyle;
    title = "Setting list";
    initial_number = 1;
    items =
        {
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemIpAddress;
            setting_page_resource = r_ip_address_setting_page;
            name = "Server address";
            }
        };
    }

RESOURCE AVKON_SETTING_PAGE r_ip_address_setting_page
    {
    label = "Enter server address";
    type = EAknCtIpFieldEditor;
    editor_resource_id = r_settinglist_ip_editor;
    }

RESOURCE IP_FIELD_EDITOR r_settinglist_ip_editor
    {
    min_field_values = IP_FIELD
        {
        first_field = 0;
        second_field = 0;
        third_field = 0;
        fourth_field = 0;
        };
    max_field_values = IP_FIELD
        {
        first_field = 128; // Something different than 255
        second_field = 255;
        third_field = 255;
        fourth_field = 255;
        };
    flags = 0;
    }

The corresponding CreateSettingItemL must construct the item:

        …
    case EMySettingItemIpAddress:
        settingItem = new (ELeave) CAknIpFieldSettingItem
                                   (aIdentifier, iIpAddress);
        // iIpAddress has the type TInetAddr
        break;

2.3 Manipulating setting items

The setting items have a few properties that can be manipulated at runtime.

2.3.1 Editing items from code

When the OK key is pressed, an item is changed or the corresponding setting page is opened. This behavior can be done from code by calling EditItemL with the item's index:

void CMyAppUi::HandleCommandL(TInt aCommand)
    {
    switch ( aCommand )
        {
        case EMyCmdEditItem:
             // Edit the first item with index 0
             iMySettingList->EditItemL(0, ETrue);
             break;
        }
    }

2.3.2 Hiding Setting Items

Setting items can be hidden. When a setting item is hidden, it is not shown on the setting list. This allows the application designer to choose which items are applicable at a given time depending on the values of other setting items or application context. Hiding setting items is done by calling the SetHidden method on the setting item.

Hiding setting items may affect the numbering of other items in the setting list, depending on the presence of the EAknSettingItemIncludeHiddenInOrdinal flag in the flags field of the setting list resource definition.

2.3.3 Defining compulsory indicator

Setting items can be marked as compulsory. The compulsory marking is shown to the left of the setting item name in the setting list. This indicator can be altered by setting the compulsory_ind_string field of the corresponding AVKON_SETTING_ITEM resource or calling the SetCompulsoryIndTextL method from code. It can be specified as an arbitrary text.

In the following example two items are specified in resource with different compulsory indicator strings.

        …
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemDateSettingId;
            name = "Current date";
            setting_page_resource = r_date_setting_page;
            compulsory_ind_string = "*";
            },
        AVKON_SETTING_ITEM
            {
            identifier = EMySettingItemTimeSettingId;
            name = "Current time";
            setting_page_resource = r_time_setting_page;
            compulsory_ind_string = "M";
            },
            …

2.4 Defining custom setting items

There is no concrete setting item for example for the check box setting page. The following example illustrates how to define a custom check box setting item derived from the base class CAknSettingItem . The corresponding setting page resource must have the type EAknSetListBox .

class CMyCheckBoxSettingItem : public CAknSettingItem
    {
    public:
        CMyCheckBoxSettingItem( TInt aIdentifier );
        ~CMyCheckBoxSettingItem();
    protected:
        void EditItemL( TBool aCalledFromMenu );
    private:
        CSelectionItemList* iSelectionList;
    };

CMyCheckBoxSettingItem::CMyCheckBoxSettingItem( TInt aIdentifier )
:   CAknSettingItem( aIdentifier )
    {
    }

CMyCheckBoxSettingItem::~CMyCheckBoxSettingItem()
    {
    if (iSelectionList)
        {
        iSelectionList->ResetAndDestroy();
        delete iSelectionList;
        }
    }

void CMyCheckBoxSettingItem::EditItemL( TBool /*aCalledFromMenu*/ )
    {
    if ( iSelectionList )
        {
        iSelectionList->ResetAndDestroy();
        delete iSelectionList;
        iSelectionList = 0;
        }
    iSelectionList = new (ELeave) CSelectionItemList( 2 );

    for ( TInt ii=0; ii < KNumberItems; ii++ )
        {
        TBuf<80> text;
        text.Format( _L("checkline %d"), ii );
        CSelectableItem* selectionItem =
            new (ELeave) CSelectableItem( text, EFalse );
        CleanupStack::PushL( selectionItem );
        selectionItem->ConstructL();
        iSelectionList->AppendL( selectionItem );
        CleanupStack::Pop( selectionItem );
        }

    CAknCheckBoxSettingPage* settPage =
        new (ELeave) CAknCheckBoxSettingPage
                   ( SettingPageResourceId(), iSelectionList );
    CleanupStack::PushL( settPage );
    SetSettingPage( settPage );
    SettingPage()->SetSettingPageObserver( this );
    SetUpStandardSettingPageL();
    CleanupStack::Pop( settPage );
    TBool accepted = SettingPage()->ExecuteLD
        ( CAknSettingPage::EUpdateWhenChanged );
    // ExecuteLD destroys the setting page, so set it to zero:
    SetSettingPage( 0 );

    if ( accepted )
        {
        TBuf<40> text;
        for ( TInt jj=0; jj < KNumberItems; jj++)
            {
            if ( (*iSelectionList)(jj)->SelectionStatus() )
                {
                TBuf<4> newtext;
                newtext.Format( _L("%d,"), jj );
                text.Append( newtext );
                }
            }

        User::InfoPrint( text );
        }
    }

2.5 Loading and storing setting list and items

CAknSettingItemList implements two methods for loading the storing all the items in the list: LoadSettingsL and StoreSettingsL . They call LoadL or StoreL respectively on each item in the list. Derived classes of the setting item should override LoadL or StoreL if they want to do additional operation when an item is loaded or saved. In the following example CMySettingItem is derived from CAknTextSettingItem :

void CMySettingItem::LoadL()
    {
    // Fetch the text from e.g. a database.
    CAknTextSettingItem::LoadL();
    }

void CMySettingItem::StoreL()
    {
    CAknTextSettingItem::StoreL();
    // Store the text e.g. in a database.
    }

2.6 Opening setting pages from code

The example code in [Setting_Pages_API_Specification.topic3.4 Defining custom setting items] also illustrates how to open a check box setting page from the setting item's overridden EditItemL method.

2.7 Observing setting pages

Setting pages can be observed with the help of the MAknSettingPageObserver observer interface. The observer is notified about events like the setting changed, the setting page cancelled or accepted.

It is important to note that the setting page does not maintain a list of observers - it maintains only one observer reference!

2.8 Handling layout changes

In order that derived concrete classes of CAknSettingItemList handle layout changes properly:

• The application UI or view has to set the rectangle to the concrete settings

list when HandleResourceChangeL is called.

• The concrete settings list has to implement SizeChanged() as

shown below.

void CMyAppUi::HandleResourceChangeL( TInt aType )
    {
    CAknAppUi::HandleResourceChangeL( aType );
    if ( iMySettingsList->IsVisible() )
        {
        iMySettingsList->SetRect( ClientRect() );
        }
    }

void CMySettingsList::SizeChanged()
    {
    if ( ListBox() )
        {
        ListBox()->SetRect( Rect() );
        }
    }

2.9 Error handling

Setting Pages API uses standard Symbian OS error reporting mechanism and standard error codes.

2.10 Memory and Performance Considerations

Memory consumption of Setting Pages depends on the number of the contained controls.

3 Glossary

3.1 Abbreviations

Setting Pages API abbreviations

API	Application Programming Interface
CBA	Command Button Area
IP	Internet Protocol. IP version 4 addresses are composed of four integer values ranging from 0 to 255 delimited with dots. IPv6 increases the address size from 32 bits to 128 bits.
MFNE	Multi-Field Number Editor
MVC	Model-View-Controller design pattern.
OS	Operating System
SDK	Software Development Kit