Widgets

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.