ListSelector
From WebOS101
Contents |
Introduction
ListSelectors provide an easy method for presenting the user with a pre-defined list of choices. ListSelectors are often used in preference scenes for presenting settings to users. The list selector is implemented internally as a popup menu.
Attribute Settings
The following attributes are used for ListSelectors:
| 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 2 items: [{label: <displayName>, value: <value set in object>}, {label: <displayName>, value: <value set in object>}, ... {label: <displayName>, value: <value set in object>}]" |
Model Settings
| 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 2 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. You can also pass through properties (e.g. icon, iconPath, disabled) that apply to menus in choices.
Events
ListSelectors only have one event: propertyChange. This event is fired whenever the setting is changed. The event property contains a reference to the model of the ListSelector that changed.
Working With ListSelectors
HTML Setup
<div id="options" x-mojo-element="ListSelector"></div>
JavaScript Setup
this.controller.setupWidget("options",
{
label: $L("Option Label"),
labelPlacement: Mojo.Widget.labelPlacementLeft,
choices: [
{label: "One", value: 1},
{label: "Two", value: 2},
{label: "Three", value: 3}
]
},
this.optionModel = {
value: 2,
disabled: false
}
);
Notes
- The label is quite limited in the number of characters you can fit. Choose the label carefully.
- By default, HTML escaping is turned on in Mojo applications since version 0.3.5 of the SDK. Unfortunately, there is no way to override HTML escaping for ListSelectors as you can do for template-based items. Your only recourse is to disable HTML escaping for the entire app or use a different widget. See Controlling HTML Escaping in Templates
