Setting Pages API Specification

Changes in Setting Pages API documentation

1.0	25.10.2006	Approved

Changes in Setting Pages API

1.0	First release

Purpose

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

Constraints

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

Classification and release information

Setting Pages API is an SDK 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

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

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.

Setting Pages API

Concrete setting item classes

Concrete setting page classes

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 .

Related APIs

CAknBigSettingItemBase
CAknBinaryPopupSettingItem
CAknCheckBoxSettingPage
CAknDateSettingPage
CAknDurationSettingPage
CAknEdwinSettingPage
CAknEnumeratedTextPopupSettingItem
CAknIpFieldSettingItem
CAknIpFieldSettingPage
CAknListBoxSettingPage
CAknMfneSettingPage
CAknPasswordSettingItem
CAknPasswordSettingPage
CAknPopupSettingPage
CAknRadioButtonSettingPage
CAknSettingItem
CAknSettingItemList
CAknSettingPage
CAknSliderSettingItem
CAknSliderSettingPage
CAknTextSettingItem
CAknTimeOffsetSettingItem
CAknTimeOffsetSettingPage
CAknTimeOrDateSettingItem
CAknTimeSettingPage
CAknVolumeSettingItem
CAknVolumeSettingPage

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

                  }

Setting item list resource structure


`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


`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


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

Related APIs

AVKON_SETTING_ITEM
AVKON_SETTING_ITEM_LIST
AVKON_SETTING_PAGE
CAknSettingItemList
CAknSettingItemList::ConstructFromResourceL
CMySettingList
ConstructL
CreateSettingItemL
EAknSettingItemIncludeHiddenInOrdinal
EAknSettingItemNumberedStyle
EAknSettingPageNoOrdinalDisplayed
Flags
Items
Label
Name
R_AVKON_MENUPANE_EMPTY
R_AVKON_SOFTKEYS_OK_CANCEL
Title
Type
aIdentifier
associated_resource
compulsory_ind_string
editor_resource_id
hint_text
iFlag
identifier
initial_number
number
setting_page_resource

Creating and using different setting items

There are different setting items available on the Symbian 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 .

Message reception

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;
               

                   }

Related APIs

CAknBinaryPopupSettingItem
CreateSettingItemL
TBool

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 .

Text setting item

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.

Related APIs

CAknTextSettingItem
CreateSettingItemL

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 .

Enumerated text setting item

Enumerated text setting item and enumerated text setting page

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;

Related APIs

CAknEnumeratedTextPopupSettingItem
CreateSettingItemL
EAknPopupSettingListFlagAllowsUserDefinedEntry
POPUP_SETTING_LIST
SetAllowsUserDefinedEntry

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 .

Alphanumeric password setting item

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;

Related APIs

CAknPasswordSettingItem
CreateSettingItemL

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 .

Numeric password setting item

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;

Related APIs

CAknPasswordSettingItem
CreateSettingItemL

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 .

Slider setting item

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;

Related APIs

CAknSliderSettingItem
CreateSettingItemL
TInt

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 .

Volume setting item

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;

Related APIs

CAknVolumeSettingItem
CreateSettingItemL

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.

Time setting item

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;

Related APIs

CAknTimeOrDateSettingItem
CreateSettingItemL
TTime

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 .

Time offset setting item

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;

Related APIs

CAknTimeOffsetSettingItem
CreateSettingItemL
TTimeIntervalSeconds

Date setting item

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

Date setting item

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;

Related APIs

CreateSettingItemL

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.

IP address setting item

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;

Related APIs

CAknIpFieldSettingItem
CreateSettingItemL
TInetAddr

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;
               

                       }
               

                   }

Related APIs

EditItemL

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.

Related APIs

EAknSettingItemIncludeHiddenInOrdinal
SetHidden

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.

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

                           },
               

                           …

Related APIs

AVKON_SETTING_ITEM
SetCompulsoryIndTextL
compulsory_ind_string

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

                      }
              

                  }

Related APIs

CAknSettingItem
EAknSetListBox

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.
              

                  }

Related APIs

CAknSettingItemList
CAknTextSettingItem
CMySettingItem
LoadL
LoadSettingsL
StoreL
StoreSettingsL

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.

Related APIs

EditItemL

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!

Related APIs

MAknSettingPageObserver

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

                      }
              

                  }

Related APIs

CAknSettingItemList
HandleResourceChangeL
SizeChanged()

Error handling

Setting Pages API uses standard Symbian platform 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.

Glossary

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

Setting Pages API Specification

Contents

Purpose

Constraints

Classification and release information

API description

Use cases

API class structure

Using Setting Pages API

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

Error handling

Memory overhead

Limitations of the API

Glossary

Abbreviations