Collapse all Symbian^3 Product Developer Library

Setting list

A setting list is a specific kind of selection list containing setting items that the user can adjust. Setting lists are displayed in the main pane.

Figure 1. Setting list

A setting item can be adjusted by selecting it in the same way as selection list items are selected in general; that is, by pressing the Selection key, or choosing the Change command from the Options menu. The main pane then displays the setting item editor where the value can be changed.

There are several setting item types available. They look the same in the setting list: each item displays an attribute text (the title of the setting) on one line and the current value on another line within the item. The adjusting and editing functions differ between the setting item types.

Table 1. Setting item types
Setting	Description
Pop-up setting	A pop-up setting allows the user to choose one value from a pre-defined list. The setting editor displays the available values in a menu list. A pop-up setting may also allow the user to enter a new textual value in addition to the pre-defined values. In that case, the last option is named Other (or equivalent), and selecting it opens a Data query for entering the new value.
Multi-selection list setting	A multi-selection list setting allows the user to choose several simultaneous values from a pre-defined list. The setting editor displays the available values as a multi-selection list. The setting item displays the number of selected items versus all the items in the value field; for example: 3/8.
Text setting	The value of a text setting item is an alphanumeric or numeric string. The editor can be of a specific type, such as the Date and Time editor.
Slider setting	With a slider, the user can adjust the value of a setting by sliding a marker. The value of a slider is adjusted using the Arrow left and Arrow right keys.

Figure 2. Pop-up setting

Figure 3. Multi-selection setting

Figure 4. Text setting

Figure 5. Slider setting

By default, in a setting editor, the keypad functions are as follows:

Table 2. Default key events in setting editor
Key	Action
Arrow up / down	Pop-up, multi-selection: browses the list. Text: moves the cursor. Slider: ignored.
Arrow left / right	Pop-up: ignored. Multi-selection: ignored. Text: moves the cursor. Slider: adjusts the slider value (a key repeat event may move the slider by several steps).
Selection key	All except multi-selection: accepts the value, returns to the setting list. Multi-selection: toggles Mark/Unmark.
Left softkey (OK)	Accepts the current item or value, returns. Note: may also be Options in certain instances.
Right softkey (Cancel)	Cancels the setting editor, returns.
Clear	Pop-up, multi-selection: ignored. Text: deletes characters. Slider: ignored.
Edit	Pop-up, multi-selection: ignored. Text: opens the editing menu. Slider: ignored.
Numeric keypad	Pop-up, multi-selection: ignored. Text: input functions. Slider: ignored; if the value is numeric, it may be adjustable using the Numeric keys.
Other keys	Do the default action of the key.

Table 3. Default touch events to setting list
User action	State change	Feedback
Touch down	No change	Highlight is shown. Tactile: Basic list effect and audio given with touch down event.
Touch release	The setting item is opened. Exception for only two values in a setting list. Refer to 19.2 Setting item with two available values.	Highlight disappears. Tactile: Basic list effect given with touch release event.
Touch down and hold	Inactive	Tactile: No effect
Touch down and move	Refer to Dragging and flicking events	Tactile: Refer to Dragging and flicking events.

In the setting editor, the Navi pane is empty, or in case of a text editor, contains the editing indicators.

Further guidelines:

Typically, a setting list is accessed via the Options menu (see Options menu).
Setting lists can only contain setting items, not other types of items mixed with them. (In case the settings are arranged in a hierarchical structure, both setting items and setting folders may exist in one list.)
All the setting item types can co-exist in the same setting list.

If a pop-up setting has only two available values (such as On and Off) and no special procedure is needed when switching from one value to the other, then the setting editor (list) must not be displayed when the user presses the Selection key; the item's value is changed immediately. However, if the user opens the setting item via the Options menu, or if an additional procedure is required (for example a password) before the item's value can be changed, the list is opened normally.

Using setting lists in applications

The APIs to use for setting lists are the Lists API and the Setting pages API. For implementation information, see Using the Lists API and Using the Setting pages API.

Parent topic: List types