Using Settings Lists

This section guides you through the SettingsList example application, which illustrates various types of settings list items. This example demonstrates the basic techniques for producing a settings list, including defining the list and settings list items in resource, creating a settings list subclass and constructing the list. It also covers the method used to change the value of a settings list item and also how to retrieve the values set by the user .

Settings List Basics

SettingsList displays the settings list for a game, as shown in Figure 7-27. The list contains three items: a slider to set the difficulty level, a player name editor, and a binary switch to enable or disable game hints. The items are numbered, and player name is marked as compulsory. Figure 7-28 shows the settings page screen for the difficulty level.

Figure 7-27. SettingsList screen.

Figure 7-28. SettingsList settings page screen.

Defining a Settings List Using Resources

Settings lists are defined in a resource file using an AVKON_SETTING_ITEM_LIST resource structure. The resource structure defined in SettingsList.rss from the SettingsList example is shown here:

 RESOURCE AVKON_SETTING_ITEM_LIST r_settingslist_setting_item_list    {    flags = EAknSettingItemNumberedStyle;    title = SETTING_ITEM_LIST_TITLE;    items =       {       AVKON_SETTING_ITEM          {          identifier = ESettingsListDifficultySettingItem;          setting_page_resource = r_settingslist_difficulty_setting_page;          name = DIFFICULTY_SETTING_ITEM_TITLE;          },       AVKON_SETTING_ITEM          {          identifier = ESettingsListPlayerNameSettingItem;          setting_page_resource = r_settingslist_player_name_setting_page;          name = PLAYER_NAME_SETTING_ITEM_TITLE;          compulsory_ind_string = "*";          },       AVKON_SETTING_ITEM          {          identifier = ESettingsListHintsSettingItem;          setting_page_resource = r_settingslist_hints_setting_page;          associated_resource = r_settingslist_hints_popup_setting_texts;          name = HINTS_SETTING_ITEM_TITLE;          }       };    } 

The AVKON_SETTING_ITEM_LIST structure has a number of fields, summarized here:

• flags ” This allows you to specify if the list is numbered using EAknSettingItemNumberedStyle , as in the SettingsList example. If it is numbered, you can add " EAknSettingItemIncludeHiddenInOrdinal" to this value to specify that hidden items are numbered.

• title ” This is a string, displayed at the top of the list.

• items ” This refers to an array of AVKON_SETTING_ITEM resources.

The default starting point for the sequence of numbers is one. To change this, you can override a default field ( initial_number ) in the AVKON_SETTING_ITEM_LIST and set it to a value of your choice.

Each settings item ( AVKON_SETTING_ITEM ) must have the following fields:

• identifier ” This uniquely identifies the settings item in code. You define identifiers in an enum in the .HRh file.

• setting_page_resource ” This refers to an AVKON_SETTING_PAGE resource.

In the SettingsList example, optional fields are defined in the settings items:

• name ” The title for the item, displayed above its value.

• compulsory_ind_string ” Marks a field as compulsory with the specified string.

• associated_resource ” Links to another control used by the settings page. In the SettingsList example, the "hints" settings item uses a pop-up list to switch hints on or off. In this case, the settings item refers to an AVKON_POPUP_SETTING_TEXTS resource, which the list uses for strings to display in both its pop-up and normal state.

A binary switch can have only two enumerated text items for its pop-up settings texts . One should have a value of zero and the other a value of one. Any deviation from this will cause a panic on construction.

 RESOURCE AVKON_SETTING_PAGE r_settingslist_difficulty_setting_page    {    number = 1;    hint_text = DIFFICULTY_HINT_TEXT;    label = DIFFICULTY_SETTING_ITEM_TITLE;    type = EAknCtSlider;    editor_resource_id = r_settingslist_difficulty_slider;    } 

As a minimum, a settings page resource needs a type and an editor_resource_id . The type specifies the type of control used to edit the item, in this case a slider control. The editor_resource_id refers to the resource definition for the SLIDER control.

Some optional fields are defined in the SettingsList example. The number is displayed in the top left corner of the settings page, if set to a value other than zero. This overrides any numbering on the settings item itself. The hint_text appears in the navigation pane, if set. The label is the title for the item, which appears above its value.

