+ + The SelectionControl class is an abstract base class for all controls that lets + the user select one or more options from a set of options. +
+ ++ + The options in a selection control are simple option objects with two properties: + value and text. An option is specified using JavaScript object notation (JSON) as + +{ value: "value here", text: "Text for value goes here" }. The value + property specifies the actual value of the option whereas the text property specifies + how the option is shown to the user in the control. E.g. the value could be a boolean + value while the text could be "Yes" or "No". The text value is an XHTML string. +
+ ++ + Don't instantiate SelectionControl directly but rather one of its subclasses. +
+ ++ + +Control +
+ ++SelectionChanged
+ + + ++ + This event is fired when the user selects one or more values in the control. +
+ + ++[Boolean] SelectionControl.isMultipleSelection(void)+ +
+ + Returns a boolean value that indicates whether the selection control lets + users select multiple options. +
+ ++ + This method does not take any arguments. +
+ ++ + True if the control lets users select multiple options, false if only a single option + can be selected at any given time. +
+ ++[Boolean] SelectionControl.isSelected(Option option)+ +
+ + Returns a boolean value that indicates whether the the specified option + is currently selected. Options are objects with two properties: value and text. +
+ ++option
+ + + ++ + The option to check the selected state for. +
+ + ++ + True if the specified option is selected, false if not. +
+ ++[Option|Array] SelectionControl.getSelected(void)+ +
+ + Retrieves the currently selected option or options. If the control is a multiple + selection control then an array of selected options is returned (an empty array if + no options are selected). If the control is a single selection control then the + single selection option is returned, or null if no options are selected. + Options are objects with two properties: value and text. +
+ ++ + This method does not take any arguments. +
+ ++ + An array containing the currently selected options for multiple selection controls. + For single selection controls the return value is the selected option. If no options + are selected then an empty array is returned for multiple selection controls and null + is returned for single selection controls. +
+ ++[void] SelectionControl.setSelected(Option|Array selected)+ +
+ + Sets the currently selected options for a selection control. The selected options + should be a subset of the options contain within the control. For a multiple selection + control an array of options should be specified. For a single selection control the + single option that should be selected should be specified without being contained in + an array. To select zero options pass an empty array for multiple selection controls + and null for single selection controls. Options are objects with two properties: + value and text. +
+ ++selected
+ + + ++ + The options to select. For multiple selection controls this argument + should be an array of the options to select or an empty array to select + zero elements. For single selection controls it should be a single option + object or null for no selected options. +
+ + ++ + This method does not return a value. +
+ ++[Array] SelectionControl.getOptions(void)+ +
+ + Retrieves the options available to the user in the control. The options are + returned as an array of option objects. Options are objects with two properties: + value and text. +
+ ++ + This method does not take any arguments. +
+ ++ + An array containing the options in the control. +
+ ++[void] SelectionControl.setOptions(Array options)+ +
+ + Sets the options that this control should give the user. Calling this method + replaces the current options with the specified new ones. If one or more selected + options are no longer part of the available options after calling this method + then they will automatically be removed from the selected set. The options + are given as an array of option objects. Options are objects with two properties: + value and text. The text value is an XHTML string. +
+ ++options
+ + + ++ + An array of options to give the user. These options replace the + current options in the control. +
+ + ++ + This method does not return a value. +
+ ++[Array] SelectionControl.getOptionForValue(Object value)+ +
+ + Retrieves the option in the selection control that has a value that matches + the specified one. If multiple options have the same value then the first matching + one is returned. If there is no match then null is returned. +
+ ++ + This method is a useful helper method for situations where a specific value in the + options should be programmatically selected. +
+ ++value
+ + + ++ + The value to search for among the options in the selection control. + The value can be of any JavaScript type. +
+ + ++ + The first option in this selection control that has a value that matches the + specified one, or null if no matching option is found. +
+ +