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.