# Mojo.Widget.ListSelector

## Namespace Detail

### Overview

List selectors can be used for pop-up multiple-choice style editing of values. The current value of the ListSelector is always available in the model.value property. The ListSelector also contains a hidden input field with the current value, so it may be wrapped in a form if desired.

### Declaration

>     <div x-mojo-element="ListSelector" id="listselectorId"
>       class="listselectorClass"  name="listselectorName"></div>

Properties | Required | Value | Description
--- | --- | --- | ---
x-mojo-element | Required | ListSelector | Declares the widget as type 'ListSelector'.
id | Required | Any String | Identifies the widget element for use when instantiating or rendering.
class | Optional | Any String | ListSelector uses .palm-list-selector by default, but you can override with this setting.
name | Optional | Any String | Adds a unique name to the ListSelector widget; generally used in templates.

### Events

>     Mojo.Event.listen(this.controller.get("listselectorId"),
>       Mojo.Event.propertyChange, this.handleUpdate);

Event Type | Value | Event Handling
--- | --- | ---
Mojo.Event.propertyChange | event.value or model.value |

### Instantiation

>     this.controller.setupWidget("listselectorId",
>       this.attributes = {
>           choices: [
>               {label: "One", value: 1},
>               {label: "Two", value: 2},
>               {label: "Three", value: 3}
>           ]
>       },
>       this.model = {
>           value: 3,
>           disabled: false
>       }
>     );

### Attribute Properties

Attribute Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
labelPlacement | String | Optional | Mojo.Widget.labelPlacementRight | Mojo.Widget.labelPlacementRight: places label on right, value on left. Mojo.Widget.labelPlacementLeft: places label on left, value on right.
modelProperty | String | Optional | value | Model property name for ListSelector state.
disabledProperty | String | Optional | disabled | Model property name for disabled boolean.
label | String | Optional | Null | Label for the entire list, shown next to selected value in smaller, blue text.
multiline | Boolean | Optional | false | If true, long labels will wrap to the next line instead of being truncated.
choices | Array | Required | null | List of values for the popup. Must be defined in either the model or attributes and contain at least two items: [{label: <displayName>, value: <value set in object>}, {label: <displayName>, value: <value set in object>}, ... {label: <displayName>, value: <value set in object>}]

### Model Properties

Model Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
value | User-defined | Required | none | value of widget
disabled | Boolean | Optional | false | If true, ListSelector is inactive.
choices | Array | Required | null | List of values for the popup. Must be defined in either the model or attributes and contain at least two items: [{label: <displayName>, value: <value set in object>}, {label: <displayName>, value: <value set in object>}, ... {label: <displayName>, value: <value set in object>}]

* - A choices array must be present in either the attributes or model. If the choices are dynamic, meaning changeable after setup, then it should be in the model; otherwise in attributes.

### Methods

The ListSelector widget does not have any methods.