org.symbian.wrttools.doc.WRTKit/html/WRTKit_Using_selection_controls-GUID-5e36d276-cce8-4bc9-bcba-78e721adb8c6.html
--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Using_selection_controls-GUID-5e36d276-cce8-4bc9-bcba-78e721adb8c6.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,211 +0,0 @@
-<?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">
-<html lang="en" xml:lang="en">
-<head>
-<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
-<meta name="copyright" content="(C) Copyright 2005" />
-<meta name="DC.rights.owner" content="(C) Copyright 2005" />
-<meta content="concept" name="DC.Type" />
-<meta name="DC.Title" content="Using selection controls" />
-<meta scheme="URI" name="DC.Relation" content="WRTKit_Common_WRTKit_tasks-GUID-24870895-4449-4307-9a54-7c90f7b3905e.html" />
-<meta content="XHTML" name="DC.Format" />
-<meta content="GUID-5E36D276-CCE8-4BC9-BCBA-78E721ADB8C6" name="DC.Identifier" />
-<meta content="en" name="DC.Language" />
-<link href="commonltr.css" type="text/css" rel="stylesheet" />
-<title>
-Using selection controls</title>
-</head>
-<body id="GUID-5E36D276-CCE8-4BC9-BCBA-78E721ADB8C6"><a name="GUID-5E36D276-CCE8-4BC9-BCBA-78E721ADB8C6"><!-- --></a>
-
-
-
- <h1 class="topictitle1">
-Using selection controls</h1>
-
- <div>
-
- <p>
-
- Selection controls are used to let users make selections among a set
- of options. The WRTKit has two controls: SelectionList and
- SelectionMenu that have an identical API but differ in look and
- feel. The SelectionList shows all the options and selections
- directly in the view while the SelectionMenu only shows the selected
- options and opens up a menu with the options when the user activates
- the control. Selection controls can either be in single or multiple
- selection mode. In single selection mode only one of the options can
- be selected at a time while in multiple selection mode any number
- (including zero) can be selected.
- </p>
-
- <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.
-SelectionList controls</span>
-
-
- <br /><img src="SelectionList_Controls_Screenshot_1.png" /><br />
- </div>
-
- <p>
-
- The SelectionList control is recommended to be used with the pointer
- navigation mode or if there are few options to choose from. The
- SelectionMenu control is recommended for large numbers of options or in
- the tab navigation mode.
- </p>
-
- <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.
-SelectionMenu control</span>
-
-
- <br /><img src="SelectionMenu_Control_Screenshot_1.png" /><br />
- </div>
-
- <p>
-
- The options of a selection control are defined as an array of option
- objects, each with two properties: value and text. The value
- property can be any JavaScript value and represent the concrete
- value of the option, while the text property is a string that is
- shown in the user interface for the option.
- </p>
-
- <p>
-
- Option arrays can conveniently be created using JavaScript object
- notation (JSON) for example as follows:
- </p>
-
-<pre>
-
-// create an array with three options
-var options = [
- { value: 1, text: "Coffee" },
- { value: 2, text: "Tea" },
- { value: 3, text: "Water" }
- ];
-</pre>
-
- <p>
-
- The selected options are defined differently depending on whether
- the selection control is in single or multiple selection mode. In
- single selection mode the selected option is defined as a reference
- to the option in the control that should be selected. In multiple
- selection mode the selected options set is defined as an array of
- references to options in the control. Note that the references must
- be to one of the options objects defined for the control. It is not
- sufficient to define new option objects that happen to be identical
- to the ones in the control.
- </p>
-
-<pre>
-
-// create a set of two selected options for multiple selection control
-var selectedOptions = [ options[1], options[2] ];
-</pre>
-
- <p>
-
- Note that the selectedOptions array is constructed so that the two
- elements in the array refer to the "Tea" and "Water" options in the
- options array.
- </p>
-
- <p>
-
- The code below creates a SelectionList control in multiple selection
- mode and initializes it with the options and selectedOptions arrays
- created above. The code assumes that a view has already been created
- and that a variable called exampleView refers to it.
- </p>
-
-<pre>
-
-// create selection list control
-var drinkList = new SelectionList("selection1", "Favorite drinks",
- options, true, selectedOptions);
-exampleView.addControl(drinkList);
-</pre>
-
- <p>
-
- "selection1" is a unique identifier for the control, "Favorite
- drinks" is the control caption, the option argument refers to the
- options array that we previously created, the following argument
- determines whether the control is in multiple selection mode, and
- finally the selectedOptions argument refers to the array with
- selected options and defines which of the options in the control
- should be selected by default.
- </p>
-
- <p>
-
- All of the arguments are optional and can be specified later as
- needed. For example if the options are not known when the control
- is created, or if the options change, they can be set using the
- setOptions() method. In the same way the selected options can be
- set using the setSelected() method.
- </p>
-
-<pre>
-
-// set options
-drinkList.setOptions(options);
-
-// set selected options
-drinkList.setSelected(selectedOptions);
-</pre>
-
- <p>
-
- The currently selected options can be retrieved using the
- getSelected() method. As mentioned earlier, in single selection mode
- the selected is just a single reference to an option (or null if no
- option is selected), while in multiple selection mode it's an array
- with references to the selected options. If no options are selected
- in multiple selection mode then the array is empty.
- </p>
-
-<pre>
-
-// find out which options are currently selected
-var selected = drinkList.getSelected();
-</pre>
-
- <p>
-
- Selection controls fire "SelectionChanged" events when a user changes
- the selection of options in a control. These events can be handled
- using by registering an event listener to the control. The code below
- shows what a typical callback function would look like:
- </p>
-
-<pre>
-
-// Callback function for selection change events.
-function favoriteDrinkChanged(event) {
- // implement what happens when the selection changed here
-}
-</pre>
-
- <p>
-
- Registering the event listener function is done as follows, for
- example right after the control was created:
- </p>
-
-<pre>
-
-// register event listener
-drinkList.addEventListener("SelectionChanged", favoriteDrinkChanged);
-</pre>
-
- </div>
-
-<div>
-<div class="familylinks">
-<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>
-</div>
-</div>
-
-</body>
-</html>
\ No newline at end of file