Setting +list

diff -r 43e37759235e -r 51a74ef9ed63 Symbian3/SDK/Source/GUID-F149726A-CC79-42A1-8A25-E15AC14ABE9A.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-F149726A-CC79-42A1-8A25-E15AC14ABE9A.dita Wed Mar 31 11:11:55 2010 +0100 @@ -0,0 +1,205 @@ + + + + + +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.

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

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

+ + + +

+ +Pop-up setting + + + +Multi-selection setting + + + +Text setting + + + +Slider setting + + +

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

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

+ + + +

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

+ \ No newline at end of file