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
.
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
.
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
.
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
.
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
.
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
.
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
.
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.
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
.
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.
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
IP address setting item
The IP address setting item allows users to manipulate IP address settings.
The variable type associated with this setting item is
TInetAddr
.
The setting item class used with the IP address type is
CAknIpFieldSettingItem
.
Note that IPv6 is not supported by the class.
Here is an example of an IP address setting item resource definition:
RESOURCE AVKON_SETTING_ITEM_LIST r_setting_list_setting_ip
{
flags = EAknSettingItemNumberedStyle;
title = "Setting list";
initial_number = 1;
items =
{
AVKON_SETTING_ITEM
{
identifier = EMySettingItemIpAddress;
setting_page_resource = r_ip_address_setting_page;
name = "Server address";
}
};
}
RESOURCE AVKON_SETTING_PAGE r_ip_address_setting_page
{
label = "Enter server address";
type = EAknCtIpFieldEditor;
editor_resource_id = r_settinglist_ip_editor;
}
RESOURCE IP_FIELD_EDITOR r_settinglist_ip_editor
{
min_field_values = IP_FIELD
{
first_field = 0;
second_field = 0;
third_field = 0;
fourth_field = 0;
};
max_field_values = IP_FIELD
{
first_field = 128; // Something different than 255
second_field = 255;
third_field = 255;
fourth_field = 255;
};
flags = 0;
}
The corresponding
CreateSettingItemL
must construct the
item:
…
case EMySettingItemIpAddress:
settingItem = new (ELeave) CAknIpFieldSettingItem
(aIdentifier, iIpAddress);
// iIpAddress has the type TInetAddr
break;
Related APIs
CAknIpFieldSettingItem
CreateSettingItemL
TInetAddr