1 <?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|
2 <html lang="en" xml:lang="en"> |
|
3 <head> |
|
4 <meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> |
|
5 <meta name="copyright" content="(C) Copyright 2005" /> |
|
6 <meta name="DC.rights.owner" content="(C) Copyright 2005" /> |
|
7 <meta content="concept" name="DC.Type" /> |
|
8 <meta name="DC.Title" content="Using selection controls" /> |
|
9 <meta scheme="URI" name="DC.Relation" content="WRTKit_Common_WRTKit_tasks-GUID-24870895-4449-4307-9a54-7c90f7b3905e.html" /> |
|
10 <meta content="XHTML" name="DC.Format" /> |
|
11 <meta content="GUID-5E36D276-CCE8-4BC9-BCBA-78E721ADB8C6" name="DC.Identifier" /> |
|
12 <meta content="en" name="DC.Language" /> |
|
13 <link href="commonltr.css" type="text/css" rel="stylesheet" /> |
|
14 <title> |
|
15 Using selection controls</title> |
|
16 </head> |
|
17 <body id="GUID-5E36D276-CCE8-4BC9-BCBA-78E721ADB8C6"><a name="GUID-5E36D276-CCE8-4BC9-BCBA-78E721ADB8C6"><!-- --></a> |
|
18 |
|
19 |
|
20 |
|
21 <h1 class="topictitle1"> |
|
22 Using selection controls</h1> |
|
23 |
|
24 <div> |
|
25 |
|
26 <p> |
|
27 |
|
28 Selection controls are used to let users make selections among a set |
|
29 of options. The WRTKit has two controls: SelectionList and |
|
30 SelectionMenu that have an identical API but differ in look and |
|
31 feel. The SelectionList shows all the options and selections |
|
32 directly in the view while the SelectionMenu only shows the selected |
|
33 options and opens up a menu with the options when the user activates |
|
34 the control. Selection controls can either be in single or multiple |
|
35 selection mode. In single selection mode only one of the options can |
|
36 be selected at a time while in multiple selection mode any number |
|
37 (including zero) can be selected. |
|
38 </p> |
|
39 |
|
40 <div class="fignone" id="GUID-5E36D276-CCE8-4BC9-BCBA-78E721ADB8C6__GUID-9F9B7E8B-2E27-4D95-AFBD-246DD16580B2"><a name="GUID-5E36D276-CCE8-4BC9-BCBA-78E721ADB8C6__GUID-9F9B7E8B-2E27-4D95-AFBD-246DD16580B2"><!-- --></a><span class="figcap">Figure 1. |
|
41 SelectionList controls</span> |
|
42 |
|
43 |
|
44 <br /><img src="SelectionList_Controls_Screenshot_1.png" /><br /> |
|
45 </div> |
|
46 |
|
47 <p> |
|
48 |
|
49 The SelectionList control is recommended to be used with the pointer |
|
50 navigation mode or if there are few options to choose from. The |
|
51 SelectionMenu control is recommended for large numbers of options or in |
|
52 the tab navigation mode. |
|
53 </p> |
|
54 |
|
55 <div class="fignone" id="GUID-5E36D276-CCE8-4BC9-BCBA-78E721ADB8C6__GUID-B3A04D05-2DA2-48B1-B37F-F0803B499DCC"><a name="GUID-5E36D276-CCE8-4BC9-BCBA-78E721ADB8C6__GUID-B3A04D05-2DA2-48B1-B37F-F0803B499DCC"><!-- --></a><span class="figcap">Figure 2. |
|
56 SelectionMenu control</span> |
|
57 |
|
58 |
|
59 <br /><img src="SelectionMenu_Control_Screenshot_1.png" /><br /> |
|
60 </div> |
|
61 |
|
62 <p> |
|
63 |
|
64 The options of a selection control are defined as an array of option |
|
65 objects, each with two properties: value and text. The value |
|
66 property can be any JavaScript value and represent the concrete |
|
67 value of the option, while the text property is a string that is |
|
68 shown in the user interface for the option. |
|
69 </p> |
|
70 |
|
71 <p> |
|
72 |
|
73 Option arrays can conveniently be created using JavaScript object |
|
74 notation (JSON) for example as follows: |
|
75 </p> |
|
76 |
|
77 <pre> |
|
78 |
|
79 // create an array with three options |
|
80 var options = [ |
|
81 { value: 1, text: "Coffee" }, |
|
82 { value: 2, text: "Tea" }, |
|
83 { value: 3, text: "Water" } |
|
84 ]; |
|
85 </pre> |
|
86 |
|
87 <p> |
|
88 |
|
89 The selected options are defined differently depending on whether |
|
90 the selection control is in single or multiple selection mode. In |
|
91 single selection mode the selected option is defined as a reference |
|
92 to the option in the control that should be selected. In multiple |
|
93 selection mode the selected options set is defined as an array of |
|
94 references to options in the control. Note that the references must |
|
95 be to one of the options objects defined for the control. It is not |
|
96 sufficient to define new option objects that happen to be identical |
|
97 to the ones in the control. |
|
98 </p> |
|
99 |
|
100 <pre> |
|
101 |
|
102 // create a set of two selected options for multiple selection control |
|
103 var selectedOptions = [ options[1], options[2] ]; |
|
104 </pre> |
|
105 |
|
106 <p> |
|
107 |
|
108 Note that the selectedOptions array is constructed so that the two |
|
109 elements in the array refer to the "Tea" and "Water" options in the |
|
110 options array. |
|
111 </p> |
|
112 |
|
113 <p> |
|
114 |
|
115 The code below creates a SelectionList control in multiple selection |
|
116 mode and initializes it with the options and selectedOptions arrays |
|
117 created above. The code assumes that a view has already been created |
|
118 and that a variable called exampleView refers to it. |
|
119 </p> |
|
120 |
|
121 <pre> |
|
122 |
|
123 // create selection list control |
|
124 var drinkList = new SelectionList("selection1", "Favorite drinks", |
|
125 options, true, selectedOptions); |
|
126 exampleView.addControl(drinkList); |
|
127 </pre> |
|
128 |
|
129 <p> |
|
130 |
|
131 "selection1" is a unique identifier for the control, "Favorite |
|
132 drinks" is the control caption, the option argument refers to the |
|
133 options array that we previously created, the following argument |
|
134 determines whether the control is in multiple selection mode, and |
|
135 finally the selectedOptions argument refers to the array with |
|
136 selected options and defines which of the options in the control |
|
137 should be selected by default. |
|
138 </p> |
|
139 |
|
140 <p> |
|
141 |
|
142 All of the arguments are optional and can be specified later as |
|
143 needed. For example if the options are not known when the control |
|
144 is created, or if the options change, they can be set using the |
|
145 setOptions() method. In the same way the selected options can be |
|
146 set using the setSelected() method. |
|
147 </p> |
|
148 |
|
149 <pre> |
|
150 |
|
151 // set options |
|
152 drinkList.setOptions(options); |
|
153 |
|
154 // set selected options |
|
155 drinkList.setSelected(selectedOptions); |
|
156 </pre> |
|
157 |
|
158 <p> |
|
159 |
|
160 The currently selected options can be retrieved using the |
|
161 getSelected() method. As mentioned earlier, in single selection mode |
|
162 the selected is just a single reference to an option (or null if no |
|
163 option is selected), while in multiple selection mode it's an array |
|
164 with references to the selected options. If no options are selected |
|
165 in multiple selection mode then the array is empty. |
|
166 </p> |
|
167 |
|
168 <pre> |
|
169 |
|
170 // find out which options are currently selected |
|
171 var selected = drinkList.getSelected(); |
|
172 </pre> |
|
173 |
|
174 <p> |
|
175 |
|
176 Selection controls fire "SelectionChanged" events when a user changes |
|
177 the selection of options in a control. These events can be handled |
|
178 using by registering an event listener to the control. The code below |
|
179 shows what a typical callback function would look like: |
|
180 </p> |
|
181 |
|
182 <pre> |
|
183 |
|
184 // Callback function for selection change events. |
|
185 function favoriteDrinkChanged(event) { |
|
186 // implement what happens when the selection changed here |
|
187 } |
|
188 </pre> |
|
189 |
|
190 <p> |
|
191 |
|
192 Registering the event listener function is done as follows, for |
|
193 example right after the control was created: |
|
194 </p> |
|
195 |
|
196 <pre> |
|
197 |
|
198 // register event listener |
|
199 drinkList.addEventListener("SelectionChanged", favoriteDrinkChanged); |
|
200 </pre> |
|
201 |
|
202 </div> |
|
203 |
|
204 <div> |
|
205 <div class="familylinks"> |
|
206 <div class="parentlink"><strong>Parent topic:</strong> <a href="WRTKit_Common_WRTKit_tasks-GUID-24870895-4449-4307-9a54-7c90f7b3905e.html">Common WRTKit tasks</a></div> |
|
207 </div> |
|
208 </div> |
|
209 |
|
210 </body> |
|
211 </html> |
|