+ + Selection of one or more options from a set of options is one of the most common + use cases in a user interface. The WRTKit supports this use case with two + controls, SelectionList and SelectionMenu, each of which can be in either + "single selection" or "multiple selection" mode. The two controls differe only + in look and interaction but not in their APIs. +
+ ++ + The SelectionList control shows an expanded list of all of its options in the + view. If the control is in single selection mode then each option is presented + with a "radio button", of which only one can be selected at a time. This ensures + that only one of the options can be selected by the user. If the SelectionList + control is in multiple selection mode then each option is presented with a + "checkbox". Any amount (including zero) of checkboxes can be checked at time, + allowing users to select multiple options. The SelectionList control is a hybrid + between the traditional way of showing radio buttons and checkboxes in a web + environment and the way that an S60 application shows single and multiple choice + selections. The SelectionList is recommeded to be used when the widget is using + the pointer navigation mode or when there are only a few options. +
+ + + +
+ + The SelectionMenu control is more similar to the way normal S60 applications + allow users to make single or multiple choices. The SelectionMenu takes up only + minimally of space in its normal state, but when activated it pops up up a list + of options with either radio buttons (for single selection) or checkboxes (for + multiple selection) that the user can select. The SelectionMenu control is good + for the tab navigation mode or if there are many options that would use up lots + of space on the screen using the SelectionList control. +
+ + + +
+ + Options in the selection controls are specified as an array of JavaScript + objects, where each object represents one option. Each option object has two + properties: value and text. The value property can be any JavaScript value, + including object references and is used to represent the concrete value of the + option. The text property is used to display the option in the user interface. + The value could for example be a boolean true or false while the + text could be "Yes" or "No". +
+ ++ + The set of currently selected options can be set or retrieved from a selection + control using getter and setter methods. For single selection controls the + selected option is specified as a single reference to one of the options in the + control. For multiple selection the selected options are specified as an array + of references to zero or more of the options in the control. Note that the + references to the options must refer to the very same options that are in the + control - not other instances of the options even if they are identical in value + and/or text. +
+ ++ + Selection controls fire "SelectionChanged" events when the user makes a + selection in the control. +
+ +