|
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 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-F149726A-CC79-42A1-8A25-E15AC14ABE9A" xml:lang="en"><title>Setting |
|
13 list</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>A setting list is a specific kind of selection list containing setting |
|
15 items that the user can adjust. Setting lists are displayed in the main pane.</p> |
|
16 <fig id="GUID-0CDD9A63-4113-4662-BCBA-502FC7CA8FF4"> |
|
17 <title>Setting list </title> |
|
18 <image href="GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e62404_href.png" placement="inline"/> |
|
19 </fig> |
|
20 <p>A setting item can be adjusted by selecting it in the same way as selection |
|
21 list items are selected in general; that is, by pressing the Selection key, |
|
22 or choosing the Change command from the Options menu. The main pane then displays |
|
23 the setting item editor where the value can be changed.</p> |
|
24 <p>There are several setting item types available. They look the same in the |
|
25 setting list: each item displays an attribute text (the title of the setting) |
|
26 on one line and the current value on another line within the item. The adjusting |
|
27 and editing functions differ between the setting item types.</p> |
|
28 <table id="GUID-212B8C90-F3AC-4893-9AF6-19A8B4845F91"><title>Setting item |
|
29 types</title> |
|
30 <tgroup cols="2"><colspec colname="col1" colwidth="0.41*"/><colspec colname="col2" colwidth="1.59*"/> |
|
31 <thead> |
|
32 <row> |
|
33 <entry>Setting</entry> |
|
34 <entry>Description</entry> |
|
35 </row> |
|
36 </thead> |
|
37 <tbody> |
|
38 <row> |
|
39 <entry><p>Pop-up setting</p></entry> |
|
40 <entry><p>A pop-up setting allows the user to choose one value from a pre-defined |
|
41 list. The setting editor displays the available values in a menu list. A pop-up |
|
42 setting may also allow the user to enter a new textual value in addition to |
|
43 the pre-defined values. In that case, the last option is named Other (or equivalent), |
|
44 and selecting it opens a Data query for entering the new value.</p></entry> |
|
45 </row> |
|
46 <row> |
|
47 <entry><p>Multi-selection list setting</p></entry> |
|
48 <entry><p>A multi-selection list setting allows the user to choose several |
|
49 simultaneous values from a pre-defined list. The setting editor displays the |
|
50 available values as a multi-selection list. The setting item displays the |
|
51 number of selected items versus all the items in the value field; for example: |
|
52 3/8.</p></entry> |
|
53 </row> |
|
54 <row> |
|
55 <entry><p>Text setting</p></entry> |
|
56 <entry><p>The value of a text setting item is an alphanumeric or numeric string. |
|
57 The editor can be of a specific type, such as the Date and Time editor.</p></entry> |
|
58 </row> |
|
59 <row> |
|
60 <entry><p>Slider setting</p></entry> |
|
61 <entry><p>With a slider, the user can adjust the value of a setting by sliding |
|
62 a marker. The value of a slider is adjusted using the Arrow left and Arrow |
|
63 right keys.</p></entry> |
|
64 </row> |
|
65 </tbody> |
|
66 </tgroup> |
|
67 </table> |
|
68 <fig id="GUID-100ECC17-5370-437D-B356-070DC3F1E785"> |
|
69 <title>Pop-up setting</title> |
|
70 <image href="GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e62487_href.png" placement="inline"/> |
|
71 </fig> |
|
72 <fig id="GUID-FE7CEFF0-1929-46D5-906B-B65C4CC909BF"> |
|
73 <title>Multi-selection setting</title> |
|
74 <image href="GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e62495_href.png" placement="inline"/> |
|
75 </fig> |
|
76 <fig id="GUID-9391502B-9B3E-417C-98D4-9962B88E9C97"> |
|
77 <title>Text setting</title> |
|
78 <image href="GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e62503_href.png" placement="inline"/> |
|
79 </fig> |
|
80 <fig id="GUID-C8EFE352-7D5B-4199-B6C9-A9F9DEBFEF53"> |
|
81 <title>Slider setting</title> |
|
82 <image href="GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e62511_href.png" placement="inline"/> |
|
83 </fig> |
|
84 <p>By default, in a setting editor, the keypad functions are as follows:</p> |
|
85 <table id="GUID-1181AD52-5BAD-4F44-A0A1-EA930F63E1AC"><title>Default key events |
|
86 in setting editor</title> |
|
87 <tgroup cols="2"><colspec colname="col1" colwidth="0.32*"/><colspec colname="col2" colwidth="1.68*"/> |
|
88 <thead> |
|
89 <row> |
|
90 <entry>Key</entry> |
|
91 <entry>Action</entry> |
|
92 </row> |
|
93 </thead> |
|
94 <tbody> |
|
95 <row> |
|
96 <entry><p>Arrow up / down</p></entry> |
|
97 <entry><p>Pop-up, multi-selection: browses the list. Text: moves the cursor. |
|
98 Slider: ignored.</p></entry> |
|
99 </row> |
|
100 <row> |
|
101 <entry><p>Arrow left / right</p></entry> |
|
102 <entry><p>Pop-up: ignored. Multi-selection: ignored. Text: moves the cursor. |
|
103 Slider: adjusts the slider value (a key repeat event may move the slider by |
|
104 several steps).</p></entry> |
|
105 </row> |
|
106 <row> |
|
107 <entry><p>Selection key</p></entry> |
|
108 <entry><p>All except multi-selection: accepts the value, returns to the setting |
|
109 list. Multi-selection: toggles <b>Mark/Unmark</b>.</p></entry> |
|
110 </row> |
|
111 <row> |
|
112 <entry><p>Left softkey (OK)</p></entry> |
|
113 <entry><p>Accepts the current item or value, returns.</p><p><b>Note: </b>may |
|
114 also be <b>Options</b> in certain instances.</p></entry> |
|
115 </row> |
|
116 <row> |
|
117 <entry><p>Right softkey (Cancel)</p></entry> |
|
118 <entry><p>Cancels the setting editor, returns.</p></entry> |
|
119 </row> |
|
120 <row> |
|
121 <entry><p>Clear</p></entry> |
|
122 <entry><p>Pop-up, multi-selection: ignored. Text: deletes characters. Slider: |
|
123 ignored.</p></entry> |
|
124 </row> |
|
125 <row> |
|
126 <entry><p>Edit</p></entry> |
|
127 <entry><p>Pop-up, multi-selection: ignored. Text: opens the editing menu. |
|
128 Slider: ignored.</p></entry> |
|
129 </row> |
|
130 <row> |
|
131 <entry><p>Numeric keypad</p></entry> |
|
132 <entry><p>Pop-up, multi-selection: ignored. Text: input functions. Slider: |
|
133 ignored; if the value is numeric, it may be adjustable using the Numeric keys.</p></entry> |
|
134 </row> |
|
135 <row> |
|
136 <entry><p>Other keys</p></entry> |
|
137 <entry><p>Do the default action of the key.</p></entry> |
|
138 </row> |
|
139 </tbody> |
|
140 </tgroup> |
|
141 </table> |
|
142 <p/> |
|
143 <table id="GUID-02B3DF05-AF93-4E8C-A252-DCACBC02311C"><title>Default touch |
|
144 events to setting list</title> |
|
145 <tgroup cols="3"> |
|
146 |
|
147 <colspec colname="col1" colwidth="0.62*"/><colspec colname="col2" colwidth="1.09*"/> |
|
148 <colspec colname="col3" colwidth="1.28*"/> |
|
149 <thead> |
|
150 <row> |
|
151 <entry valign="top"><p>User action</p></entry> |
|
152 <entry valign="top"><p>State change</p></entry> |
|
153 <entry valign="top"><p>Feedback</p></entry> |
|
154 </row> |
|
155 </thead> |
|
156 <tbody> |
|
157 <row> |
|
158 <entry><p>Touch down</p></entry> |
|
159 <entry><p>No change</p></entry> |
|
160 <entry><p>Highlight is shown. </p><p>Tactile: Basic list effect and audio |
|
161 given with touch down event.</p></entry> |
|
162 </row> |
|
163 <row> |
|
164 <entry><p>Touch release</p></entry> |
|
165 <entry><p>The setting item is opened. Exception for only two values in a setting |
|
166 list. Refer to 19.2 Setting item with two available values.</p></entry> |
|
167 <entry><p>Highlight disappears. Tactile: Basic list effect given with touch |
|
168 release event.</p></entry> |
|
169 </row> |
|
170 <row> |
|
171 <entry><p>Touch down and hold</p></entry> |
|
172 <entry><p>Inactive</p></entry> |
|
173 <entry><p>Tactile: No effect</p></entry> |
|
174 </row> |
|
175 <row> |
|
176 <entry><p>Touch down and move</p></entry> |
|
177 <entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging |
|
178 and flicking</xref> events</p></entry> |
|
179 <entry><p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging |
|
180 and flicking</xref> events.</p></entry> |
|
181 </row> |
|
182 </tbody> |
|
183 </tgroup> |
|
184 </table> |
|
185 <p>In the setting editor, the Navi pane is empty, or in case of a text editor, |
|
186 contains the editing indicators.</p> |
|
187 <p>Further guidelines:</p> |
|
188 <ul> |
|
189 <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> |
|
190 <li><p>Setting lists can only contain setting items, not other types of items |
|
191 mixed with them. (In case the settings are arranged in a hierarchical structure, |
|
192 both setting items and setting folders may exist in one list.)</p></li> |
|
193 <li><p>All the setting item types can co-exist in the same setting list.</p></li> |
|
194 </ul> |
|
195 <p>If a pop-up setting has only two available values (such as <b>On</b> and <b>Off</b>) |
|
196 and no special procedure is needed when switching from one value to the other, |
|
197 then the setting editor (list) must not be displayed when the user presses |
|
198 the Selection key; the item's value is changed immediately. However, if the |
|
199 user opens the setting item via the <b>Options</b> menu, or if an additional |
|
200 procedure is required (for example a password) before the item's value can |
|
201 be changed, the list is opened normally.</p> |
|
202 <section id="GUID-EDDFFFA4-DFBC-4455-B6DD-D48ED995A3EF"><title>Using |
|
203 setting lists in C++ applications</title><p>The APIs to use for setting lists |
|
204 are the <xref format="html" href="specs/guides/Lists_API_Specification/Lists_API_Specification.html" scope="peer">Lists API</xref> and the <xref format="html" href="specs/guides/Setting_Pages_API_Specification/Setting_Pages_API_Specification.html" scope="peer">Setting pages API</xref>. For implementation information, see <xref format="htrml" href="specs/guides/Lists_API_Specification/Lists_API_Specification.html#Lists_API_Specification.topic3" scope="peer">Using the Lists API</xref> and <xref format="html" href="specs/guides/Setting_Pages_API_Specification/Setting_Pages_API_Specification.html#Setting_Pages_API_Specification.topic3" scope="peer">Using the Setting pages API</xref>.</p></section> |
|
205 </conbody></concept> |