diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F149726A-CC79-42A1-8A25-E15AC14ABE9A.dita --- a/Symbian3/SDK/Source/GUID-F149726A-CC79-42A1-8A25-E15AC14ABE9A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F149726A-CC79-42A1-8A25-E15AC14ABE9A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,205 +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:

- -

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.

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