SettingPages API: Using Setting Pages API

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[];
    }

Table 1: 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
    }

Table 2: 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.

Table 3: 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.

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.

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.

Figure 4: Message reception

Figure 5: Binary switch setting item and binary switch setting page

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;
    }

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.

Figure 6: Text setting item

Figure 7: Text setting item and text setting page

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.

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.

Figure 8: Enumerated text setting item

Figure 9: Enumerated text setting item and enumerated text setting page

Figure 10: Enumerated text’s user defined text editor

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;

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

Figure 11: Alphanumeric password setting item

Figure 12: Alphanumeric password setting item and password setting page

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;

Numeric password setting item

The password setting item allows the input of secret data. Password setting items can be either alphanumeric (see 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.

Figure 13: Numeric password setting item

Figure 14: Numeric password setting item and password setting page

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;

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.

Figure 15: Slider setting item

Figure 16: Slider setting item and slider setting page

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;

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.

Figure 17: Volume setting item

Figure 18: Volume setting item and volume setting page

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;

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.

Figure 19: Time setting item

Figure 20: Time setting item and time setting page

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;

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.

Figure 21: Time offset setting item

Figure 22: Time offset setting item and time offset setting page

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;

Date setting item

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

Figure 23: Date setting item

Figure 24: Date setting item and date setting page

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;

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.

Figure 25: IP address setting item

Figure 26: IP address setting item and IP address setting page

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;

Manipulating setting items

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

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;
        }
    }

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.

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.

Figure 27: Compulsory item indicator

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";
            },
            …

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 );
        }
    }

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

Opening setting pages from code

The example code in Defining custom setting items also illustrates how to open a check box setting page from the setting item’s overridden EditItemL method.

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!

Handling layout changes

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

  1. The application UI or view has to set the rectangle to the concrete settings list when HandleResourceChangeL is called.
  2. 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() );
        }
    }

Error handling

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

Memory overhead

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

Limitations of the API

None.

Copyright © Nokia Corporation 2001-2008
Back to top