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