# Buttons and Selectors

The widgets in this group share some common features:

- Other than the Button, which has no value setting, the widgets allow you to define which property to use to hold the widget's data value. This can be useful when you want to use a single object to hold the data associated with multiple widgets as with a form.
- Any of the widgets can be disabled by setting the disabled property to true, and you can choose a different property to hold the disabled value by setting the disabledProperty in the widget attributes.

For more detail refer to the API documentation, Sample code or Styles references.

## Button

Mojo buttons can be enabled or disabled, and can optionally display an activity indicator, making them perfect for triggering an action expected to take some time. You should register as a listener for the Mojo.Event.tap event to allow a user to trigger actions.

To set up a button:

>     this.model = {
>       buttonLabel: "Button"
>     };
>     this.controller.setupWidget('button', {}, this.model);
>     //add a listener
>     this.controller.listen('button', Mojo.Event.tap, this.tapped.bind(this));

To react to a tap on the button:

>     tapped: function(event) {
>       Mojo.Log.info("button tapped");
>     }

If you have no need for advanced features, consider just using the button styling provided by the framework to get a div that matches button styling, or creating your own div with your own styles. The divs below will both still trigger a Mojo.Event.tap event when the user taps on it.

Framework appearance:

>     <div id="myButton" class="palm-button">Button</div>

## Check Box

A Check Box widget is used to control and indicate a binary state value in one element. Tapping a Check Box will toggle its state, presenting or removing a "check mark" depending on the previous state. The framework handles the display changes and will manage the widget's data model for you, toggling between two states that you defined at setup time. The check box is also one of the class of widgets that will allow you to specify a fieldName in the attributes. The framework will create a hidden input field as part of its setup that stores the current value of the check box for you, so that Mojo.View.serializeMojo on the form gives you all relevant information from the page.

Instantiate a basic check box that starts checked:

>     this.attributes = {
>       property: "value",
>     };
>     this.model = {
>       value: true
>     };
>     this.controller.setupWidget('checkbox', this.attributes, this.model);

If you need to respond to the state change as it happens, the widget generates a Mojo.Event.propertyChange event when selected.

>     this.controller.listen('sample-checkbox', Mojo.Event.propertyChange, this.changed.bind(this));
>     changed: function(propertyChangeEvent) {
>       Mojo.Log.info("The checkbox has changed to " + propertyChangeEvent.value +
>           " which is the same as in my model " + this.model.value);
>     }

## Toggle Button

The Check Box and Toggle Button are two different visual presentations of the same underlying widget. Mojo's ToggleButton will switch between two states each time it is tapped or swiped in the direction opposite its current state and generate a Mojo.Event.propertyChange event.

>     var attributes = {
>       modelProperty: "value",
>     };
>     this.model = {
>       value: true
>     };
>     this.controller.setupWidget('toggle', attributes, this.model);

## Radio Button

If you need to a single widget to switch between multiple states while revealing all the state options on the screen, then a Radio Button may fit your needs. Mojo provides a classic Radio Button that presents each button as a labeled selection option in a horizontal array in which only one option can be selected at at time. You can expect to handle two or three states and with proper styling.

To create a radio button with three options, where the second option is selected:

>     var attributes = {
>       modelProperty: 'value',
>       choices: [
>           {label : 'First', value : 1},
>           {label : 'Second', value : 2},
>           {label : 'Third', value : 3},
>       ]
>     };
>     this.model = {
>       value: 2
>     };
>     this.controller.setupWidget('radiobutton', attributes, this.model);
>     this.controller.listen('radiobutton', Mojo.Event.propertyChange, this.changed.bind(this));

When the user taps an option, the framework will handle the display change, update the modelProperty to the new choice and generate a Mojo.Event.propertyChange event. By listening to that event for that DIV element, you can respond to the selections if needed.

>     changed: function(propertyChangeEvent) {
>       Mojo.Log.info("The radiobutton has changed to "
>           + propertyChangeEvent.value +
>           " which is the same as in my model " + this.model.value);
>     }

## List Selector

The List Selector behaves and is managed as a selector. It enables the selection of one of many options, presented in a pop-up list in which there is no practical limit to the number of options presented. It shares the same behavior present in the Sub-menu widget, but with a different visual representation.

Whenever the List Selector is tapped, the framework handles the display actions associated with displaying, navigating and selecting from the list pop-up, assign the selection to the widget model, generate a Mojo.Event.propertyChange event to notify your scene assistant of the change.

To setup a List Selector widget to display a user's current IM status:

>     this.selectorsModel = {currentStatus: 'away'};
>     this.statuses = { [
>       {label:$L('Away'), value:"away", secondaryIcon:'status-away'},
>       {label:$L('Available'), value:"available",
>           secondaryIcon:'status-available', disabled:true},
>       {label:$L('Offline'), value:"offline", secondaryIcon:'status-offline'} ]
>     };
>     this.controller.setupWidget('statusSelector', {label: $L('Status'),
>       choices: this.statuses, modelProperty:'currentStatus'}, this.selectorsModel);
>     this.controller.listen('statusSelector',
>       Mojo.Event.propertyChange, this.changed.bindAsEventListener(this));
>     changed: function(propertyChangeEvent) {
>       Mojo.Log.info("The user's current status has changed to " +
>           this.selectorsModel.currentStatus);
>     }

Where the List Selector is like the List widget is in its styling. To have the HP webOS look and feel, you'll need to wrap your widget declaration with styling DIVs like those used with the List widget. For more information or for a full explanation of the styling options, see the Styles and CSS Reference under the User Interface Guidelines section of the SDK Documentation.

## Slider

The last widget in this group is the Slider, which presents a range of selection options in the form of a horizontal slider with a control knob that can be dragged to the desired location.

Each time the slider is tapped, dragged and released, the value associated with the slider's modelProperty is updated and a Mojo.Event.propertyChange event is generated. The framework will use the minimum and maximum values you provide at setup to determine the current value associated with the slider. If you specify 0 to 100, and the knob is centered, the updated value will be 50; specify 0 and 1 and the updated value with be .5.

To setup a slider widget that ranges between values 0 and 1 and starts halfway through the slider:

>     var attributes = {
>       property: 'value',
>       maxValue: 1,
>       minValue: 0
>     };
>     this.model = {
>       value: .5
>     };
>     this.controller.setupWidget('slider', attributes, this.model);
>     this.controller.listen('slider',Mojo.Event.propertyChange, this.propertyChanged.bind(this));

To manage updates to the value by the user:

>     propertyChanged: function(propertyChangeEvent) {
>       Mojo.Log.info("The slider has changed to " + propertyChangeEvent.value +
>           " which is the same as in my model " + this.model.value);
>     }

To change the value of the slider programmatically:

>     updateSliderValue: function(newValue) {
>       this.model.value = .75;
>       this.controller.modelChanged(this.model);
>     }