The SLIDER resource is a standard control, well documented in the Series 60 SDK "Slider Control Example." Table 7-9 provides brief details, but you are advised to consult the SDK documentation if you require in-depth information.

Deriving a Settings List

You will need to create a subclass of CAknSettingItemList and override some of its methods . In the SettingsList example, this role is performed by CSettingsListSettingItemList . It is usual to pass in data for the list to modify ”this is performed in the SettingsList example by the class TSettingsListSettings .

Note that TSettingsListSettings has public accessor methods which obtain references to private data. This is not normally advisable, as it breaks encapsulation. However, in this case the list's settings items require non-const references to manipulate. Data is passed by reference into the first-phase constructor, which then stores it.

 CSettingsListSettingItemList(TSettingsListSettings& aSettings) : iSettings(aSettings)    {    } 

Creating the Settings Items

Although you define the settings items in resource, you need to construct them dynamically in your code; otherwise they will not display. You do this in the CreateSettingItemL() method, which you override in the list subclass.

[View full width]

 
 [View full width] 
 CAknSettingItem* CSettingsListSettingItemList::CreateSettingItemL(TInt aIdentifier)    {    CAknSettingItem* settingItem = NULL;    switch (aIdentifier)       {       case ESettingsListDifficultySettingItem:          settingItem = new (ELeave) CAknSliderSettingItem(aIdentifier, iDifficultyLevel);          break;       case ESettingsListPlayerNameSettingItem:          settingItem = new (ELeave) CAknTextSettingItem(aIdentifier, iPlayerName);          break;       case ESettingsListHintsSettingItem:          settingItem = new (ELeave) CAknBinaryPopupSettingItem(aIdentifier, iSettings  .HintsEnabled());          break;       }    return settingItem; // passing ownership    } 

The base class calls the method for each item defined in resource, passing in the identifier for the item ( aIdentifier ). You then construct the appropriate type of settings item for the identifier, passing in a piece of data for it to alter. The base class owns the settings items and holds them in an array. You can access this using the SettingItemArray() method.

Note that the base class calls CreateSettingItemL() when the settings list is constructed . If the application fails when it first shows the list, it is likely that there is a problem with this method. For example, a panic would occur if iDifficulty were out of range for the slider.

Changing Settings List Values

Whenever you select an item using the Selection key, the base class calls the EditItemL() method.

 void CSettingsListSettingItemList::EditItemL(TInt aIndex, TBool aCalledFromMenu)    {    CAknSettingItemList::EditItemL(aIndex, aCalledFromMenu);    (*SettingItemArray())[aIndex]->StoreL();    } 

You should first call the base-class version of EditItemL() , as this allows you to edit the item either via the settings page or in-place. Which method is used depends on the value of aCalledFromMenu . If it is set to EFalse , editing is in place, otherwise it is edited via the settings page. The framework calls EditItemL() whenever you select an item. It sets aCalledFromMenu to EFalse for all components apart from the binary switch, which it sets to Etrue .

You should add a Change item to the Options menu to allow editing. This should call the EditItemL() method. It is common to have the binary switch open the settings page when called from the menu, but edit in-place when the Selection key is pressed. To do this, just have EditItemL() called with a value of Etrue for all controls.

When you change settings item values, they do not automatically update the data items supplied to them on construction. Settings items have a method StoreL() that writes the value in the control to the data. In the SettingsList example, the EditItemL() method is overridden to provide a convenient location for this storage to occur. The settings items are stored in an array in the base class, which can be accessed using the SettingItemArray() method. The appropriate item is selected from the array and its StoreL() method called to store the value that has just been edited.

The settings list provides another method for storing items: StoreSettingsL() . This calls StoreL() on each of the settings items in the list. You could use this method to store items when you remove the list from the display, instead of storing each item individually after editing.

Constructing a Settings List

You will need to construct your list using the resource defined for it. This can be performed in the container's ConstructL() method using standard two-phase construction from resource.

 iSettingItemList = new CSettingsListSettingItemList(iSettings); iSettingItemList->SetMopParent(this); iSettingItemList->ConstructFromResourceL(R_SETTINGSLIST_SETTING_ITEM_LIST); 

Settings Item Types

Tables 7-9 through 7-16 are provided to assist you in adding items to your settings lists. Each table describes a particular settings item, illustrated with an example screen shot, giving sample resource definitions and sample code for creating the item.

Table 7-9. Slider Settings Item Reference

Type	Slider
Setting Item Screen Shot
Setting Page Screen Shot
Example Resource	AVKON_SETTING_ITEM { identifier = EMySliderSettingItem; setting_page_resource = r_my_slider_setting_page; } RESOURCE AVKON_SETTING_PAGE r_my_slider_setting_page { type = EAknCtSlider; editor_resource_id = r_my_slider; } RESOURCE SLIDER r_my_slider { layout = EAknSettingsItemSliderLayout; minvalue = 0; maxvalue = 2; step = 1; valuetype = EAknSliderValueBareFigure; minlabel = "Min"; maxlabel = "Max"; }
Setting Item Class	CAknSliderSettingItem
Example CreateSettingItemL()	TInt iSlider; CAknSettingItem* CMySettingItemList:: CreateSettingItemL(TInt aIdentifier) { return new CAknSliderSettingItem (aIdentifier, iSlider); }
Further Information	layout ” determines whether to show the header, current value and labels. minvalue and maxvalue ” determine the minimum and maximum values represented by the slider. step ” determines how much the slider increments by. valuetype ” determines how the value will be displayed (figure, percent, fraction or decimal). minlabel and maxlabel ” are the minimum and maximum labels. If you were to use a slider outside a settings list, you would use a CAknSlider control. Methods are available to alter the values and labels of the slider dynamically and to change the step size and minimum and maximum values. Further information can be found in the SDK documentation.

Table 7-10. Volume Setting Item Reference

Type	Volume
Setting Item Screen Shot
Setting Page Screen Shot
Example Resource	AVKON_SETTING_ITEM { identifier = EMyVolumeSettingItem; setting_page_resource = r_my_volume_setting_page; } RESOURCE AVKON_SETTING_PAGE r_my_volume_setting_page { type = EAknCtVolumeControl; editor_resource_id = r_my_volume; } RESOURCE VOLUME r_my_volume { flags = ESettingsVolumeControl; value = 1; }
Setting Item Class	CAknVolumeSettingItem
Example CreateSettingItemL()	[View full width] TInt iVolume; CAknSettingItem* CMySettingItemList:: CreateSetting ItemL(TInt aIdentifier) { return new CAknVolumeSettingItem(aIdentifier, iVolume); }
Further Information	The header file for the CAknVolumeSettings class indicates that the volume can be in the range 0 to 10. It can actually be in the range 1 to 10 ”a panic occurs if you set it to zero!

Table 7-11. Text Editor Setting Item Reference

Type	Text Editor
Setting Item Screen Shot
Setting Page Screen Shot
Example Resource	[View full width] AVKON_SETTING_ITEM { identifier = EMyTextEditorSettingItem; setting_page_resource = r_my_text_editor_setting_page; } RESOURCE AVKON_SETTING_PAGE r_my_text_editor_setting_page { type = EEikCtEdwin; editor_resource_id = r_my_text_editor; }
Setting Item Class	CAknTextSettingItem
Example CreateSettingItemL()	TBuf<10> iText; CAknSettingItem* CMySettingItemList:: CreateSettingItemL(TInt aIdentifier) { return new CAknTextSettingItem(aIdentifier, iText); }
Further Information	When empty, the text editor displays a placeholder string. By default this is " None ", but it can be changed using CAknTextSettingItem::SetEmptyItemTextL() . The Ok soft key is not visible on the settings page screen, until the editor contains one character.

Table 7-12. Enumerated Text Setting Item Reference

Type	Enumerated Text
Setting Item Screen Shot
Setting Page Screen Shot
Example Resource	AVKON_SETTING_ITEM { identifier = EMyEnumeratedTextSettingItem; setting_page_resource = r_my_setting_page; associated_resource = r_my_popup_setting_texts; } RESOURCE AVKON_SETTING_PAGE r_my_setting_page { type = EAknCtPopupSettingList; editor_resource_id = r_my_popup_setting_list; }
Setting Item Class	CAknEnumeratedTextPopupSettingItem
Example CreateSettingItemL()	[View full width] TTime iEnumeration; CAknSettingItem* CMySettingItemList:: CreateSetting ItemL(TInt aIdentifier) { return new CAknEnumeratedTextPopupSettingItem (aIdentifier, iEnumeration); }

Table 7-13. Time or Date Editor Setting Item Reference

Type	Time or Date Editor
Setting Item Screen Shot
Setting Page Screen Shot
Example Resource	[View full width] AVKON_SETTING_ITEM { identifier = EMyTimeSettingItem; setting_page_resource = r_my_time_setting _page; } RESOURCE AVKON_SETTING_PAGE r_setlistex2_time_setting_page { type = EEikCtTimeEditor; editor_resource_id = r_my_time_editor; }
Setting Item Class	CAknTimeOrDateSettingItem
Example	[View full width] TTime iTime; CreateSettingItemL() CAknSettingItem* CMySettingItemList:: CreateSetting ItemL(TInt aIdentifier) { return new CAknTimeOrDateSettingItem (aIdentifier, CAknTimeOrDateSettingItem::ETime, iTime); }
Further Information	To make this a date, rather than time editor, change the second parameter in the CAknTimeOrDateSettingItem constructor to EDate , change the type in the settings page to EEikCtDateEditor , and set the resource's editor_resource_id to a DATE_EDITOR .

Table 7-14. IP Address Editor Setting Item Reference

Type	IP Address Editor
Setting Item Screen Shot
Setting Page Screen Shot
Example Resource	AVKON_SETTING_ITEM { identifier = EMyIpSettingItem; setting_page_resource = r_my_ip_setting_page; } RESOURCE AVKON_SETTING_PAGE = r_my_ip_setting_page { type = EAknCtIpFieldEditor; editor_resource_id = r_my_ip_field_editor; }
Setting Item Class	CAknIpFieldSettingItem
Example CreateSettingItemL()	TInetAddr iIp; CAknSettingItem* CMySettingItemList:: CreateSettingItemL(TInt aIdentifier) { return new CAknIpFieldSettingItem(aIdentifier, iIP); }

Table 7-15. Binary Switch Setting Item Reference

Type	Binary Switch
Setting Item Screen Shot
Setting Page Screen Shot
Example Resource	AVKON_SETTING_ITEM { identifier = EMyBinarySwitchSettingItem; setting_page_resource = r_my_setting_page; associated_resource = r_my_popup_setting_texts; } RESOURCE AVKON_SETTING_PAGE r_my_setting_page { type = EAknCtPopupSettingList; editor_resource_id = r_my_popup_setting_list; }
Setting Item Class	CAknBinaryPopupSettingItem
Example CreateSettingItemL()	[View full width] TBool iBinarySwitch CAknSettingItem* CMySettingItemList:: CreateSettingItemL() ItemL(TInt aIdentifier) { return new CAknBinaryPopupSettingItem (aIdentifier, iBinarySwitch); }
Further Information	There can be only two items in the associated_resource and editor_resource_id resource. See the SettingsList example for further details.

Table 7-16. Password Editor Setting Item Reference

Type	Password Editor
Setting Item Screen Shot
Setting Page Screen Shot
Example Resource	AVKON_SETTING_ITEM { identifier = EMyPasswordSettingItem; setting_page_resource = r_my_password_setting_page; } RESOURCE AVKON_SETTING_PAGE r_my_password_setting_page { type = EEikCtSecretEd; editor_resource_id = r_my_password_secreted; }
Setting Item Class	CAknPasswordSettingItem
Example CreateSettingItemL()	[View full width] TBuf <10> iPassword; CAknSettingItem* CMySettingItemList:: CreateSettingItemL(TInt aIdentifier) { return new CAknPasswordSettingItem(aIdentifier, CAknPasswordSettingItem::EAlpha, iPassword); }
Further Information	To make this a numeric password, or PIN, change the second parameter in the CAknPasswordSettingItem constructor to ENumeric .