# Widget Reference

This section provides reference details for each of the available widgets. For a discussion of widgets in general, see All about widgets.

For coding examples showing how to use these widgets, see the UI Widgets Sample included in the SDK sample code.

The actual widget implementations are "widget assistants" in the various `widget_*.js` files, and common widget behavior is mostly encapsulated in `widget_controller.js`. New widgets are added to the framework simply by defining the new class in the Mojo.Widget namespace.

Although some widgets are instantiated automatically or on request, most are instantiated by the framework when it finds a `<div>` element in a scene that has the `x-mojo-element` attribute specified. This attribute names a widget class in the `Mojo.Widget` namespace. When a widget is instantiated, the framework creates a `WidgetController` instance for the div. The widget controller takes care of instantiating a widget assistant containing the actual widget implementation, and other standard widget setup work. Widget assistants must be instantiated via a `WidgetController`.

The widget assistant class's initialize method should be used only for intializing private state. Most widgets will probably choose not to implement it at all, and instead do initialization in the setup method, which is called slightly after the widget is instantiated. This is convenient, because at this time the widget can access the `WidgetController` via its controller property.

The WidgetController sets the following standard properties on itself:

- element: the widget's div element in the DOM.

- scene: the SceneController for the widget's scene.

- model: the widget's model, if appropriate (see below). This is the object containing the data the widget will display.

- attributes: the widget's attributes (like model, defines widget configuration, does not change between list items).

This lets all widget code reference the scene controller, model, and DOM element the same way.

## Widget Models

The framework will automatically hook up a widget with its attributes and data model object, and provide routing for notifications when the model changes.

When instantiating a widget, the framework checks to see if the scene assistant has set up attributes and/or a model for that widget using `setupWidget()`. If so, they will be set as the `WidgetController`'s attributes and model properties before the widget assistant's `setup()` method is called. If the widget implements a `handleModelChanged()` method, then it will automatically be called when the scene controller is notified of changes to the widget's model (via `SceneController.modelChanged())`.

If a setup cannot be found for the widget, the widget is not instantiated unless the assistant has a property `setupOptional:true`.

Widget | Description
--- | ---
Mojo.Widget.Button | Push button with optional activity indicator and callback.
Mojo.Widget.CheckBox | Simple bi-state check box.
Mojo.Widget.DatePicker | Provides UI for selecting a date.
Mojo.Widget.Drawer | A container that toggles between hidden and shown views.
Mojo.Widget.FilterField | A text field design for acting as a filter on application-specific data.
Mojo.Widget.FilterList | A filter field integrated with a list.
Mojo.Widget.ImageView | Views an image full-screen with support for zooming and panning, with an option to scroll to other images.
Mojo.Widget.IntegerPicker | Offers selection of a single integer field.
Mojo.Widget.List | The main list widget for editable, static, and dynamic lists with many options.
Mojo.Widget.ListSelector | Provides a multiple-choice pop-up selector.
Mojo.Widget.PasswordField | A special TextField for password entry.
Mojo.Widget.ProgressBar | Progress indicator using a bar graphic background.
Mojo.Widget.ProgressPill | Progress indicator using a View menu style background.
Mojo.Widget.ProgressSlider | Progress indicator integrated with a Slider widget; useful for streaming data indicators.
Mojo.Widget.RadioButton | Multiple choice selector in the form of a button array.
Mojo.Widget.RichTextEdit | A TextField with support for rich text editing.
Mojo.Widget.Scroller | Apply horizontal and/or vertical scrolling to a DIV's contents with snap options.
Mojo.Widget.Slider | Selector for a numerical range of values in the form of a horizontal slider.
Mojo.Widget.Spinner | Activity indicator that is manually started and stopped.
Mojo.Widget.TextField | The main text entry and edit widget with many options. You can combine this into forms.
Mojo.Widget.TimePicker | Provides UI for selecting a time setting.
Mojo.Widget.ToggleButton | Provides UI for switching between two states when tapped.
Mojo.Widget.WebView | Embeddable Web view for use within a scene.