Mojo.Widget
Namespace Detail
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.
| Field Name and Description |
|---|
|
Mojo.Widget.Button
|
|
Mojo.Widget.CheckBox
|
|
Mojo.Widget.DatePicker
|
|
Mojo.Widget.Drawer
|
|
Mojo.Widget.FilterField
|
|
Mojo.Widget.FilterList
|
|
Mojo.Widget.ImageView
|
|
Mojo.Widget.IntegerPicker
|
|
Mojo.Widget.List
|
|
Mojo.Widget.ListSelector
|
|
Mojo.Widget.PasswordField
|
|
Mojo.Widget.ProgressBar
|
|
Mojo.Widget.ProgressPill
|
|
Mojo.Widget.ProgressSlider
|
|
Mojo.Widget.RadioButton
|
|
Mojo.Widget.RichTextEdit
|
|
Mojo.Widget.Scroller
|
|
Mojo.Widget.Slider
|
|
Mojo.Widget.Spinner
|
|
Mojo.Widget.TextField
|
|
Mojo.Widget.TimePicker
|
|
Mojo.Widget.ToggleButton
|
|
Mojo.Widget.WebView
|
Detail
Overview
Buttons are the most basic UI element, which allow an action to be bound to a region. Buttons have a text label that can be updated dynamically. ButtonWidgets are automatically styled to look like other buttons within the webOS.
Declaration
<div x-mojo-element="Button" id="buttonId" class="buttonClass" name="buttonName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required Button Declares the widget as type 'Button'
id Required Any String Identifies the widget element for use when instantiating or rendering; should be unique in the
document
class Optional Any String All buttons belong to the class palm-button but override this with a custom class
name Optional Any String Add a unique name to the button widget; generally used in templates when used
Events
Mojo.Event.listen("buttonId",Mojo.Event.tap, this.handleUpdate)
Event Type Value Event Handling
----------------------------------------------------
Mojo.Event.tap None Respond to button tap
Instantiation
this.controller.setupWidget("buttonId",
this.attributes = {
},
this.model = {
label : "BUTTON",
disabled: false
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
label String Optional null Button's label if none is supplied by the model
type String Optional Mojo.Widget.defaultButton Type options:
Mojo.Widget.defaultButton - simple pushbutton
Mojo.Widget.activityButton- pushbutton with spinner activated on tap of the
button
disabledProperty String Optional "disabled" Model property name for disabled
labelProperty String Optional "label" Model property name for label
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
buttonLabel String Optional null DEPRECATED Button's label
buttonClass String Optional primary Model property that has the CSS class name of this button
disabled Boolean Optional FALSE If true, button is inactive
label String Optional null Button's label
Methods
Method Arguments Description
----------------------------------------------------------------------------------------------
activate None For an activity button, start the spinner
deactivate None For an activity button, stop the spinner
Activate
buttonWidget.mojo.activate();
Deactivate
buttonWidget.mojo.deactivate();
Overview
A CheckBox widget like a ToggleButton, is used to control and indicate a binary state value in one element. Which widget to use is really a matter of design preference as they serve almost an identical function. Tapping a CheckBox will toggle it's state, presenting or removing a "checkmark" 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.
Declaration
<div x-mojo-element="CheckBox" id="checkboxId" class="checkboxClass" name="checkboxName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required CheckBox Declares the widget as type 'CheckBox'
id Required Any String Identifies the widget element for use when instantiating or rendering
Events
Mojo.Event.listen("checkboxId", Mojo.Event.propertyChange, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.propertyChange Sends an event with the added properties 'model' and 'value'; Model is the model supplied when the application
first set up the widget with a value updated to reflect the state of the checkbox; value represents the
current value of the checkbox regardless of model.
Instantiation
this.controller.setupWidget("checkboxId",
this.attributes = {
trueValue: 'On',
falseValue: 'Off'
},
this.model = {
value: false,
disabled: false
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
modelProperty String Optional "value" Model property name for checkbox state
disabledProperty String Optional "disabled" Model property name for disabled boolean
trueValue String Optional true Value to set model property when true
falseValue String Optional false Value to set model property when false
fieldName String Optional none DEPRECATED Idenitifer for the value of the checkbox; used when the checkbox is used in html forms
inputName String Optional none Idenitifer for the value of the checkbox; used when the checkbox is used in html forms
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value User-defined Required none Current value of widget
disabled Boolean Optional false If true, checkbox is inactive
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
None
Overview
The DatePicker offers selection of the month, day and year. It is one of the simple picker widgets which present their choices as a linear sequence of values that wraps around; when you scroll to the end of the sequence, it simply continues back at the beginning. The Date and Time pickers use the JavaScript Date object to represent the chosen date in their data model.
Declaration
<div x-mojo-element="DatePicker" id="datepickerId" class="datepickerClass" name="datepickerName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required DatePicker Declares the widget as type 'DatePicker'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String There isn't a default class for DatePicker but you can assign one if you want apply custom styling
name Optional Any String Add a unique name to the datepicker widget; generally used in templates when used
Events
this.controller.listen("datepickerId",'mojo-propetyChange', this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.propertyChange event.value Respond to DatePicker value change
or model.time
Instantiation
var todayDate = new Date();
this.controller.setupWidget("datepickerId",
this.attributes = {
label: 'Date',
modelProperty: 'time' // one may override the default modelProperty so as to share a Date object with a time picker
},
this.model = {
time: todayDate
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
label String Optional 'Date' Label displayed for the widget controls
labelPlacement String Optional Mojo.Widget.labelPlacementLeft Mojo.Widget.labelPlacementRight : places label on right, value on left.
Mojo.Widget.labelPlacementLeft : places label on left, value on right
modelProperty String Optional date Model property name for date object
month Boolean Optional true Specify whether or not to include the month in your date picker; default is true
day Boolean Optional true Specify whether or not to include the day in your date picker; default is true
year Boolean Optional true Specify whether or not to include the year in your date picker; default is true
maxYear Integer Optional 2099 Specify max year in year capsule if enabled
minYear Integer Optional 1900 Specify min year in year capsule if enabled
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
date Date Object Required null Date object to set initial widget value and updated value after user selection
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
None
Overview
Drawers are container widgets that can be "open", allowing child content to be displayed normally, or "closed", keeping it out of view. The open state of the drawer depends on a single model property, although there are also widget APIs available for manually opening & closing a drawer. It should be noted that although these APIs modify the 'open' model property, they do not send Mojo.Event.propertyChange events, but use the standard DOM click event instead.
Declaration
<div x-mojo-element="Drawer" id="drawerId" class="drawerClass" name="drawerName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required Drawer Declares the widget as type 'Drawer'
id Required Any String Identifies the widget element for use when instantiating or rendering
Events
None
Instantiation
this.controller.setupWidget("drawerId",
this.attributes = {
modelProperty: 'open',
unstyled: false
},
this.model = {
open: true
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
modelProperty String Optional open Name of model property to hold the drawer's open state.
unstyled Boolean Optional false Prevents styles from being added, allowing the Drawer to be used just
for open/close functionality; drawer contents will always be moved into a Drawer
structure and positioned relatively
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
open Boolean Required true Initial Drawer state and toggled with each click
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
setOpenState open Sets the open state to open or closed
getOpenState none Returns current value of open state
toggleState none Change the drawer's open state to the opposite of what it is now
Overview
The FilterField wiget has an input field displayed at the top of the screen that displays the result of just typing to the screen when no other input field is focused. The field is hidden when empty, it's initial state, but it is given focus in the scene so that any typing is captured in the field.
As soon as the first character is entered, the framework displays the field and calls the specified filterFunction. The FilterField automatically delays events so that a search is not triggered as the result of every query.
Declaration
<div x-mojo-element="FilterField" id="filterFieldId" class="filterFieldClass" name="filterFieldName" ></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required FilterField Declares the widget as type 'FilterField'
id Required Any String Identifies the widget element for use when instantiating or rendering
Events
Mojo.Event.listen("filterFieldId",Mojo.Event.filter, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.filter filterString: value in the filter field. Sent after the specified delayed passes.
Mojo.Event.filterImmediate filterString: value in the filter field. Sent on every key press.
Instantiation
this.controller.setupWidget('filterField',
this.attributes = {
delay: 5000,
filterFieldHeight: 100
},
this.model = {
disabled: false
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
delay Optional 300ms how long to wait between key strokes for a filter event;
helps to queue them up so not constantly searching.
disabledProperty String Optional "disabled" Model property name for disabled
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
disabled Boolean false 'disabled' If true, the FilterField does not open when keys are typed
with no focused element on the screen
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
close None Close the FilterField
open None Open the FilterField
setCount count(Integer) Set the number to be shown in the results bubble in the FilterField
Overview
When your list is best navigated with a search field, particularly one where you would instantly filter the list as each character is typed into the field, you would want to use the FilterList widget. It is intended to display a variable length list of objects, which can be filtered through a call back function.
The widget has a text field displayed above a list, where the list is the result of applying the contents of the text field against some off-screen data source. The text field is hidden when empty, it's initial state but it is given focus in the scene so that any typing is captured in the field. As soon as the first character is entered, the framework displays the field and calls the specified filterFunction.
Declaration
<div x-mojo-element="FilterList" id="listId" class="listClass" name="listName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required FilterList Declares the widget as type 'FilterList'
id Required Any String Identifies the widget element for use when instantiating or rendering
Events
Mojo.Event.listen("filterlistId", Mojo.Event.listTap, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.listChange {model:this.controller.model, item:dataObj, index: index + this.renderOffset, originalEvent:event}
Mojo.Event.listTap event.value or model.value
Mojo.Event.listAdd
Mojo.Event.listDelete event.item
event.index
Mojo.Event.listReorder event.item
event.toIndex
event.fromIndex
Mojo.Event.filter event.filterString
Mojo.Event.filterImmediate event.filterString
Instantiation
this.controller.setupWidget("filterlistId",
this.attributes = {
itemTemplate: 'filterlistscene/static-list-entry',
listTemplate: 'filterlistscene/static-list-container',
addItemLabel: $L('Add ...'),
swipeToDelete: true,
reorderable: true,
filterFunction: this.filterFunction.bind(this)},
delay: 350,
emptyTemplate:'filterlist/emptylist'
},
this.model = {
disabled: false
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
filterFunction Function Optional None Called to load items when the list is scrolled or filter changes. Function definition:
filterFunction (filterString, listWidget, offset, count)
delay Integer Optional 300 Delay after entry before filter function is called (in ms)
Plus all attributes available in the List widget
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
disabled Boolean Optional False If true, filter field is disabled
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
getList none Get the List widget associated with this FilterList
close none Close the FilterField associated with this FilterList
open none Open the FilterField associated with this FilterList
setCount count (Integer) Set the count in the bubble in the FilterField associated with this FilterList
Plus all methods available in the List widget and FilterField widget
Overview
This widget is designed to view an image full screen with support for zooming and panning while optionally moving between additional images. You can use this for single images, or flick left and right through a series of images. You can assign handlers through the onLeftFunction and onRightFunction attributes properties and listen to mojo-imageViewChanged; from the handlers use the methods leftUrlProvided(url), rightUrlProvided(url), and centerUrlProvided(url) to build a scrolling list of images.
Declaration
<div x-mojo-element="ImageView" id="ImageId" class="ImageClass" name="ImageName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required ImageView Declares the widget as type 'ImageView'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String Provide your own unique class and override the frameworks styles
name Optional Any String Add a unique name to the ImageView widget; generally used in templates when used
Events
Mojo.Event.listen("ImageId",Mojo.Event.propertyChange, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.imageViewChanged event.url event fires when image in view changes
Instantiation
this.controller.setupWidget("ImageId",
this.attributes = {
noExtractFS: true
},
this.model = {
onLeftFunction: this.onLeft.bind(this),
onRightFunction: this.onRight.bind(this)
}
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
highResolutionLoadTimeout
Number Optional 1.2 Time to wait before switching photo to high res
extractfsParams String Optional "800:800:3"
lowResExtractFSParams String Optional "160:160:3"
noExtractFS Boolean Optional false Flag to prevent looking up a high res versio
limitZoom Boolean Optional false Flag to prevent or limit zooming
panInsetX Number Optional 0
panInsetY Number Optional 0
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
onLeftFunction Function Optional None Called after a left transition
onRightFunction Function Optional None Called after a right transition
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
getCurrentParams None Return the current zoom level and focus [0,1]
manualSize width, height Manually size the widget
leftUrlProvided filepath or url Tell the widget to use this image as the left
rightUrlProvided filepath or url Tell the widget to use this image as the right
centerUrlProvided filepath or url Tell the widget to use this image as the center
Overview
The IntegerPicker offers selection of a single integer field. It is one of the simple picker widgets which present their choices as a linear sequence of values that wraps around; when you scroll to the end of the sequence, it simply continues back at the beginning.
Declaration
<div x-mojo-element="IntegerPicker" id="integerpickerId" class="integerpickerClass" name="integerpickerName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required IntegerPicker Declares the widget as type 'IntegerPicker'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String There isn't a default class for IntegerPicker but you can assign one if you want apply custom styling
name Optional Any String Add a unique name to the integerpicker widget; generally used in templates when used
Events
this.controller.listen("integerpickerId",'mojo-propetyChange', this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.propertyChange event.value Respond to IntegerPicker value change
or model.time
Instantiation
this.controller.setupWidget("integerpickerId",
this.attributes = {
label: 'Number',
modelProperty: 'value',
min: 0,
max: 20
},
this.model = {
value: 5
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
label String Optional 'Value' Label displayed for the the widget controls
labelPlacement String Optional Mojo.Widget.labelPlacementLeft 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 date object
min Integer Required required Minimum selection option
max Integer Required required Maximum selection option
padNumbers boolean Optional false Add padding to single digit numbers or not
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value Integer Required required Initial widget value and updated value after user selection
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
None
Overview
List is the most common and possibly the most powerful Mojo widget. Objects are rendered into list items using provided HTML templates, and may be variable height and/or include other widgets. Lists can be static, where the list items are provided to the widget directly as an array, or they can be dynamic, where the application provides a callback function which is invoked as additional items are needed for display. Lists can be manipulated in place, with the framework handling deletion, reordering and addition functions for the application.
Declaration
<div x-mojo-element="List" id="listId" class="listClass" name="listName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required List Declares the widget as type 'List'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String Provide your own unique class and override the frameworks styles
name Optional Any String Add a unique name to the list widget; generally used in templates when used
Events
this.controller.listen("listId", Mojo.Event.listTap, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.listChange {model:this.controller.model, item:dataObj, index: index + this.renderOffset, originalEvent:event}
Mojo.Event.listTap event.item
Mojo.Event.listAdd
Mojo.Event.listDelete event.item
event.index
Mojo.Event.listReorder event.item
event.toIndex
event.fromIndex
Instantiation
this.controller.setupWidget("listId",
this.attributes = {
itemTemplate: 'listscene/static-list-entry',
listTemplate: 'listscene/static-list-container',
addItemLabel: $L('Add ...'),
swipeToDelete: true,
reorderable: true,
emptyTemplate:'list/emptylist'
},
this.model = {
listTitle: $L('List Title'),
items : [
{data:$L("Item 1"), year:$L("1974")},
{data:$L("Item 2"), year:$L("1975")},
{data:$L("Item 3"), year:$L("1972")},
{data:$L("Item 4"), year:$L("2003")},
{data:$L("Item 5"), year:$L("1996")},
{data:$L("Item 6"), year:$L("1969")},
]
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
listTemplate String Optional File path relative to app folder for container template
itemTemplate String Required File path relative to app folder for item template
addItemLabel String Optional None If defined, a special "add" item will be appended to the list and taps on this
item will generate a 'Mojo.Event.listAdd' event. The string is used to label the entry;
if null, then it will default to "+Add".
formatters Function Optional Object functions to format list entries based on model properties
preventDeleteProperty String Optional If specified, the item models will be checked for this property, and swipeToDelete will be
ignored on that item if the item model's property is truthy.
itemsProperty String Optional items Model property for items list
itemsCallback Function Optional None Items will be loaded as needed by calling this function
swipeToDelete Boolean Optional FALSE If true, list entries can be deleted with a swipe
autoconfirmDelete Boolean Optional TRUE If false, delete swipes will post a 'delete/undo' button pair, otherwise deletes
will be made immediately after swiping
uniquenessProperty String Optional None Name of an item model property which can be used to uniquely identify items.
If specified, List will maintain a hash of swiped items instead of setting a deleted property,
preventing the app from having to persist the deleted property.
reorderable Boolean Optional FALSE If true, list entries can be reordered by drag & drop
dividerFunction Function Optional Function to create divider elements
dividerTemplate Function Optional list-divider.html Function to format divider
fixedHeightItems Boolean Optional FALSE If true, list widget will apply optimizations for fixed height items
initialAverageRowHeight Integer Optional ? Initial value used for average height estimation
renderLimit Integer Optional 20 Max number of items to render at once; increase this if the UI overruns
the list boundaries
lookahead Integer Optional 15 Number of items to fetch ahead when loading new items
dragDatatype String Optional None Used for drag&drop reordering. If specified will allow items to be dragged from one
list to another of the same datatype
deletedProperty String Optional deleted Name of the item object property in which to store the deleted status of an item
nullItemTemplate String Optional default template File path relative to app folder for template for items that are
rendered before loading
emptyTemplate String Optional default template File path relative to app folder for template for empty list; this is only implemented for lists loaded via the itemsCallback property
onItemRendered Function Optional None Called each time an item is rendered into the DOM with these arguments
(listWidget, itemModel, itemNode)
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
items Array Optional None Contains a list of Objects to display in the list; required unless itemsCallback property
is set as a an Attributes property
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
focusItem itemModel, focusSelector Focus the item designated by the item model; optionally pass in the focusSelector to focus a specific element within the item
showAddItem boolean Show the "add item" in the list
noticeUpdatedItems offset, items (array) Causes the given items to be replaced and re-rendered. Items provided past the current end of the list will cause the length to grow. MUST pass
an array
noticeAddedItems offset, items (array) Inserts the given array of items into the list at the given offset.If list items are dynamically loaded, this may cause some to be kicked out of
the cache. Calling this API will not cause a property-change event to be fired.
noticeRemovedItems offset, limit Removes items from the list beginning at the given offset, and continuing for 'limit' items. If list items are dynamically loaded, this may
cause new ones to be requested. Calling this API will not cause a property-change event to be fired.
getNodeByIndex index Return top level node for the list item of the given index. Returns undefined if the item does not exist or is not currently rendered.
invalidateItems offset, limit Causes the given items to be reloaded (if currently loaded). If limit is unspecified, causes all items after 'offset' to be invalidated.
getLoadedItemRange Returns a hash with offset & limit properties indicating the range of currently loaded item models (or items which have been requested).
This is sometimes used on the service side to optimize subscription data.
getMaxLoadedItems Returns the maximum number of loaded items the list will maintain in its local cache.
function has no affect when the list size != 0.
setLength length Call to set the overall length of the list.
This function will set the limit on what range of items may be requested, but will generally not invalidate any existing items
or request any new ones. It MAY request new items when the currently loaded items window
is either not full, or the length change causes the items window to move. The latter case can occur if the length change causes the
window to be "out of bounds", or if it would ideally be positioned past the end of the list.
setLengthAndInvalidate length Behaves like setLength, except that all currently loaded items are invalidated.
For lazily loaded lists, this API will result in a request for a whole window of items.
Note that items are invalidated even when the length of the list does not actually change.
getLength Returns the current length of the list.
revealItem index, animate (boolean) Attempts to scroll the scene to reveal the item with the given index
May behave poorly when working with variable height list items which are not currently loaded, since we can't accurately predict the height of
the final rendered content.
getItemByNode node Returns the item model associated with the list item containing the given node, if any. Returns undefined if not.
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 the .palm-list-selector by default but you override this setting
name Optional Any String Add a unique name to the listselector widget; generally used in templates when used
Events
Mojo.Event.listen("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 radiobutton 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 Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value User-defined Required none value of widget
disabled Boolean Optional false If true, radiobutton 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.
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
None
Overview
If you need a text field that will be used for passwords or some other type of confidential information,
the Password Field provides many of the Text Field features but masks the display. Any entered text is
displayed as a bullet, or "•" character. As with the Text Field the framework handles all of the
editing logic within the field and generates a Mojo.Event.propertyChange event when the field has been updated.
Declaration
<div x-mojo-element="PasswordField" id="listId" class="listClass" name="listName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required PasswordField Declares the widget as type 'PasswordField'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String Provide your own unique class and override the frameworks styles
name Optional Any String Add a unique name to the passwordfield widget; generally used in templates when used
Events
Mojo.Event.listen("passwordfieldId", Mojo.Event.propertyChange, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.propertyChange {model:model, property:property, value:value, oldValue: oldValue, originalEvent: originalEvent}
Instantiation
this.controller.setupWidget("passwordfieldId",
this.attributes = {
hintText: $L('Type Password')
},
this.model = {
value: ""
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
modelProperty String Optional "value" Model property name for selector value
hintText String Optional None Initially displayed string; supplanted by model value if supplied
textFieldName String Optional None DEPRECATED If supplied, the textarea will have this name, so that when it is serialized,
the property can be easily pulled out
inputName String Optional None If supplied, the textarea will have this name, so that when it is serialized, the property can be easily pulled out
charsAllow Function Optional None Function must return 'true' to allow input character, or 'false' if not allowed;
note: this event is sent as a result of a keyPress event, so you must check
against key codes matching ASCII characters.
focus Boolean Optional FALSE DEPRECATED If true, field has focus on scene push
autoFocus Boolean Optional FALSE If true, field has focus on scene push
modifierState String Optional None "initial state of modifier keys for this field. Can be:
Mojo.Widget.numLock,
Mojo.Widget.capsLock"
autoResize Boolean Optional FALSE DEPRECATED Automatically grow field horizontally
growWidth Boolean Optional FALSE Automatically grow field horizontally
autoResizeMax Integer Optional None Maximum width of field
enterSubmits Boolean Optional FALSE When used in conjunction with multline, if this is set, then enter will submit rather than newline
limitResize Boolean Optional FALSE Limit height resize (scrolls text rather than grow field)
preventResize Boolean Optional FALSE There will be no resizing in any dimension
holdToEnable Boolean Optional FALSE if the textfield is disabled, tapping and holding and releasing will enable it;
if disabled is not set, this is ignored
focusMode String Optional Insert Mode "Replace or Insert Mode; choices:
Mojo.Widget.focusSelectMode
Mojo.Widget.focusInsertMode
Mojo.Widget.focusAppendMode
Text will either all be selected (Select), or a cursor will
appear where the user tapped (Insert) or cursor goes to end of text (Append)
changeOnKeyPress Boolean Optional FALSE If true, sends a propertyChange event on every character change to a field;
otherwise only when focus lost
textReplacement Boolean Optional FALSE Whether to enable the SmartTextEngine services of PalmSysMgr. Disabled by default
in the PasswordField. Not recommended for use with PasswordField.
maxLength Integer Optional No Limit Maximum character length of field; does not apply to multiline fields where it will be ignored
requiresEnterKey Boolean Optional FALSE Required Enter key to submit; other navigation will not genterate submit event
holdToEdit Boolean Optional FALSE Tap and Hold to focus/edit; Tap only will be ignored
autoCapitalization Boolean Optional FALSE The first letter of each word (determined by whitespace) is capitalized.
Not recommended for use with PasswordField.
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value String Required Null Initial and updated value of widget
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
focus none Focus the input part of the password field
blur none Blur the input part of the password field
getValue none Get the plaintext value of the password field
setText String DEPRECATED Set the plaintext value of the text field
setValue String Set the plaintext value of the text field
getCursorPosition none Returns on object with {selectionStart: int, selectionEnd: int} that describe the position of the cursor; if start is not
equal to end, then there is text selected
setCursorPosition start, end Set the cursor position in the input portion of the textfield; if start and end are not the same, then this
will select the text between START and END; if start and/ or end occur in invalid positions, they will be changed
to valid positions at the end of the text if they were larger than the size of the value, or at the beginning, if they
are smaller than the size of the value; empty text will result in a cursor at the start of the textfield
Set x-mojo-focus-highlight=true on any parent div to have the focus class applied to it as well when the PasswordField widget becomes focused
Overview
The Progress Bar is exactly the same as the Progress Pill except that you use "x-mojo-element="ProgressBar" in your scene file. Otherwise, you would code it and manage just as you do the Progress Pill. In the default style, there isn't room for a title, or any type of images on the bar, but the properties are supported nonetheless.
As with the Progress Pill, this is useful to show download progress, loading from a database or just a long operation where you have a sense of the duration, then you can use Progress Pill as the indicator. The indicator is designed to show a Bar image that corresponds to the model's value property, where a value of 0 has no Pill exposed and a value of 1 has the Pill in a complete position. To control the indicator you need to initialize it's value at 0, then progressively update the model property it until it reaches the value of 1. The best way to do this is by using an interval timer to which you can respond by increasing the progress indicator's value property incrementally and calling the updateModel function.
Declaration
<div x-mojo-element="ProgressBar" id="progressbarId" class="progressbarClass" name="progressbarName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required ProgressBar Declares the widget as type 'ProgressBar'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String There isn't a default class for ProgressBar but you can assign one if you want apply custom styling
name Optional Any String Add a unique name to the progressbar widget; generally used in templates when used
Events
Mojo.Event.listen("progressbarId", Mojo.Event.progressIconTap, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.progressIconTap {model: this.controller.model} The icon in the bar was tapped, app specific action but usually cancel operation
Mojo.Event.progressComplete Progress is complete
Instantiation
this.controller.setupWidget("progressbarId",
this.attributes = {
title: 'Progress Bar',
image: 'images/header-icon.png',
modelProperty: "progress"
},
this.model = {
iconPath: "../images/progress-bar-background.png",
progress: 0
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
modelProperty String Optional value Widget's model property name
title String Optional Null Dynamic title to show on download bar
image String Optional Null File path relative to app folder for dynamic image to show on bar
icon String Optional Null CSS class for icon to display on the bar
iconPath String Optional Null File path relative to app folder for icon
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value Integer Required Null Current value of widget
title String Optional Null Dynamic title to show on download bar
image String Optional Null File path relative to app folder for dynamic image to show on bar
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
reset Reset the progress to 0
cancelProgress Stop progress and leave the progress pill visually where it was
Overview
When you need to show download progress, loading from a database or just a long operation where you have a sense of the duration, then you can use Progress Pill as the indicator. The indicator is designed to show a Pill image that corresponds to the model's value property, where a value of 0 has no Pill exposed and a value of 1 has the Pill in a complete position. To control the indicator you need to initialize it's value at 0, then progressively update the model property it until it reaches the value of 1. The best way to do this is by using an interval timer to which you can respond by increasing the progress indicator's value property incrementally and calling the updateModel function.
Declaration
<div x-mojo-element="ProgressPill" id="progresspillId" class="progresspillClass" name="progresspillName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required ProgressPill Declares the widget as type 'ProgressPill'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String There isn't a default class for ProgressPill but you can assign one if you want apply custom styling
name Optional Any String Add a unique name to the progresspill widget; generally used in templates when used
Events
Mojo.Event.listen("progresspillId",Mojo.Event.progressIconTap, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.progressIconTap {model: this.controller.model} The icon in the bar was tapped, app specific action but usually cancel operation
Mojo.Event.progressComplete Progress is complete
Instantiation
this.controller.setupWidget("progresspillId",
this.attributes = {
title: 'Progress Pill',
image: 'images/header-icon.png',
modelProperty: "progress"
},
this.model = {
iconPath: "../images/progress-bar-background.png",
progress: 0
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
modelProperty String Optional value Widget's model property name
modelStartProperty String Optional modelStartProperty Name of start value property for this widget instance
title String Required Null Dynamic title to show on download bar
titleRight String Optional Null Dynamic title to show on the right side of the download bar
image String Optional Null File path relative to app folder for dynamic image to show on bar
icon String Optional Null CSS class for icon to display on the bar
iconPath String Optional Null File path relative to app folder for icon
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value Integer Required Null Current value of widget; if value is undefined or negative, will show
in "button-mode" which gives a selected class
title String Required Null Dynamic title to show on download bar
titleRight String Optional Null Dynamic title to show on the right side of the download bar
image String Optional Null File path relative to app folder for dynamic image to show on bar
modelStartProperty Integer Optional Null Starting position of the progress bar
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
reset Reset the progress to 0
cancelProgress Stop progress and leave the progress pill visually where it was
Overview
For media, or other applications where you want to show progress as part of a tracking slider, then the Progress Slider is an ideal choice. Combining the Slider widget with the Progress Pill, you almost have both widgets in one but not all of the options are represented.
Declaration
<div x-mojo-element="ProgressSlider" id="progresssliderId" class="progresssliderClass" name="progresssliderName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required ProgressSlider Declares the widget as type 'ProgressSlider'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String Provide your own unique class and override the frameworks styles
name Optional Any String Add a unique name to the progressslider widget; generally used in templates when used
Events
Mojo.Event.listen("progresssliderId", Mojo.Event.propertyChange, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.propertyChange {value: pos}
Mojo.Event.progressComplete Progress is complete
Instantiation
this.controller.setupWidget("progresssliderId",
this.attributes = {
property: 'value',
round: true,
maximumValue: 100,
mininumValue: 0
},
this.model = {
value: 20
}
);
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
sliderProperty String Optional "slider" Name of model property for this widget instance for the slider position
progressProperty String Optional "progress" Name of model property for this widget instance for the progress bar position
progressStartProperty Integer Optional Null Starting position of the progress bar
minValue Integer Required Minimum slider value returned at leftmost position
maxValue Integer Required Maximum slider value returned at leftmost position
round Boolean Required Round the value returned to the nearest integer
cancellable Boolean Required If true, progress cancel option is shown
updateInterval Integer Optional 0 if >0, will send updates every updateInterval seconds
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value Integer Required Null Current value of widget; this will be sanitized to be between minValue and maxValue
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
reset Reset the progress to 0
Overview
If you need to a single widget to switch between multiple states while revealing all the state options on the screen, then a RadioButton may fit your needs. Mojo provides a classic RadioButton which presents each button as a labeled selection option in a horizontal array, where only one option can be selected at at time. The number of options is variable, constrained only by the width of the display and the minimum button size that can be pleasingly presented or selected. You can expect to handle between 2 and 5 states given the typical screen size for a webOS device, but the framework won't limit you.
Declaration
<div x-mojo-element="RadioButton" id="radiobuttonId" class="radiobuttonClass" name="radiobuttonName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required RadioButton Declares the widget as type 'RadioButton'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String RadioButton uses the .palm-radiobutton-container by default but you override this setting
name Optional Any String Add a unique name to the radiobutton widget; generally used in templates when used
Events
Mojo.Event.listen("radiobuttonId", Mojo.Event.propertyChange, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.propertyChange { property: this.valueName,
value: this.choices[clicked._mojoListIndex].value,
model: this.controller.model
}
Instantiation
this.controller.setupWidget("myRadioBtn",
this.attributes = {
choices: [
{label: "One", value: 1},
{label: "Two", value: 2},
],
this.model = {
value: 1,
disabled: false
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
modelProperty String Optional value Model property name for radiobutton state
disabledProperty String Optional disabled Model property name for disabled boolean
choices Array Required null Array of button descriptions, each of which is a {label: 'string', value: value} entry;
number of entries defines scope of widget
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value User-defined Required none value of widget
disabled Boolean Optional false If true, radiobutton is inactive
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
None
Overview
There is a simple Rich Text Edit widget that behaves exactly like a multiline text field, but in addition supports applying Bold, Italic and Underline styles to arbitrary runs of text within the field. You declare a x-mojo-element="RichTextEdit" DIV in your scene and set it up in your assistant without attributes or a model.
To enable the styling, set the richTextEditMenu property to true in the AppMenu attributes (see Menus for more information on the App Menu).
Declaration
<div x-mojo-element="RichTextEdit" id="richTextEditId" class="message-rte" name="richTextEdit"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required RichTextEdit Declares the widget as type 'RichTextEdit'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String Provide your own unique class and override the frameworks styles
name Optional Any String Add a unique name to the richtextedit widget; generally used in templates when used
Events
this.controller.listen("richtexteditId", 'blur', this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Instantiation
this.controller.setupWidget("richtexteditId",
this.attributes = {
},
this.model = {
value: ""
});
Get Content
To obtain the content of the RichTextEdit field, call:
this.controller.get('richtexteditId').innerHTML
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
Overview
The scroller widget provides all scrolling behavior. One is installed automatically in every scene (you can disable this behavior by having a truthy value in the disableSceneScroller property in the scene arguments to pushScene and you can have any number of additional scrollers anywhere in the DOM.
You can select one of six scrolling modes currently, specified in the mode property of the widget's attributes:
- free: allow scrolling along the x and y axis.
- horizontal: allow scrolling only along the horizontal axis.
- vertical: allow scrolling only along the vertical axis.
- dominant: allow scrolling along the horizontal or vertical axis, but not both at once. The direction of the intial drag will determine the axis of scrolling.
- horizontal-snap: In this mode, scrolling is locked to the horizontal axis, but snaps to points determined by the position of the block elements found in the model's snapElements property. As the scroller scrolls from snap point to snap point it will send a propertyChange event.
- vertical-snap: similarly, this mode locks scrolling to the vertical axis, but snaps to points determined by the elements in the snapElements property array
The Scroller declaration MUST wrap the scrolled contents within it's scope.
Declaration
<div x-mojo-element="Scroller" id="scrollerId" class="scrollerClass" name="scrollerName">
<div> TARGET SCROLL CONTENT </div>
</div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required Scroller Declares the widget as type 'Scroller'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String Scroller uses the .palm-scroller-container by default but you override this setting
name Optional Any String Add a unique name to the scroller widget; generally used in templates when used
Events
this.controller.listen("scrollerId", 'Mojo.Event.propertyChange', this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.propertyChange None Respond to Scroller value change
Mojo.Event.scrollStarting None When contained in a scroller, down action followed by movement generates a scroll-starting event
Instantiation
this.controller.setupWidget("scrollerId",
this.attributes = {
mode: 'vertical
},
this.model = {
snapElements: {x: [DOMElement, DOMElement, DOMElement, ...]}
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
mode String Required value Scrolling mode; either: free, vertical, horizontal, dominant, vertical-snap, horizontal-snap
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
snapElements Object Optional none Object containing array of DOM elements used as snap points for horizontal or vertical scrolling
under the appropriate component. i.e {y: [DOMElement, DOMElement, DOMElement, ...]}
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
revealTop Object Jump the scroll to reveal the top of the content being scrolled.
revealBottom Jump the scroll to reveal the bottom of the content being scrolled
revealElement HTML Element Jump the scroll to reveal a specific element, only scrolls vertically
scrollTo Integer {x-coord}, Integer {x-coord}, Jump the scroll to the x,y coordinates specified. If either of the coordinates are undefined, they are ignored
Boolean {animate}, Boolean {supress notifications}
getState Returns the current scroll state for use in a future call to setState.
setState Object {scrollState},Boolean {animate} Jumps the scroll to the value specified in scrollState; pass true to animate the scrollJumps the scroll to the
value specified in scrollState
adjustBy Integer {deltaX}, Integer {deltaY} Adjust the current scroll position by the given amount. Safe to call from scroll listeners while animating.
Does not cause listeners to be notified of any changes.
scrollerSize Returns the size of the scroller's view port in pixels: {height:nnn, width:nnn}
setMode String {newMode} Set the mode of the scroller, which controls which drag directions causes scrolling. Choices are 'free',
'dominant', 'horizontal', 'horizontal-snap', and 'vertical'.
getScrollPosition Get the current position of the scroller. Returns {left: nnn px, top: nnn px}
setSnapIndex Number{snapIndex}, Boolean {animate} Sets the snap index for a snap scroller and scrolls to the new position; pass true to animate.
Overview
The Slider presents a range of selection options in the form of a horizontal slider with a control knob that can be tapped and dragged to the desired location. You must specify minimum (left-most) and maximum (right-most) values for the slider and you can optionally indicate intermediate choices which will trigger additional behavior.
Declaration
<div x-mojo-element="Slider" id="sliderId" class="sliderClass" name="sliderName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required Slider Declares the widget as type 'Slider'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String Slider uses the .palm-slider-container by default but you override this setting
name Optional Any String Add a unique name to the slider widget; generally used in templates when used
Events
Mojo.Event.listen("sliderId", Mojo.Event.propertyChange, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.propertyChange {value: pos}
Instantiation
this.controller.setupWidget("listselectorId",
this.attributes = {
minValue: 0,
maxValue: 100
},
this.model = {
value: 3,
disabled: false
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
modelProperty String Optional value Model property name for slider state
minValue Integer Required Starting value, or leftmost value on slider
maxValue Integer Required Ending value, or rightmost value on slider
round Boolean Optional FALSE If true, will round the slider value to the nearest integer
if 1, will be used for starting value
updateInterval Integer Optional 0 if >0, will send updates every updateInterval seconds
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value Integer Required none value of widget; this will be sanitized to be between minValue and maxValue
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
None
Overview
The spinner widget provides all scrolling behavior. One is installed automatically in every scene (you can disable this behavior by having a truthy value in the disableSceneSpinner property in the scene arguments to pushScene and you can have any number of additional spinners anywhere in the DOM.
If you just need show that activity is taking place, use the Spinner. The framework uses it as part of the activity button type, and you'll see it in many of the core applications. There are two sizes, the large Spinner is 128 pixels wide (and high) and the small Spinner is 32 pixels. These metrics are for the Pre screen and may vary on other devices but the proportions and fit within the UI will be maintained. All attribute properties are optional, but the spinnerSize is commonly used; set it to "large", the default, or "small". To start the Spinner, set its model property (default name is 'spinning') to true; to stop it, set the property to false.
Declaration
<div x-mojo-element="Spinner" id="spinnerId" class="spinnerClass" name="spinnerName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required Spinner Declares the widget as type 'Spinner'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String Spinner uses the .palm-spinner-container by default but you override this setting
name Optional Any String Add a unique name to the spinner widget; generally used in templates when used
Events
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
None
Instantiation
this.controller.setupWidget("spinnerId",
this.attributes = {
spinnerSize: 'large'
},
this.model = {
spinning: false
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
property String Optional spinning DEPRECATED Name of model property for this widget instance
modelProperty String Optional spinning Name of model property for this widget instance; default is "spinning"
spinnerSize String Optional Mojo.Widget.spinnerSmall Either Mojo.Widget.spinnerLarge or Mojo.Widget.spinnerSmall (small=32 or large=128)
superClass String Optional .palm-activity-indicator Specifies the CSS class name for the background image when you specify a custom
startFrameCount Integer Optional None if the spinner widget is in custom mode, this specifies the number of frames
allocated to the pre-main loop animation
mainFrameCount Integer Optional 10 if the spinner widget is in custom mode, this specifies the number of frames
allocated to the main loop animation
finalFrameCount Integer Optional None if the spinner widget is in custom mode, this specifies the number of frames
allocated to the post-main loop animation
frameHeight Integer Optional small Explicitly sets the frame height of the animation (small=32 or large=128)
fps Integer Optional 10 Number of frames per second
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
spinning Boolean Required false Spinner state, true is spinning
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
start None Start the spinner
stop None Stop the spinner
toggle None Change the spinner (spinning to not, stopped to spinning)
Overview
This is a widget that extends the functionality of an input type = text HTML element with hint text and text correction behavior. The field defaults to a single line, scrolling text field with fixed horizontal and vertical dimensions, that will submit the text, meaning generate a Mojo.Event.propertyChange event, when it loses focus. The contents of the field will be passed to your event handler in both event.value and the widget's model.value.
Declaration
<div x-mojo-element="TextField" id="listId" class="listClass" name="listName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required TextField Declares the widget as type 'TextField'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String Provide your own unique class and override the frameworks styles
name Optional Any String Add a unique name to the textfield widget; generally used in templates when used
Events
Mojo.Event.listen("textfieldId", Mojo.Event.propertyChange, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.propertyChange {model:model, property:property, value:value, oldValue: oldValue, originalEvent: originalEvent}
Instantiation
this.controller.setupWidget("textfieldId",
this.attributes = {
hintText: $L(' ... and hit Enter'),
multiline: false,
enterSubmits: false,
focus: true
},
this.model = {
value: "",
disabled: false
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
modelProperty String Optional value Model property name for selector value
disabledProperty String Optional disabled Model property name for disabled boolean
hintText String Optional None Initially displayed string; supplanted by model value if supplied
textFieldName String Optional None DEPRECATED If supplied, the textarea will have this name, so that when it is serialized,
the property can be easily pulled out
inputName String Optional None If supplied, the textarea will have this name, so that when it is serialized, the property can be easily pulled out
multiline Boolean Optional FALSE Auto line wrapping to field width
charsAllow Function Optional None Function must return 'true' to allow input character, or 'false' if not allowed;
note: this event is sent as a result
of a keyPress event, so you must check against key codes matching ASCII characters.
focus Boolean Optional FALSE DEPRECATED If true, field has focus on scene push
autoFocus Boolean Optional FALSE If true, field has focus on scene push
modifierState String Optional None "initial state of modifier keys for this field. Can be:
Mojo.Widget.numLock,
Mojo.Widget.capsLock"
autoResize Boolean Optional FALSE DEPRECATED Automatically grow field horizontally
growWidth Boolean Optional FALSE Automatically grow field horizontally
autoResizeMax Integer Optional None Maximum width of field
enterSubmits Boolean Optional FALSE When used in conjunction with multline, if this is set, then enter will submit rather than newline
limitResize Boolean Optional FALSE Limit height resize (scrolls text rather than grow field)
preventResize Boolean Optional FALSE There will be no resizing in any dimension
holdToEnable Boolean Optional FALSE if the textfield is disabled, tapping and holding and releasing will enable it;
if disabled is not set, this is ignored
focusMode String Optional Insert Mode "Replace or Insert Mode; choices:
Mojo.Widget.focusSelectMode
Mojo.Widget.focusInsertMode
Mojo.Widget.focusAppendMode
Text will either all be selected (Select), or a cursor will
appear where the user tapped (Insert) or cursor goes to end of text (Append)
changeOnKeyPress Boolean Optional FALSE If true, sends a propertyChange event on every character change to a field;
otherwise only when focus lost
textReplacement Boolean Optional TRUE DEPRECATED Whether to enable the SmartTextEngine services of PalmSysMgr. Enabled by default in the TextField.
maxLength Integer Optional No Limit Maximum character length of field; does not apply to multiline fields where an exception will be thrown.
requiresEnterKey Boolean Optional FALSE Required Enter key to submit; other navigation will not genterate submit event
holdToEdit Boolean Optional FALSE Tap and Hold to focus/edit; Tap only will be ignored
autoCapitalization Boolean Optional FALSE DEPRECATED The first letter of each word (determined by whitespace) is capitalized.
emoticons Boolean Optional FALSE Enable emoticons on this field
autoReplace Boolean Optional True Whether to enable the SmartTextEngine services of PalmSysMgr. Enabled by default in the TextField.
textCase String Optional Mojo.Widget.steModeSentenceCase Use this to change the autocapitzliation on the TextField. Options are:
Mojo.Widget.steModeSentenceCase (capitalization like a sentence),
Mojo.Widget.steModeTitleCase (capitalize first letter of each word),
Mojo.Widget.steModeLowerCase (no capitalization)
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value String Required Null Initial and updated value of widget
disabled Boolean Optional false If true, toggle is inactive
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
focus none Focus the input part of the text field
blur none Blur the input part of the text field
getValue none Get the plaintext value of the text field
setText String DEPRECATED Set the plaintext value of the text field; also used by alt char picker to set the value
setValue String Set the plaintext value of the text field
getCursorPosition none Returns on object with {selectionStart: int, selectionEnd: int} that describe the position of the cursor; if start is not
equal to end, then there is text selected
setCursorPosition start, end Set the cursor position in the input portion of the textfield; if start and end are not the same, then this
will select the text between START and END; if start and/ or end occur in invalid positions, they will be changed
to valid positions at the end of the text if they were larger than the size of the value, or at the beginning, if they
are smaller than the size of the value; empty text will result in a cursor at the start of the textfield
Set x-mojo-focus-highlight=true on any parent div to have the focus class applied to it as well when the TextField widget becomes focused
Overview
The TimePicker offers selection of the hour and minutes with an AM/PM selector when appropriate. It is one of the simple picker widgets which present their choices as a linear sequence of values that wraps around; when you scroll to the end of the sequence, it simply continues back at the beginning. The Date and Time pickers use the JavaScript Date object to represent the chosen time in their data model.
Declaration
<div x-mojo-element="TimePicker" id="timepickerId" class="timepickerClass" name="timepickerName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required TimePicker Declares the widget as type 'TimePicker'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String There isn't a default class for TimePicker but you can assign one if you want apply custom styling
name Optional Any String Add a unique name to the timepicker widget; generally used in templates when used
Events
this.controller.listen("timepickerId",'mojo-propetyChange', this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
mojo-propertyChange event.value or model.time Respond to TimePicker value change
Instantiation
var currentTIme = new Date();
this.controller.setupWidget("timepickerId",
this.attributes = {
label: 'Time',
modelProperty: 'time'
},
this.model = {
time: currentTime
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
label String Optional 'Time' Label displayed for the widget controls
labelPlacement String Optional Mojo.Widget.labelPlacementLeft Mojo.Widget.labelPlacementRight : places label on right, value on left.
Mojo.Widget.labelPlacementLeft : places label on left, value on right
modelProperty String Optional time Model property name for date object
minuteInterval Integer Optional 5 Interval between minute selection options
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
time Date Object Required null Date object to set initial widget value and updated value after user selection
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
None
Overview
As with the CheckBox and similar to the RadioButton, the ToggleButton is a widget for displaying and controlling a binary state value. Mojo's ToggleButton will be switch between two states each time it is tapped. Declaration
Declaration
<div x-mojo-element="ToggleButton" id="togglebuttonId" class="togglebuttonClass" name="togglebuttonName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required ToggleButton Declares the widget as type 'ToggleButton'
id Required Any String Identifies the widget element for use when instantiating or rendering
Events
Mojo.Event.listen("togglebuttonId", Mojo.Event.propertyChange, this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.propertyChange model:model attached to the widget, property: model property, value: value of the checkbox
Instantiation
this.controller.setupWidget("togglebuttonId",
this.attributes = {
trueValue: 'On',
falseValue: 'Off'
},
this.model = {
value: false,
disabled: false
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
modelProperty String Optional value Model property name for togglebutton state
disabledProperty String Optional disabled Model property name for disabled boolean
trueValue String Optional true Value to set model property when true
trueLabel String Optional 'On' Label when toggle is true
falseValue String Optional false Value to set model property when false
falseLabel String Optional 'Off' Label when toggle is false
fieldName String Optional DEPRECATED Idenitifer for the value of the toggle button; used when the toggle button is used in html forms
inputName String Optional Idenitifer for the value of the toggle button; used when the toggle button is used in html forms
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
value User-defined Required none Current value of widget
disabled Boolean Optional FALSE If true, togglebutton is inactive
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
None
Overview
To embed a contained web object, you would declare and instantiate a webView widget. You can bound the widget within your declaration to get a scrolling view, or allow it to take over an entire scene at your discretion. You can use it render local markup or to load an external URL; as long as you can define the source as a URL it can be applied.
Declaration
<div x-mojo-element="WebView" id="WebId" class="WebClass" name="WebName"></div>
Properties Required Value Description
---------------------------------------------------------------------------------------------------------------------------------
x-mojo-element Required WebView Declares the widget as type 'WebView'
id Required Any String Identifies the widget element for use when instantiating or rendering
class Optional Any String Provide your own unique class and override the frameworks styles
name Optional Any String Add a unique name to the WebView widget; generally used in templates when used
Events
Mojo.Event.listen("WebId",'mojo-webViewLoadProgress', this.handleUpdate)
Event Type Value Event Handling
---------------------------------------------------------------------------------------------------------------------------------
Mojo.Event.webViewLoadStarted indicates the WebView widget has started loading the content
Mojo.Event.webViewLoadProgress progress indicates that some progress has been made in loading content and returns the amount in
progress. Note: this will show 100% even in the case of a failed page load.
Mojo.Event.webViewLoadStopped indicates the page has finished loading; note: "finished loading" is a tricky concept in
AJAX web pages, so be careful how you use this event
Mojo.Event.webViewLoadFailed errorCode, message indicates the content failed to load and supplies an error code (errorCode) and
localized message (message)
Mojo.Event.webViewDownloadFinished url, mimeType, tmpFilePath File download completed
Mojo.Event.webViewLinkClicked url The user tapped a link
Mojo.Event.webViewTitleUrlChanged title, url, canGoBack, canGoForward
Mojo.Event.webViewTitleChanged title
Mojo.Event.webViewUrlChanged url, canGoBack, canGoForward
Mojo.Event.webViewCreatePage pageIdentifier
Mojo.Event.webViewTapRejected
Mojo.Event.webViewScrollAndScaleChanged
Mojo.Event.webViewEditorFocused focused
Mojo.Event.webViewUpdateHistory url, reload
Mojo.Event.webViewSetMainDocumentError domain, errorCode, failingURL, message
Mojo.Event.webViewServerConnect
Mojo.Event.webViewServerDisconnect
Mojo.Event.webViewResourceHandoff
Mojo.Event.webViewFirstPaintComplete
Mojo.Event.webViewUrlRedirect url, appId
Mojo.Event.webViewModifierTap up, linkInfo
Mojo.Event.webViewMimeNotSupported url, mimeType indicates the BrowserServer cannot handle a given URL
Mojo.Event.webViewMimeHandoff url, mimeType indicates the BrowserServer cannot (or isn't supposed to) handle a mime type.
Instantiation
this.controller.setupWidget("WebId",
this.attributes = {
url: 'http://www.palm.com',
minFontSize:18,
virtualpagewidth: 20,
virtualpageheight: 10
},
this.model = {
}
});
Attribute Properties
Attribute Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
virtualpageheight Integer Optional ? The browser's virtual page height.
virtualpagewidth Integer Optional ? The browser's virtual page width.
urL String Required None The initial URL to display.
pageIdentifier String Optional ? The BrowserServer page identifier. This is used when the BrowserServer
instructs an application to open a new page.
minFontSize Integer Optional ? The minimum font size that the browser will display.
topMargin Integer Optional ? The margin above the web view that is scrolled off the screen when a new page is loaded.
cacheAdapter Boolean Optional undefined If true, cache this adapter, false if not, or undefined to not specify and use the
browser-adapter default. Default is undefined.
interrogateClicks Boolean Optional true If the host application wants to be called for every hyperlink click via
Mojo.Event.webViewLinkClicked event
showClickedLink Boolean Optional true Styles clicked link with grey background and border.
Model Properties
Model Property Type Required Default Description
---------------------------------------------------------------------------------------------------------------------------------
None
Methods
Method Arguments Description
---------------------------------------------------------------------------------------------------------------------------------
setTopMargin Integer Set the top margin (in pixels)
clearCache None Clear browser cache. Will clear the cache for all open pages.
clearCookies None Clear browser cookies. Will clear cookies for all open pages.
deleteImage String {fname} Delete the image file specified by the argument.
generateIconFromFile String {inFilName}, String {outFileName}, Generate a 64x64 pixel icon from a portion of an input file.
Number {left}, Number {top}, The output icon will be given a drop shadow and sheen
Number {right}, Number {bottom} consistent with other launcher icons.
goBack None Go to the previous page in the user's browing history.
goForward None Go to the next page in the user's browsing history.
openURL String Navigate to the specified url in the webview
reloadPage None Reload the currently loaded page
resizeImage String {inFileName}, String {outFileName}, Resize the input file to the specified width/height and
Number {width}, Number {height} write the new image to the specified output file.
getHistoryState Function {successCb} Retrieve the current history state from the Browser server.
Will call successCb with results.
isEditing Function {callback} Determines if an editable field is in focus
Will call "callback" with boolean value
insertStringAtCursor String {string} Inserts given string at cursor position of editable field in focus
setBlockPopups Boolean Enable or disable popup blocking. This setting is on a
per-WebView widget basis.
setAcceptCookies Boolean Enable or disable accepting cookies. This setting is on a
per-WebView widget basis.
addUrlRedirect String {urlRe}, Boolean {redirect}, Add a URL redirect. When the browser server nagivates to a URL
Object {userData}, Number {type} matching urlRe and redirect is true then it will not navigate
to that URL and instead send a Mojo.Event.webViewUrlRedirect event.
addSystemRedirects String {appId} Add all entries from the system's command/resource handlers table
The optional appId parameter can be used to omit all
command/resource handler entries that match a given app ID.
saveViewToFile String {fname}, Number {left}, Number {top} Save the current view to the specified file. The save region
Number {width}, Number {height} is optional. If omitted then the full view will be saved to fname.
setEnableJavaScript Boolean Enable or disable javascript This setting is on a
per-WebView widget basis.
stopLoad None Stop loading the current page
focus None Focus the webview widget
blur None Blur the webview widget
clearHistory None Clear session history. This setting is on a
per-WebView widget basis.
setShowClickedLink Boolean Enhance the showing of a clicked link. This setting is on a
per-WebView widget basis.
copy Function {callback}
selectAll None