# WRTKit SelectionControl Class

## Description

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.

## Inherits from

Control

## Events

- SelectionChanged

  This event is fired when the user selects one or more values in the control.

Parent topic: WRTKit API Reference

## isMultipleSelection()

### Syntax

    [Boolean] SelectionControl.isMultipleSelection(void)

### Description

Returns a boolean value that indicates whether the selection control lets users select multiple options.

### Arguments

This method does not take any arguments.

### Return value

True if the control lets users select multiple options, false if only a single option can be selected at any given time.

## isSelected()

### Syntax

    [Boolean] SelectionControl.isSelected(Option option)

### Description

Returns a boolean value that indicates whether the the specified option is currently selected. Options are objects with two properties: value and text.

### Arguments

- option

  The option to check the selected state for.

### Return value

True if the specified option is selected, false if not.

## getSelected()

### Syntax

    [Option|Array] SelectionControl.getSelected(void)

### Description

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.

### Arguments

This method does not take any arguments.

### Return value

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.

## setSelected()

### Syntax

    [void] SelectionControl.setSelected(Option|Array selected)

### Description

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.

### Arguments

- 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.

### Return value

This method does not return a value.

## getOptions()

### Syntax

    [Array] SelectionControl.getOptions(void)

### Description

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.

### Arguments

This method does not take any arguments.

### Return value

An array containing the options in the control.

## setOptions()

### Syntax

    [void] SelectionControl.setOptions(Array options)

### Description

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.

### Arguments

- options

  An array of options to give the user. These options replace the current options in the control.

### Return value

This method does not return a value.

## getOptionForValue()

### Syntax

    [Array] SelectionControl.getOptionForValue(Object value)

### Description

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.

### Arguments

- value

  The value to search for among the options in the selection control. The value can be of any JavaScript type.

### Return value

The first option in this selection control that has a value that matches the specified one, or null if no matching option is found.