1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7 	Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->  <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"><concept id="GUID-F149726A-CC79-42A1-8A25-E15AC14ABE9A" xml:lang="en"><title>Setting

    10 list</title><prolog><metadata><keywords></keywords></metadata></prolog><conbody>

    11 <p>A setting list is a specific kind of selection list containing setting

    12 items that the user can adjust. Setting lists are displayed in the main pane.</p>

    13 <fig id="GUID-5795DABA-71C7-42DE-B3AF-BA532435416A">

    14 <title>Setting list </title>

    15 <image href="GUID-D36660AA-1DC1-49B4-870E-F3BA66A734BC_d0e55427_href.png" scale="33" placement="inline"></image>

    16 </fig>

    17 <p>A setting item can be adjusted by selecting it in the same way as selection

    18 list items are selected in general; that is, by pressing the Selection key,

    19 or choosing the Change command from the Options menu. The main pane then displays

    20 the setting item editor where the value can be changed.</p>

    21 <p>There are several setting item types available. They look the same in the

    22 setting list: each item displays an attribute text (the title of the setting)

    23 on one line and the current value on another line within the item. The adjusting

    24 and editing functions differ between the setting item types.</p>

    25 <table id="GUID-212B8C90-F3AC-4893-9AF6-19A8B4845F91"><title>Setting item

    26 types</title>

    27 <tgroup cols="2"><colspec colname="col1"></colspec><colspec colname="col2"></colspec>

    28 <thead>

    29 <row>

    30 <entry>Setting</entry>

    31 <entry>Description</entry>

    32 </row>

    33 </thead>

    34 <tbody>

    35 <row>

    36 <entry><p>Pop-up setting</p></entry>

    37 <entry><p>A pop-up setting allows the user to choose one value from a pre-defined

    38 list. The setting editor displays the available values in a menu list.A pop-up

    39 setting may also allow the user to enter a new textual value in addition to

    40 the pre-defined values. In that case, the last option is named Other (or equivalent),

    41 and selecting it opens a Data query for entering the new value.</p></entry>

    42 </row>

    43 <row>

    44 <entry><p>Multi-selection list setting</p></entry>

    45 <entry><p>A multi-selection list setting allows the user to choose several

    46 simultaneous values from a pre-defined list. The setting editor displays the

    47 available values as a multi-selection list. The setting item displays the

    48 number of selected items versus all the items in the value field; for example:

    49 3/8.</p></entry>

    50 </row>

    51 <row>

    52 <entry><p>Text setting</p></entry>

    53 <entry><p>The value of a text setting item is an alphanumeric or numeric string.

    54 The editor can be of a specific type, such as the Date and Time editor.</p></entry>

    55 </row>

    56 <row>

    57 <entry><p>Slider setting</p></entry>

    58 <entry><p>With a slider, the user can adjust the value of a setting by sliding

    59 a marker. The value of a slider is adjusted using the Arrow left and Arrow

    60 right keys.</p></entry>

    61 </row>

    62 </tbody>

    63 </tgroup>

    64 </table>

    65 <fig id="GUID-D919C463-A143-4C05-AD2E-0983291F4658">

    66 <title>Pop-up setting</title>

    67 <image href="GUID-A0FF8339-E322-4D22-A800-E90467E5C952_d0e55510_href.png" scale="33" placement="inline"></image>

    68 </fig>

    69 <fig id="GUID-DB28DFCD-006C-4828-BDAC-CC9594AE4768">

    70 <title>Multi-selection setting</title>

    71 <image href="GUID-7E69FAA4-2198-4428-BD26-96C4020E2077_d0e55518_href.png" scale="33" placement="inline"></image>

    72 </fig>

    73 <fig id="GUID-B3D4C80C-7BD8-441F-AEB6-B186022E6A0A">

    74 <title>Text setting</title>

    75 <image href="GUID-AA9552C9-6223-459C-A8F9-770ECFCEFBDD_d0e55526_href.png" scale="33" placement="inline"></image>

    76 </fig>

    77 <fig id="GUID-4A642EAD-6C40-407A-A1C1-408B9331A1DA">

    78 <title>Slider setting</title>

    79 <image href="GUID-967E277E-67FC-4F98-B775-06C9BFC09926_d0e55534_href.png" scale="33" placement="inline"></image>

    80 </fig>

    81 <p>By default, in a setting editor, the keypad functions are as follows:</p>

    82 <table id="GUID-1181AD52-5BAD-4F44-A0A1-EA930F63E1AC"><title>Default key events

    83 in setting editor</title>

    84 <tgroup cols="2"><colspec colname="col1"></colspec><colspec colname="col2"></colspec>

    85 <thead>

    86 <row>

    87 <entry>Key</entry>

    88 <entry>Action</entry>

    89 </row>

    90 </thead>

    91 <tbody>

    92 <row>

    93 <entry><p>Arrow up / down</p></entry>

    94 <entry><p>Pop-up, multi-selection: browses the list. Text: moves the cursor.

    95 Slider: ignored.</p></entry>

    96 </row>

    97 <row>

    98 <entry><p>Arrow left / right</p></entry>

    99 <entry><p>Pop-up: ignored. Multi-selection: ignored. Text: moves the cursor.

   100 Slider: adjusts the slider value (a key repeat event may move the slider by

   101 several steps).</p></entry>

   102 </row>

   103 <row>

   104 <entry><p>Selection key</p></entry>

   105 <entry><p>All except multi-selection: accepts the value, returns to the setting

   106 list. Multi-selection: toggles <b>Mark/Unmark</b>.</p></entry>

   107 </row>

   108 <row>

   109 <entry><p>Left softkey (OK)</p></entry>

   110 <entry><p>Accepts the current item or value, returns.</p><p><b>Note: </b>may

   111 also be <b>Options</b> in certain instances.</p></entry>

   112 </row>

   113 <row>

   114 <entry><p>Right softkey (Cancel)</p></entry>

   115 <entry><p>Cancels the setting editor, returns.</p></entry>

   116 </row>

   117 <row>

   118 <entry><p>Clear</p></entry>

   119 <entry><p>Pop-up, multi-selection: ignored. Text: deletes characters. Slider:

   120 ignored.</p></entry>

   121 </row>

   122 <row>

   123 <entry><p>Edit</p></entry>

   124 <entry><p>Pop-up, multi-selection: ignored. Text: opens the editing menu.

   125 Slider: ignored.</p></entry>

   126 </row>

   127 <row>

   128 <entry><p>Numeric keypad</p></entry>

   129 <entry><p>Pop-up, multi-selection: ignored. Text: input functions. Slider:

   130 ignored; if the value is numeric, it may be adjustable using the Numeric keys.</p></entry>

   131 </row>

   132 <row>

   133 <entry><p>Other keys</p></entry>

   134 <entry><p>Do the default action of the key.</p></entry>

   135 </row>

   136 </tbody>

   137 </tgroup>

   138 </table>

   139 <p>In the setting editor, the Navi pane is empty, or in case of a text editor,

   140 contains the editing indicators.</p>

   141 <p>Further guidelines:</p>

   142 <ul>

   143 <li><p>Typically, a setting list is accessed via the <b>Options</b> menu (see <xref href="GUID-BFEEECCA-190B-4DDE-8A04-4FE918BE8690.dita">Options menu</xref>). </p></li>

   144 <li><p>Setting lists can only contain setting items, not other types of items

   145 mixed with them. (In case the settings are arranged in a hierarchical structure,

   146 both setting items and setting folders may exist in one list.)</p></li>

   147 <li><p>All the setting item types can co-exist in the same setting list.</p></li>

   148 </ul>

   149 <p>If a pop-up setting has only two available values (such as <b>On</b> and <b>Off</b>)

   150 and no special procedure is needed when switching from one value to the other,

   151 then the setting editor (list) must not be displayed when the user presses

   152 the Selection key; the item's value is changed immediately. However, if the

   153 user opens the setting item via the <b>Options</b> menu, or if an additional

   154 procedure is required (for example a password) before the item's value can

   155 be changed, the list is opened normally.</p>

   156 <section><title>Using setting lists in

   157 C++ applications</title><p>The APIs to use for setting lists are the Lists

   158 API and the Setting

   159 pages API. For implementation information, see Using

   160 the Lists API and Using

   161 the Setting pages API.</p></section>

   162 </conbody></concept>