Quick Reference—Developer Guide - Palm webOS

by Mitch Allen

Throughout the book, you’ve seen sample code and examples of widgets and services. In this section, those interfaces are compiled in reference form to help you as you are coding or if you just want to look something up.

Palm webOS book cover

This excerpt is from Palm webOS. This is the official guide to building native JavaScript applications for Palm's new mobile operating system, Palm® webOS™. Written by Palm's software chief technology officer along with the Palm webOS development team, Palm webOS offers you a complete tutorial on the design principles, architecture, UI, tools, and services necessary to develop webOS applications. If you're familiar with HTML, CSS, and Javascript, you're ready to build applications for webOS-based devices, including the Palm Pre.

buy button

This is not a comprehensive list of all Mojo APIs; for that you should refer to the SDK site. There you will find the APIs mentioned in this book, including:

  • Widgets

  • Dialogs

  • Menus

  • Storage

  • Services

  • Controller APIs

Widgets

This section includes all of the Mojo widgets. Each widget section includes a brief description repeating some of the information from Chapters 3, 4, and 5, followed by an enumeration of the widget’s attribute and model properties, relevant events, and public methods.

Button

Buttons are the most basic UI element, bounding an action to a region. When a button is pushed, it can change state but gracefully returns to the previous state, like a doorbell.

Attribute properties

Type

Description

type

String

Choices:

Mojo.Widget.defaultButton
Mojo.Widget.activityButton
disabledProperty

Boolean

Name of model property for disabled state

label

String

Displayed label

labelProperty

String

Model property name for label

Model properties

Type

Description

buttonClass
StringStyle options are primary, secondary, dismissal, affirmative, or negative
label

String

Displayed label

disabled

Boolean

Default property that when true, disables the widget

Events

Mojo.Event.tap

Methods

activate()

For an activity button, start the spinner

deactivate()

For an activity button, stop the spinner

Check Box

A Check Box widget is used to control and indicate a binary state value in one element.

Attribute properties

Type

Description

modelProperty

String

Name of model property for widget state

disabledProperty

String

Name of model property for disabled state

trueValue

String

Value to set modelProperty when widget state is true

falseValue

String

Value to set modelProperty when widget state is false

inputName

String

Identifier for the value of the check box; used when the widget is used in HTML forms

Model properties

Type

Description

value

Boolean

Current value of widget

disabled

Boolean

Default property that when true, disables the widget

Events

Mojo.Event.propertyChange

Date Picker

The date picker allows selection of month, day, and year values.

Attribute properties

Type

Description

label

String

Label displayed with the widget controls

labelPlacement

String

Choices are:

Mojo.Widget.labelPlacementLeft
Mojo.Widget.labelPlacementRight
modelProperty

String

Name of model property for date object; defaults to 'date'

month

Boolean

Set to true to display the month field in the widget

day

Boolean

Set to true to display the day field in the widget

year

Boolean

Set to true to display the year field in the widget

maxYear
IntegerSpecify maximum year in year capsule if enabled (default 2099)
minYear
IntegerSpecify minimum year in year capsule if enabled (default 1900)

Model properties

Type

Description

date

Date

Date object set to the widget value

Events

None

Drawer

Drawers are container widgets that can be open, allowing child content to be displayed normally, or closed, keeping it out of view.

Attribute properties

Type

Description

unstyled

Boolean

When set to true, prevents styles from being added, allowing the Drawer to be used just for open/close function

modelProperty

String

Name of model property for date object

Model properties

Type

Description

open

Boolean

Current state of the widget; set to true when open

Events

Mojo.Event.propertyChange

Methods

setOpenState(open)

Sets the open state to open or closed

getOpenState()

Returns current value of open state

toggleState()

Change the drawer’s open state to the opposite of what it is now

File Picker

Mojo.FilePicker.pickFile (params, stageController)

The File Picker presents a file browser that lets the user navigate the directory structure and optionally select a file. The File Picker lets users view and select files from the media partition, and allows filtering by file type (e.g., file, image, audio, or video).

Arguments

Type

Description

params

Object

Object containing information about the file to select as described below:

  onSelect

Function

Function to call after selection is made; it will return an object of the following format:

{ fullPath: /full/path/of/selected/file' }
  onCancel

Function

Function to call after selection is made; when picker is canceled.

  kinds

Array

Array of strings to allow (image, audio, video, file); default is support for all kinds; if only one kind is needed, kind: mytype can be used and override kinds

  defaultKind

String

String; the view to go to; one of image, audio, video or file

  actionType

String

attach and open are the only supported options; open is the default

  actionName

String

Overrides the default string defined by actionType

  extensions

Array

File extensions to filter in the files view

stageController

Object

The calling application’s stage assistant

Events

None

Filter Field

The Filter Field can be applied to any case where you want to process the field contents and update on-screen elements based on the entered string.

Attribute properties

Type

Description

delay

Integer

Delay between key strokes for a filter event, in milliseconds

disabledProperty

String

Name of model property for disabled state

Model properties

Type

Description

disabled

Boolean

Default property that, when true, disables the widget

Events

Mojo.Event.filter

Methods

open()

Open the widget

close()

Close the widget

setCount(integer)

Set the number to be shown in the results bubble in the Filter Field

Filter List

The Filter List combines a Filter Field and a List. It is intended to display a variable length list of objects, built by a special callback function that filters the list based on the contents of the filter field.

Attribute properties

Type

Description

delay

Integer

Delay between key strokes for a filter event, in milliseconds

filterFunction

Function

Function called to load items into the list as it is scrolled or filter changes; function definition is:

filterFunction(filterString, listWidget,
    offset, count)

where:

filterString: set to the input string

listWidget: this Filter Listwidget object

offset: index of first displayed entry in listfs

count; number of entries required from the function

listTemplate

String

File path relative to app folder for container template

itemTemplate

String

File path relative to app folder for item template

addItemLabel

String

If defined, a special “add” item will be appended to the list and taps on this will generate a Mojo.Event.listTap

formatters

Function

Object functions to format list entries based on model properties

itemsProperty

String

Model property for items list

swipeToDelete

Boolean

If true, list entries can be deleted with a swipe

autoconfirmDelete

String

If false, delete swipes will post a delete/undo button pair, otherwise deletes will be made immediately after swiping

uniquenessProperty
StringName 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
preventDeleteProperty

String

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 true

reorderable

Boolean

If true, list entries can be reordered by drag and drop

dividerFunction

Function

Function to create divider elements

dividerTemplate

Function

Function to format divider

fixedHeightItems

Boolean

If false, list widget will not apply optimizations for fixed height lists

initialAverageRowHeight

Integer

Initial value used for average height estimation

renderLimit

Integer

Max number of items to render at once; increase this if the UI overruns the list boundaries

lookahead

Integer

Number of items to fetch ahead when loading new items

dragDatatype

String

Used for drag-and-drop reordering; if specified, will enable dragging of items from one list to another of the same data type

deletedProperty

String

Name of the item object property in which to store the deleted status of an item

nullItemTemplate

String

File path relative to app folder for template for items that are rendered before loading

emptyTemplate

String

File path relative to application folder for template for empty list

onItemRendered

Function

Called each time an item is rendered into the DOM with these arguments

Model properties

Type

Description

disabled

Boolean

Default property that, when true, disables the widget

Events

Mojo.Event.listChange
Mojo.Event.listTap
Mojo.Event.listAdd
Mojo.Event.listDelete
Mojo.Event.listReorder
Mojo.Event.filter

Methods

getList()

Get the List widget associated with this filter list

open()

Open the filter field associated with this filter list

close()

Close the filter field associated with this filter list

setCount(integer)

Set the number to be shown in the results bubble in the filter field

Image View

You can use an ImageView for displaying single images, but it is intended as a scrolling viewer, flicking left and right through a series of images.

Attribute properties

Type

Description

highResolutionLoad

Integer

Time to wait before switching photo to high res

noExtractFS

Boolean

Flag to prevent looking up a high res version

fslimitZoom

Boolean

Flag to prevent or limit zooming

Model properties

Type

Description

onLeftFunction

Function

Called after a left scroll and transition

onRightFunction

Function

Called after a right scroll and transition

Events

Mojo.Event.imageViewChanged

Methods

getCurrentParams()

Return the current zoom level and focus [0,1]

manualSize(width, height)

Manually size the widget

leftUrlProvided(url)

Set the image for the left scroll

rightUrlProvided(url)

Set the image for the right scroll

centerUrlProvided(url)

Set the image for the center

Integer Picker

The Integer Picker offers a selection between minimum and maximum integer values, both of which are specified as properties.

Attribute properties

Type

Description

label

String

Label displayed with the widget controls

labelPlacement

String

Choices are:

Mojo.Widget.labelPlacementLeft
Mojo.Widget.labelPlacementRight
modelProperty

String

Name of model property for integer value; defaults to 'value'

min

Integer

Minimum value of the widget

max

Integer

Maximum value of the widget

padNumbers

Boolean

Add padding to single digit numbers or not

Model properties

Type

Description

value

Integer

Current value of the widget

Events

Mojo.Event.propertyChange

List

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.

Attribute properties

Type

Description

listTemplate

String

File path relative to app folder for container template

itemTemplate

String

File path relative to app folder for item template

addItemLabel

String

If defined, a special “add” item will be appended to the list and taps on this will generate a Mojo.Event.listTap

formatters

Function

Object functions to format list entries based on model properties

itemsProperty

String

Model property for items list

itemsCallback

Function

Items will be loaded as needed by calling this function

swipeToDelete

Boolean

If true, list entries can be deleted with a swipe

autoconfirmDelete

String

If false, delete swipes will post a delete/undo button pair, otherwise deletes will be made immediately after swiping

uniquenessProperty
StringName 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
preventDeleteProperty

String

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 true

reorderable

Boolean

If true, list entries can be reordered by drag and drop

dividerFunction

Function

Function to create divider elements

dividerTemplate

Function

Function to format divider

fixedHeightItems

Boolean

If false, list widget will not apply optimizations for fixed height lists

initialAverageRowHeight

Integer

Initial value used for average height estimation

renderLimit

Integer

Max number of items to render at once; increase this if the UI overruns the list boundaries

lookahead

Integer

Number of items to fetch ahead when loading new items

dragDatatype

String

Used for drag-and-drop reordering; if specified, will enable dragging of items from one list to another of the same data type

deletedProperty

String

Name of the item object property in which to store the deleted status of an item

nullItemTemplate

String

File path relative to app folder for template for items that are rendered before loading

emptyTemplate

String

File path relative to application folder for template for empty list

onItemRendered

Function

Called each time an item is rendered into the DOM with these arguments

Model properties

Type

Description

items

Array

An array of objects to display in the list; required unless itemsCallback property is set as an attributes property

Events

Mojo.Event.listChange
Mojo.Event.listTap
Mojo.Event.listAdd
Mojo.Event.listDelete
Mojo.Event.listReorder

Methods

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(enable)

Show the “add item” in the list

noticeUpdatedItems(offset, items)

Causes the given items to be replaced and rerendered; items provided past the current end of the list will cause the length to grow; must pass an array

noticeAddedItems(offset, items)

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, items)

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 and limit properties indicating the range of currently loaded item models (or items that 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

setInitialSize(length)

Call to set the initial size of the list, or after resetting the list state by calling modelChanged(); this function will set the limit on what range of items may be requested, but subsequent changes to the list size should be made through noticeAddedItems() and fsnoticeRemovedItems(); this 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 range of items that 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

getLength()

Returns the current length of the list

revealItem(index, animate)

Attempts to scroll the scene to reveal the item with the given index; may behave poorly when working with variable height list items that are not currently loaded, since you 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; otherwise, returns undefined

List Selector

The List Selector enables the selection of one of many options, presented in a pop-up list in which there is no practical limit to the number of options presented. This is similar to the Submenu widget behavior.

Attribute properties

Type

Description

modelProperty

String

Name of model property for widget state

disabledProperty

String

Name of model property for disabled state

multi-line

Boolean

If true, long labels will wrap to the next line instead of being truncated

label

String

Display label

labelPlacement

String

Mojo.Widget.labelPlacementRight places label on right, value on left (default);

Mojo.Widget.labelPlacementLeft places label on left, value on right

choices

Array

Array of selector descriptions, which must be in either the attributes or model object; each entry is required to be:

{label: 'string', value: value}

There must be at least two entries, and the number of entries defines the number of options presented in the widget

Model properties

Type

Description

value

Boolean

Current value of widget

disabled

Boolean

Default property that, when true, disables the widget

choices

Array

Array of selector descriptions, which must be in either the attributes or model object; each entry is required to be:

{label: 'string', value: value}

There must be at least two entries, and the number of entries defines the number of options presented in the widget

Events

Mojo.Event.propertyChange

Password Field

A text field 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.

Attribute properties

Type

Description

modelProperty

Boolean

Name of model property for widget value

hintText

String

Initially displayed string; supplanted by model value if supplied

inputName

String

If supplied, the text area will have this DOM name so that when it is serialized, the property can be easily pulled out

charsAllow

Function

Function must return true to allow input character, or false if not allowed

autoFocus

Boolean

If true, field has focus on scene push

modifierState

String

Initial state of modifier keys for this field; can be: Mojo.Widget.numLock or Mojo.Widget.capsLock

growWidth

Boolean

Automatically grow field horizontally

autoResizeMax

String

Maximum width of field

enterSubmits

Boolean

If set, the Enter key will submit rather than newline; must be used with multi-line

limitResize

Boolean

Limit height resize (scrolls text rather than grow field)

preventResize

Boolean

There will be no resizing in any dimension

holdToEnable

Boolean

If the text field is disabled, tapping and holding and releasing will enable it; if disabled is not set, this is ignored

focusMode

String

Replace or Insert Mode; choices are:

Mojo.Widget.focusSelectMode
Mojo.Widget.focusInsertMode
Mojo.Widget.focusAppendMode
changeOnKeyPress

Boolean

If true, sends a property change event on every character change to a field; otherwise only when field loses focus

maxLength

Integer

Maximum character length of field; does not apply to multi-line fields, where it will be ignored

requiresEnterKey

Boolean

Required Enter key to submit; other navigation will not submit contents of field

holdToEdit

Boolean

Tap and hold to focus/edit; tap only will be ignored

Model properties

Type

Description

value

Boolean

Plain-text value of the widget

Events

Mojo.Event.propertyChange

Methods

focus()

Put focus on the input field

blur()

Remove focus from the input field

getValue()

Get the plaintext value of the widget

setValue()

Set the plaintext value of the widget

getCursorPosition()

Returns an option with:

{selectionStart: int, selectionEnd: int}

that describe the position of the cursor; if start is not equal to end, there is text selected

setCursorPosition(start, end)

Sets the cursor position in the input portion of the text field

Progress Bar

Progress Bar displays a narrow horizontal bar with an incremental internal bar to show progress. Use a Progress Bar or Pill to show download progress, when loading from a database, or anytime you initiate a long-running operation and have a sense of the duration.

Attribute properties

Type

Description

modelProperty

String

Name of model property for widget value

icon

String

CSS class for icon to display on the bar

iconPath

String

File path relative to application folder for icon

Model properties

Type

Description

value

Integer

Value of the widget

title

String

Dynamic title to show on bar

image

String

File path relative to application folder for dynamic image to show on bar

Events

Mojo.Event.progressComplete

Methods

reset()

Reset progress to 0

cancelProgress()

Stop the progress and freeze bar display in current state

Progress Pill

Progress Pill displays a broad horizontal bar with an incremental pill to show progress. Use a Progress Bar or Pill to show download progress, when loading from a database, or anytime you initiate a long-running operation and have a sense of the duration.

Attribute properties

Type

Description

modelProperty

String

Name of model property for widget value

title

String

Title to show on bar

image

String

File path relative to application folder for image to show on bar

icon

String

CSS class for icon to display on the bar

iconPath

String

File path relative to application folder for icon

Model properties

Type

Description

value

Integer

Value of the widget

title

String

Dynamic title to show on bar

image

String

File path relative to application folder for dynamic image to show on bar

Events

Mojo.Event.progressIconTap
Mojo.Event.progressComplete

Methods

reset()

Reset progress to 0

cancelProgress()

Stop the progress and freeze bar display in current state

Progress Slider

For media or other applications in which you want to show progress as part of a tracking slider, the Progress Slider is an ideal choice. Combining the Slider widget with the Progress Pill, the behavior is fully integrated, but not all of the configuration options are represented.

Attribute properties

Type

Description

sliderProperty

String

Name of model property for slider position value

progressProperty

String

Name of model property for progress position value

progressStartProperty

Integer

Starting position of progress bar

minValue

Integer

Starting value, or leftmost value on the slider

maxValue

Integer

Ending value, or rightmost value on the slider

round

Boolean

If true, will round the value to the nearest integer

updateInterval

Integer

If set >0, the widget will send events every updateInterval seconds

Model properties

Type

Description

value

Integer

Value of the widget

Events

Mojo.Event.propertyChange
Mojo.Event.progressComplete

Methods

reset()

Reset progress to 0

Radio Button

The Radio Button presents each button as a labeled selection option in a horizontal array, where only one option can be selected at a time.

Attribute properties

Type

Description

modelProperty

String

Name of model property for widget state

disabledProperty

String

Name of model property for disabled state

choices

Array

Array of button descriptions; each entry is required to be:

{label: 'string', value: value}

The number of entries defines the number of buttons presented in the widget

Model properties

Type

Description

value

Boolean

Current value of widget

disabled

Boolean

Default property that, when true, disables the widget

Events

Mojo.Event.propertyChange

Rich Text Edit

There is a simple Rich Text Edit widget that behaves similar to a multi-line text field, but in addition supports applying Bold, Italic, and Underline styles to arbitrary runs of text within the field. To enable the styling, set the Application menu’s RichTextEditItems property to true.

Attribute properties

Type

Description

None

  

Model properties

Type

Description

value

Boolean

Current value of widget

Events

None

Scroller

The Scroller widget provides the scrolling behavior in Mojo. Scrollers can be applied to any div content and set to one of six scrolling modes.

Attribute properties

Type

Description

mode

String

Scrolling mode; one of free, vertical, horizontal, dominant, vertical-snap, or horizontal-snap

Model properties

Type

Description

snapElements

Array

Array of DOM elements used as snap points for horizontal or vertical scrolling

Events

Mojo.Event.propertyChange

Methods

revealTop(newTop)

Jumps the scroll to reveal the top of the specified object at the top of the scroll area

revealBottom()

Jumps the scroll to reveal the bottom of the content being scrolled

revealElement(Element)

Jumps the scroll to reveal a specific DOM element

scrollTo(x-coord, y-coord, animated, 
suppressNotification)

Jumps the scroll to the specified x- and y-coordinates; set animated to true to animate the scroll, or if animated is false, set suppressNotification to true to prevent notifications to event listeners

getState()

Returns the current scroll state for use in a future call to setState()

setState(scrollState, animate)

Jumps the scroll to the value specified in scrollState; pass true to animate the scroll

adjustBy(deltaX, deltaY)

Adjusts 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(newMode)

Set the mode of the scroller, which controls which drag directions causes scrolling; choices are free, dominant, horizontal, horizontal-snap, vertical, and vertical-snap

getScrollPosition()

Get the current position of the scroller; returns:

{left: nnn px, top: nnn px}
setSnapIndex(snapIndex, animate)

Sets the snap index for a snap scroller and scrolls to the new position; pass true to animate

Slider

The Slider presents a range of selection options in the form of a horizontal slider with a control knob that can be dragged to the desired location.

Attribute properties

Type

Description

modelProperty

String

Name of model property for widget value

minValue

Integer

Starting value, or leftmost value on the slider

maxValue

Integer

Ending value, or rightmost value on the slider

round

Boolean

If true, will round the value to the nearest integer

updateInterval

Integer

If set >0, the widget will send events every updateInterval seconds

Model properties

Type

Description

value

Integer

Value of the widget

Events

Mojo.Event.propertyChange

Spinner

Use a Spinner to show that an activity is taking place. The framework uses a Spinner as part of any activity button, and you’ll see it used in the core applications. There are two sizes: the large Spinner is 128 × 128 pixels, and the small Spinner is 32 × 32.

Attribute properties

Type

Description

modelProperty

String

Name of model property for widget state

spinnerSize

String

Choices are:

Mojo.Widget.spinnerLarge
Mojo.Widget.spinnerSmall
superClass

String

Specifies the CSS class name for the background image with a custom spinner

startFrameCount

Integer

With a custom spinner, this is set to the number of frames for the preloop animation

mainFrameCount

Integer

With a custom spinner, this is set to the number of frames for the main loop animation

finalFrameCount

Integer

With a custom spinner, this is set to the number of frames for the post-loop animation

frameHeight

Integer

Explicitly sets the height of the animation

fps

Integer

Frames per second of the main loop animation

Model properties

Type

Description

spinning

Boolean

Spinner state; set to true if spinning

Events

Mojo.Event.propertyChange

Methods

start()

Start the spinner

stop()

Stop the spinner

toggle()

Change the spinner from start to stop or from stop to start

Text Field

The basic text widget that supports all general text requirements: single or multi-line text entry, with common styles for labels, titles, headings, body text, line items, and item details. The editing tools include basic entry and deletion, symbol and alternate character sets, cursor movement, selection, cut/copy/paste, and auto text correction.

Attribute properties

Type

Description

modelProperty

Boolean

Name of model property for widget value

disabledProperty

String

Name of model property for disabled state

hintText

String

Initially displayed string; supplanted by model value if supplied

inputName

String

If supplied, the text area will have this DOM name so that when it is serialized, the property can easily be pulled out

charsAllow

Function

Function must return true to allow input character, or false if not allowed

autoFocus

Boolean

If true, field has focus on scene push

modifierState

String

Initial state of modifier keys for this field; can be: Mojo.Widget.numLock or Mojo.Widget.capsLock

growWidth

Boolean

Automatically grow field horizontally

autoResizeMax

String

Maximum width of field

enterSubmits

Boolean

If set, the Enter key will submit rather than newline; must be used with multi-line

limitResize

Boolean

Limit height resize (scrolls text rather than grow field)

preventResize

Boolean

There will be no resizing in any dimension

holdToEnable

Boolean

if the text field is disabled, tapping and holding and releasing will enable it; if disabled is not set, this is ignored

focusMode

String

Replace or Insert Mode; choices are:

Mojo.Widget.focusSelectMode
Mojo.Widget.focusInsertMode
Mojo.Widget.focusAppendMode
changeOnKeyPress

Boolean

If true, sends a property change event on every character change to a field; otherwise only when field loses focus

maxLength

Integer

Maximum character length of field; does not apply to multi-line fields, where it will be ignored

requiresEnterKey

Boolean

Requires Enter key to submit; other navigation will not submit contents of field

holdToEdit

Boolean

Tap and hold to focus/edit; tap only will be ignored

emoticons

Boolean

Enable emoticons on this field

autoReplace

Boolean

Whether to enable the Smart Text Engine services

textCase

String

Options are:

Mojo.Widget.steModeSentenceCase
Mojo.Widget.steModeTitleCase
Mojo.Widget.steModeLowerCase

Model properties

Type

Description

value

Boolean

Value of the widget

disabled

Boolean

Default property that when true, disables the widget

Events

Mojo.Event.propertyChange

Methods

focus()

Put focus on the input field

blur()

Remove focus from the input field

getValue()

Get the plain-text value of the widget

setValue(String)

Set the plain-text value of the widget

getCursorPosition()

Returns an option with:

{selectionStart: int, selectionEnd: int}

that describe the position of the cursor; if start is not equal to end, there is text selected

setCursorPosition(start, end)

Sets the cursor position in the input portion of the text field

Time Picker

The Time Picker enables selection of hours, minutes, and either A.M. or P.M. for time selection. The picker will suppress the A.M./P.M. capsule if the 24-hour time format is selected in the user preferences or by the locale.

Attribute properties

Type

Description

label

String

Label displayed with the widget controls

labelPlacement

String

Choices are:

Mojo.Widget.labelPlacementLeft
Mojo.Widget.labelPlacementRight
modelProperty

String

Name of model property for date object; defaults to 'time'

minuteInterval

Integer

Interval between minute selections

Model properties

Type

Description

time

Date

Date object set to the widget value

Events

Mojo.Event.propertyChange

Toggle Button

The Toggle Button is another widget for displaying and controlling a binary state value. As with the Check Box, the Toggle Button will switch between two states each time it is tapped.

Attribute properties

Type

Description

modelProperty

String

Name of model property for widget state

disabledProperty

String

Name of model property for disabled state

trueValue

String

Value to set modelProperty when widget state is true

trueLabel

String

Label when widget state is true

falseValue

String

Value to set modelProperty when widget state is false

falseLabel

String

Label when widget state is false

inputName

String

Identifier for the value of the check box; used when the widget is used in HTML forms

Model properties

Type

Description

value

Boolean

Current value of widget

disabled

Boolean

Default property that, when true, disables the widget

Events

Mojo.Event.propertyChange

Web View

To embed a contained web object, declare and instantiate a WebView widget. You can use it render local markup or to load an external URL; as long as you can define the source as a reachable URL, you can use a WebView to render that resource.

Attribute properties

Type

Description

virtualpageheight

Integer

The browser’s virtual page height

virtualpagewidth

Integer

The browser’s virtual page width

url

String

The initial URL to display

pageIdentifier

Function

The BrowserServer page identifier; this is used when the Browser Server instructs an application to open a new URL

minFontSize

Integer

The minimum font size that the browser will display

topMargin

Integer

The margin above the web view that is scrolled off the screen when a new page is loaded

cacheAdapter

Boolean

If true, cache this adapter, false if not, or undefined to not specify and use the browser-adapter default; default is undefined

interrogateClicks

Boolean

Use to call the host application for every hyperlink click via Mojo.Event.webViewLinkClicked

showClickedLink

Boolean

Styles clicked links with grey background and border

Model properties

Type

Description

None

  

Events

Mojo.Event.webViewLoadStarted
Mojo.Event.webViewLoadProgress
Mojo.Event.webViewLoadStopped
Mojo.Event.webViewDownloadFinished
Mojo.Event.webViewLinkClicked
Mojo.Event.webViewTitleUrlChanged
Mojo.Event.webViewTitleChanged
Mojo.Event.webViewUrlChanged
Mojo.Event.webViewCreatePage
Mojo.Event.webViewTapRejected
Mojo.Event.webViewScrollAndScaleChanged
Mojo.Event.webViewEditorFocused
Mojo.Event.webViewUpdateHistory
Mojo.Event.webViewSetMainDocumentError
Mojo.Event.webViewServerConnect
Mojo.Event.webViewServerDisconnect
Mojo.Event.webViewResourceHandoff
Mojo.Event.webViewFirstPaintComplete
Mojo.Event.webViewUrlRedirect
Mojo.Event.webViewModifierTap
Mojo.Event.webViewMimeNotSupported
Mojo.Event.webViewMimeHandoff

Methods

setTopMargin(margin)

Set the top margin (in pixels)

clearCache()

Clear browser cache

clearCookies()

Clear browser cookies

deleteImage(image)

Delete the image file specified by the argument

generateIconFromFile(src, dst, left, 
top, right, bottom)

Generate a 64 × 64 pixel icon from a portion of a source file; the output icon will be given a drop shadow and sheen consistent with other launcher icons

goBack()

Go to the previous page in the user’s browsing history

goForward()

Go to the next page in the user’s browsing history

openURL(url)

Open the specified URL in the WebView

reloadPage()

Reload the currently loaded page

resizeImage(src, dst, width, height)

Resize the input file to the specified width/height and write the new image to the specified output file

getHistoryState(onSuccess)

Asynchronous; retrieves the current history state from the Browser server; will call onSuccess with results

setBlockPopups(enable)

Set to true to block pop-ups

setAcceptCookies(enable)

Set to false to disable cookies

addUrlRedirect(urlRe, redirect, 
userData, type)

Add a URL redirect; when the browser server navigates to a URL matching urlRe and redirect is true, it will not navigate to that URL, and will instead send a Mojo.Event.webViewUrlRedirect event

addSystemRedirects(skippAppId)

Read the command resource handler table and send down redirect handler commands to the browser server

saveViewToFile(fname, left, top, 
width, height)

Save the specified view frame (in pixels) to the specified file

setEnableJavaScript(enable)

Set to false to disable JavaScript

stopLoad()

Stop loading the current page

clearHistory()

Clear browser history

setShowClickedLink(enable)

Set to true to enable launch of clicked links

Dialogs

This section includes the three Mojo dialog APIs:

  • Error dialog

  • Alert dialog

  • Custom dialog

Each entry includes a brief description, repeating some of the information from Chapter 4, Dialogs and Menus, followed by an enumeration of the arguments. Dialogs are accessed through a direct API so the format for this entry will be structured as an API entry.

Mojo.Controller.errorDialog()

This API is used to post error messages in a modal dialog box with a fixed title of “Error,” a customizable message, and a confirmation button. The Error dialog must be used only with errors, since you can’t change the title.

Arguments

Type

Description

message

String

Displayed message in a modal dialog

window

Element

Optional argument to specify the window to post the alert within; required in multistage applications

Mojo.Controller.SceneController.showAlertDialog()

You can display a short message using an Alert dialog, with one or more HTML buttons presenting the selection options. This is the best option if you have either a nonerror message for the user or want to present options in the form of button selections.

Arguments

Type

Description

onChoose
FunctionHandler called when user makes a choice and the dialog is dismissed
message

String

Displayed message in a modal dialog

title

String

Title of the dialog box

preventCancel

Boolean

If true, back gesture or other alerts will not cancel the dialog box

choices

Array

Array of button descriptions; each entry is required to be:

{label: 'string', value: value, type: 'string', 
allowHTMLMessage: boolean}

The number of entries defines the number of buttons presented in the dialog box; the type property is set to one of the button classes (e.g., primary, secondary, affirmative, negative); allowHTMLMessage set to allow insertion of HTML if safe

allHTMLMessage

Boolean

If true, the message string will not have HTML escaped

Mojo.Controller.SceneController.showDialog()

The showDialog function can display any type of content to the user in the form of a modal dialog box. You can put anything into a dialog box that you’d put into a scene, meaning almost any web content or Mojo UI content.

Arguments

Type

Description

template

String

File path to HTML template containing content for the dialog box; rendered with properties from this model object

assistant

Object

The dialog assistant responsible for running the dialog box, which must implement methods (setup, activate, deactivate, cleanup, and handleCommand)

preventCancel

Boolean

If true, back gesture or other alerts will not cancel the dialog box

Menus

This section summarizes the four menu types:

  • Application menu

  • Command menu

  • View menu

  • Submenu

The three menu types are structured like the widgets in the previous section. Each entry includes a brief description, repeating some of the information from Chapter 4, Dialogs and Menus, followed by an enumeration of the widget’s attribute and model properties, as well as relevant events. Unlike the other menu types, Submenu is accessed through a direct API, so the format for this entry will be structured as an API entry.

AppMenu

The Application menu appears in the upper-left corner of the screen when the user taps the left side of the status bar. It includes some system-defined and some application-defined actions, and is intended to have an application-wide scope for the most part.

Attribute properties

Type

Description

omitDefaultItems

Boolean

If true, default menu items will not be added to this menu

richTextEditItems

Boolean

If true, the Edit menu will also include Bold/Italics/Underline

Model properties

Type

Description

label

String

Currently not supported

visible

Boolean

Current visibility of this menu

Items

Object

Object containing items for this menu, structured as:

  label

String

User-visible label for this item, not rendered for groups

  icon

String

CSS class for icon to display in this item

  iconPath

String

Path to image to display in menu item, relative to application’s directory

  width

Integer

Calculated based on item’s width; specifies the width in pixels of this menu item; overrides default calculations; ignored for groups

  items

Boolean

If this is specified, this item is a group that visually ties the child items together

  toggleCmd

Boolean

Only used when items is specified; specify this property to make this group a toggle group; this string is the command of currently selected choice item in this group, and this property is modified by the widget when a different choice is made

  command

Boolean

Specify to make this item a choice; it will then respond to a user tap by sending a Mojo.Event.command through the commander chain with this string as the command property

  disabled

Boolean

Menu choice is disabled when this is true; only used for items that also specify command

  submenu

Boolean

Specify to make this item a submenu item; it will then respond to a user tap by displaying the named menu as a pop-up submenu

  template

String

Path to HTML template for custom content to be inserted instead of a standard menu item; the template is rendered using this item model object for property substitution

  checkEnabled

Boolean

If set to true, a Mojo.Event.commandEnable event will be sent through the commander chain each time this menu item is displayed or invoked via keyboard shortcut

Events

Mojo.Event.command
Mojo.Event.commandEnable

Command Menu

The Command menu items are presented at the bottom of the screen. Items include variable-sized buttons that can be combined into groups, and in a horizontal layout from left-to-right.

Attribute properties

Type

Description

spacerHeight

Boolean

If specified, the spacer DIV associated with this menu will be the given height in pixels

menuClass

Boolean

Alternate CSS style; default is palm-default

Model properties

Type

Description

label

String

Currently not supported

visible

Boolean

Current visibility of this menu

items

Object

Object containing items for this menu, structured as:

  label

String

User-visible label for this item, not rendered for groups

  icon

String

CSS class for icon to display in this item

  iconPath

String

Path to image to display in menu item, relative to application’s directory

  width

Integer

Calculated based on item’s width; specifies the width in pixels of this menu item; overrides default calculations; ignored for groups

  items

Boolean

If this is specified, this item is a group that visually ties the child items together

  toggleCmd

Boolean

Only used when items is specified; specify this property to make this group a toggle group; this string is the command of currently selected choice item in this group, and this property is modified by the widget when a different choice is made

  command

Boolean

Specify to make this item a choice; it will then respond to a user tap by sending a Mojo.Event.command through the commander chain with this string as the command property

  disabled

Boolean

Menu choice is disabled when this is true; only used for items which also specify command

  submenu

Boolean

Specify to make this item a submenu item; it will then respond to a user tap by displaying the named menu as a pop-up submenu

  template

String

Path to HTML template for custom content to be inserted instead of a standard menu item; the template is rendered using this item model object for property substitution

  checkEnabled

Boolean

If set to true, a Mojo.Event.commandEnable event will be sent through the commander chain each time this menu item is displayed or invoked via keyboard shortcut

Events

Mojo.Event.command
Mojo.Event.commandEnable

View Menu

The View menu presents items as variable-sized buttons, either singly or in groups across the top of the scene. The items are rendered in a horizontal sequence starting from the left of the screen to the right.

Attribute properties

Type

Description

spacerHeight

Boolean

If specified, the spacer DIV associated with this menu will be the given height in pixels

menuClass

Boolean

Alternate CSS style; default is palm-default

Model properties

Type

Description

label

String

Currently not supported

visible

Boolean

Current visibility of this menu

items

Object

Object containing items for this menu, structured as:

  label

String

User visible label for this item, not rendered for groups

  icon

String

CSS class for icon to display in this item

  iconPath

String

Path to image to display in menu item, relative to application’s directory

  width

Integer

Calculated based on item’s width; specifies the width in pixels of this menu item; overrides default calculations; ignored for groups

  items

Boolean

If this is specified, this item is a group that visually ties the child items together

  toggleCmd

Boolean

Only used when items is specified; specify this property to make this group a toggle group; this string is the command of currently selected choice item in this group, and this property is modified by the widget when a different choice is made

  command

Boolean

Specify to make this item a choice; it will then respond to a user tap by sending a Mojo.Event.command through the commander chain with this string as the command property

  disabled

Boolean

Menu choice is disabled when this is true; only used for items which also specify command

  submenu

Boolean

Specify to make this item a submenu item; it will then respond to a user tap by displaying the named menu as a pop-up submenu

  template

String

Path to HTML template for custom content to be inserted instead of a standard menu item; the template is rendered using this item model object for property substitution

  checkEnabled

Boolean

If set to true, a Mojo.Event.commandEnable event will be sent through the commander chain each time this menu item is displayed or invoked via keyboard shortcut

Events

Mojo.Event.command
Mojo.Event.commandEnable

Submenu

Mojo.Controller.SceneController.popupSubmenu()

Pop-up submenus can offer a transient list of choices to the user, typically off of another menu entry or from a DOM element in the scene.

Arguments

Type

Description

onChoose

Function

Called when user makes a choice and the pop-up is dismissed

placeNear

Element

Used to position the pop-up menu near the triggering element

toggleCmd

Boolean

Causes the appropriate item to appear with a checkmark; supported in top-level model for pop-ups

popupClass

String

CSS class for the pop-up menu, referenced from the HTML templates

scrimClass

String

CSS class for the pop-up scrim; defaults to submenu-popup

manualPlacement

Boolean

If true, pop-up menu will not be placed automatically (centered, or near placeNear element)

items

Array

Array of choices; each choice is an object with the following properties:

  label
StringDisplay name of choice
  command
StringCommand string passed to onChoose handler when selected
  secondaryIcon
StringCSS class for a secondary icon to display, generally used for some kind of status, and appearing to the left of the menu item
  secondaryIconPath
StringJust like iconPath, but for secondaryIcon
  chosen
BooleanStyles the item as the selected item in the group

Storage

This section describes the Cookie and Depot objects and methods. Each section includes a brief description, repeating some of the information from Chapter 6, Data, followed by an enumeration of each object’s methods with their arguments and return values. Both storage objects are accessed through a direct API, so the format for this entry will be structured as an API entry.

If you’d like more detailed information on the HTML 5 Database object, refer to the specification at http://dev.w3.org/html5/webstorage/#databases.

Mojo.Model.Cookie()

Mojo cookies are technically related to browser cookies, but with an object interface to simplify use by webOS applications. Mojo cookies typically store small amounts of data that will be used to preserve application state and related information, such as preference settings.

Calling the constructor will open the named cookie if it already exists, or if it doesn’t exist, will create it.

Constructor

new Mojo.Model.Cookie(cookieName, optionalDocument)

Arguments

Type

Description

cookieName

String

Name for the cookie; has an application scope so uniqueness across applications is not a requirement

optionalDocument

Object

Document element to store cookie; defaults to current document

Methods

get()

Returns the object stored in this cookie, or undefined if the cookie doesn’t exist

put(objectToStore, expirationDate)

Updates the value of this cookie with the passed object with an optional date object to set an expiration date; if no expiration date is set, the cookie will not expire

remove()

Deletes the cookie

Mojo.Depot()

The Depot object is a wrapper on the HTML 5 APIs for simple object storage and retrieval. You can store up to 1 MB of data in a depot by default. Mojo provides by a few simple functions that wrap the HTML 5 APIs to create, read, update, or delete a database.

Calling the constructor will open the named depot if it already exists, or if it doesn’t exist, will create it.

Constructor

new Mojo.Depot(options, onSuccess, onFailure)

Arguments

Type

Description

options

Object

Options for opening or creating a depot, structured as:

  name

String

Name used to identify the underlying database; has an application scope; use 'ext:' prefix to create Depot in the /media partition

  version

Integer

Version number used for the underlying database

  displayName

String

Not currently supported; for future use

  estimatedSize

Integer

Estimated size in bytes; used to assist framework in managing databases

  replace

Boolean

If true, will replace the existing database if it exists; defaults to false

onSuccess

Function

Callback function that is called if the depot is successfully opened or created

onFailure

Function

Callback function that is called with an error string if an error occurs

Methods

add(key, objectToStore, 
onSuccess, onFailure)

Function to add an object, objectToStore, identified by a key

get(key, onSuccess, 
onFailure)

Gets the object identified by the key and returned as the single argument to the onSuccess function

discard(key, onSuccess, 
onFailure)

Removes the depot object associated with the key

removeAll(onSuccess, 
onFailure)
Removes everything in the depot

Services

This section describes the available application, device, and cloud service methods. Each service is briefly described, repeating some of the information from Chapters 8 and 9, with a listing of the service’s available methods, arguments, and responses.

All services are accessed through:

Mojo.Service.Request(serviceName, {method:methodName, 
parameters:{}, onSuccess:{}, onFailure:{}})

Each service entry includes:

  • The serviceName in the form of a string such as 'palm://com.palm.name'

  • A description of each method, with the methodName and parameters properties

  • The contents of the response object, which is provided as an argument in the callbacks to either the onSuccess or onFailure functions

Accounts

palm://com.palm.accounts/crud

The Accounts service provides an interface for interacting with the accounts system. To use the Synergy applications, you must provide an account ID as a parameter; this service provides access to those IDs.

Many of the methods will use some common objects.

Account

Properties

Type

Description

username

String

Login credentials

domain

String

The account source

accountId

String

The account reference for use in the Synergy applications

icons

Object

Includes largeIcon and smallIcon properties whose values are file paths to the appropriate account icons

dataTypes

Object

A hash of strings indicating which applications apply to this account, either "CONTACTS" or "CALENDAR"

isDataReadOnly

Boolean

If true, data with this account is read-only

Method: listAccounts

Lists accounts created by this application.

Parameters

Type

Description

None

  

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

list

Array

List of account objects

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: createAccount

Creates an account.

Parameters

Type

Description

account

Object

Account object specifying account data

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

accountId

String

The account reference for use accessing the account or for services that are based on the account

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: getAccount

Gets the details of an account.

Parameters

Type

Description

accountId

String

The account reference for use accessing the account or for services that are based on the account

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

account

Object

Account object specifying account data

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: updateAccount

Updates an account with revised data type, icons, or a change to read/write permissions.

Parameters

Type

Description

accountId

String

The account reference for use accessing the account or for services that are based on the account

displayName
StringThe displayable account name
icons

Object

Includes largeIcon and smallIcon properties whose values are file paths to the appropriate account icons

isDataReadOnly

Boolean

If true, data with this account is read-only

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

accountId

String

The account reference for use accessing the account or for services that are based on the account

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: deleteAccount

Deletes account data for one or more data types.

Parameters

Type

Description

accountId

String

The account reference for use accessing the account or for services that are based on the account

dataTypes

Object

A hash of strings indicating which applications apply to this account, either "CONTACTS" or "CALENDAR"

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise there is an error and the account was not created

dataTypes

Object

A hash of strings indicating which data types were deleted

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Alarms

palm://com.palm.power/timeout

The Alarm service is based on the device’s real-time clock (RTC). Alarms are intended to wake applications while minimized, maximized, or to drive polling for Dashboard applications.

Method: set

Sets an alarm to wake up the application.

Parameters

Type

Description

at

String

Create a calendar-based alarm in GMT; of the form: 'mm/dd/yyyy hh:mm:ss'; either at or in is required

in

String

Create a relative alarm; of the form: 'hh:mm:ss', with a minimum alarm of five minutes

uri

String

URI of serviceName/methodName to be called when alarm fires

wakeup

Boolean

Wake up the device from sleep when set to true; set to false by default

params

Object

Parameter object to be sent along with service call; the contents are dependent on the service method defined by the uri parameter

Response

Type

Description

returnValue

Boolean

If true, the alarm was successfully set; otherwise, there is an error and the alarm was not set

key

String

The key provided in the method call

errorText

String

An error message; only provided with returnValue set to false

Method: clear

Clears a previously set alarm.

Parameters

Type

Description

key

String

The key provided in the method call

Response

Type

Description

returnValue

Boolean

If true, the alarm was successfully set; otherwise, there is an error and the alarm was not set

key

String

The key provided in the method call

errorText

String

An error message; only provided with returnValue set to false

Application Manager

palm://com.palm.applicationManager

The Application Manager service provides functions related to finding and launching applications. Applications launched through the Application Manager will open and maximize a new window for the targeted application while minimizing the current application window. This is the general case of specific application services. Currently supported are:

  • Audio

  • Browser

  • Email

  • Maps

  • Messaging

  • Phone

  • Photos

  • Video

For details on calling individual services, refer to the specific service in this section.

Method: open

The Application Manager will use the content type to find the appropriate application to use for that content. Refer to Tables B.1, B.2, and B.3 for the supported content types.

Parameters

Type

Description

target

String

A standard URI format of the form: command://url, where command is one of the supported commands, and the url is an argument string in conventional URL notation; if the command is a webOS application, the url argument string will be specified by that application

Response

Type

Description

None

  

Table B.1. Supported file types

Extension

Mime type

htm

text/html

html

text/html

pdf

application/pdf

txt

application/txt

doc

application/doc

doc

application/msword

xls

appId”:"com.palm.app.docviewer

xls

appId”:"com.palm.app.docviewer

xls

application/vnd.ms-excel

xls

application/x-excel

xls

application/x-msexcel

ppt

application/ppt

ppt

application/mspowerpoint

ppt

application/powerpoint

ppt

application/vnd.ms-powerpoint

ppt

application/x-mspowerpoint


Table B.2. Supported video formats

Extension

Mime type

mp4

video/mp4-generic

mp4

video/quicktime

mp4

video/mp4

mp4

video/mpeg4

m4v

video/mp4-generic

m4v

video/quicktime

m4v

video/mp4

m4v

video/mpeg4

3gp

video/3gp

3gpp

video/3gp

3g2

video/3gpp

3gpp2

video/3gpp

sdp

application/sdp


Table B.3. Supported audio formats

Extension

Mime type

3gp

audio/3gpp

3gpp

audio/3gpp

3ga

audio/3gpp

3gp

audio/3ga

3gpp

audio/3ga

3ga

audio/3ga

3g2

audio/3gpp2

3gp2

audio/3gpp2

sdp

audio/amr

amr

audio/x-amr

mp3

audio/mpa

mp3

audio/mp3

mp3

audio/x-mp3

mp3

audio/x-mpg

mp3

audio/mpeg

mp3

audio/mpeg3

mp3

audio/mpg3

mp3

audio/mpg

mp4

audio/mp4

m4a

audio/mp4

m4a

audio/m4a

aac

audio/aac

aac

audio/x-aac

aac

audio/mpeg

aac

audio/mp4a-latm

wav

audio/wav

pls

audio/x-scpls

m3u

audio/mpegurl

m3u

audio/x-mpegurl


Method: launch

This method will launch a specific application and pass in parameters in the form that the application has specified.

Parameters

Type

Description

id

String

The application ID, defining the intended application

params

Object

JSON object containing the parameters for the target application and specified by the target application

Response

  

None

  

Audio

palm://com.palm.applicationManager

The Audio application can be launched through the Application Manager service.

Method: launch

Launches the Audio application to play or stream the file located at the target URI, downloading it first if not already on the device. If the URI is not specified, it will just launch the audio player to its normal starting scene.

Parameters

Type

Description

id

String

Set to 'com.palm.app.streamingmusicplayer'

params

Object

Includes a single property:

  target

String

URL of the form rtsp://audio-file, where audio-file is a well-formed URI targeting an audio file encoded in a supported video format

Response

Type

Description

None

  

Calendar

palm://com.palm.calendar/crud

The Calendar API provides programmatic access to the Calendar application. It allows you to create, read, update, delete, and list calendars, events, and attendees. To use this API you must have an account created via the Accounts API. An account has many calendars, a calendar has many events, and an event has many attendees.

Many of the APIs will use the calendar or event objects as input or output argument.

Calendar

Properties

Type

Description

calendarId

String

Immutable unique identifier for this calendar

name

String

Display name for this calendar

externalId

String

External ID for this calendar

Event

Properties

Type

Description

subject

String

Title of the event

startTimestamp

String

Event start time (in milliseconds UTC)

endTimestamp

String

Event end time (in milliseconds UTC)

allDay

Boolean

True if all-day event

note

String

Optional note text

location

String

Location of the event

alarm

String

ISO 8601 duration format or none, all lowercase

rrule

String

RFC 2445 recurrence string, may only include RRULE, EXRULE, RDATE, or EXDATE

rruleTZ

String

rrule timezone object; this object is mandatory if an rrule is specified

endValidity

String

The end timestamp for nonrecurring events; for recurring events, the end timestamp of last occurrence or 0 if it repeats forever

attendees

Object

Event start time (in milliseconds UTC)

externalId

String

An externalId reference to this event and parented

parentId

String

This is an exception that needs to be linked to a parent recurring series

originalStartTimestamp

Integer

The original start timestamp of this event in the parent series

Note

On methods that accept a calendarId as an input argument (getCalendar, updateCalendar, and deleteCalendar), you can alternately provide an externalId and an accountId.

Method: createCalendar

Creates a new calendar.

Parameters

Type

Description

accountId

String

The account reference for use in the Synergy applications

calendar

Object

Specify the name and optionally the externalId

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

calendarId

String

Immutable unique identifier for this calendar

Method: getCalendar

Retrieves the named calendar.

Parameters

Type

Description

calendarId

String

Immutable unique identifier for this calendar

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

calendar

Object

Specify the name and optionally the externalId

Method: updateCalendar

Updates the named calendar.

Parameters

Type

Description

calendar

Object

Specify the name and optionally the externalId

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: deleteCalendar

Deletes the named calendar.

Parameters

Type

Description

calendarId

String

Immutable unique identifier for this calendar

Response

Type

Description

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: listCalendars

Lists all calendars created by the calling application; you will see only the calendars that you have created.

Parameters

Type

Description

accountId

String

The account reference for use in the Synergy applications

Response

Type

Description

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

calendars

Array

List of calendar objects associated with this account

Method: createEvent

Adds the provided event to the named calendar.

Parameters

Type

Description

calendarId

String

Immutable unique identifier for this calendar

event

Object

Details of the calendar event

trackChanges

Boolean

Marks this change so that it’s tracked, and getChanges will include this record ID in its response; defaults to false

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

eventId

String

Immutable unique identifier for this event

Method: getEvent

Retrieves the details of the named event.

Parameters

Type

Description

eventId

String

Immutable unique identifier for this event

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

event

Object

Details of the calendar event

Method: updateEvent

Updates the event details of the named event.

Parameters

Type

Description

event

Object

Details of the calendar event

trackChanges

Boolean

Marks this change so that it’s tracked, and getChanges will include this record ID in its response; defaults to false

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: deleteEvent

Deletes the named event.

Parameters

Type

Description

eventId

String

Immutable unique identifier for this event

trackChanges

Boolean

Marks this change so that it’s tracked, and getChanges will include this record ID in its response; defaults to false

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: listEvents

Lists all events created by the calling application; you will only see events in calendars that you have created.

Parameters

Type

Description

calendarId

String

Immutable unique identifier for this calendar

startTimestamp

String

Start of search range (in milliseconds UTC)

endTimestamp

String

End of search range (in milliseconds UTC)

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

events

Array

Array of event objects that fit the search criteria

Method: startTracking

Enables change tracking for an account. After this is called, all user-initiated changes to records belonging to this account will be returned by getChanges. Change tracking is incremental, and changes are forgotten each time doneWithChanges is called.

Parameters

Type

Description

accountId

String

The account reference for use in the Synergy applications

trackerId

String

A client-chosen handle if multiple independent change trackers are needed per account

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: getChanges

Gets a list of calendar and event IDs for records in an account that have been changed or deleted by the user since the last time doneWithChanges was called.

Parameters

Type

Description

accountId

String

The account reference for use in the Synergy applications

trackerId

String

A client-chosen handle if multiple independent change trackers are needed per account

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

token

String

A string to be passed to doneWithChanges after processing of this change set is complete

calendar

Object

Includes changed, an array of changed calendar objects (calendarId only), and deleted, an array of deleted calendar objects (calendarId and externalId)

events

Object

Includes changed, an array of changed event objects (eventId only), and deleted, an array of deleted event objects (eventId and externalId)

Method: doneWithChanges

Forgets all changes for an account. Future calls to getChanges will return only changes from this point forward.

Parameters

Type

Description

accountId

String

The account reference for use in the Synergy applications

trackerId

String

A client-chosen handle if multiple independent change trackers are needed per account

token

String

A string to be passed to doneWithChanges after processing of this change set is complete

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Connection Manager

palm://com.palm.connectionmanager

Use the Connection Manager’s getStatus method to get updates on the device connection status.

Method: getStatus

Gets connections status and optionally subscribes to connection notifications.

Parameters

Type

Description

subscribe

Boolean

Set to true for subscriptions, default is false

Response

Type

Description

returnValue

Boolean

If true, the status data was returned and the subscription was set if requested

isInternetConnectionAvailable

Boolean

If true, a data connection is available; could be through any of the transports

wifi

Object

An object with the WiFi status properties:

  state

String

Set to either 'connected' or 'disconnected'

  ipAddress

String

WiFi IP address

  ssid

String

The SSID of the currently connected access point

  bssid

String

The BSSID of the currently connected access point

wan

Object

An object with the WAN status properties:

  state

String

Set to either 'connected' or 'disconnected'

  ipAddress

String

WAN IP address

  network

String

Set to 'unknown', 'unsusable', 'gprs', 'edge', 'umts', 'hsdpa', '1x', 'evdo'

btpan

Object

An object with the Bluetooth PAN status properties:

  state

String

Set to either 'connected' or 'disconnected'

  ipAddress

String

Bluetooth IP address

  panUser

String

Set to the name of the Bluetooth PAN client connected to the device

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Contacts

palm://com.palm.contacts/crud

The Contacts API provides programmatic access to the Contacts application. It allows you to create, read, update, delete, and list contacts entries. To use this API you must have an account created via the Accounts API.

Many of the APIs will use the contacts or contactslice objects as input or output arguments.

Contact

Properties

Type

Description

id

String

Immutable unique identifier for this Contact record

firstName

String

 
lastName

String

 
middleName

String

 
displayText

String

 
prefix

String

 
suffix

String

 
companyName

String

 
jobTitle

String

 
pictureLoc

String

File path to picture location; 50 × 50 pixels rough size

pictureLocSquare

String

File path to picture location; 50 × 50 pixels rough size, but guaranteed to be square

pictureLocBig

String

File path to picture location; a full size image

isAvatarLoc

String

The original start timestamp of this event in the parent series

birthday

String

YYYYMMDD format

anniversary

String

YYYYMMDD format

nickname

String

 
spouse

String

 
children

String

 
notes

String

 
phoneNumbers

Array

Array of phone number strings

emailAddresses

Array

Array of email address strings

imNames

Array

Array of IM names strings

addresses

Array

Array of physical address strings

urls

Array

Array of urls strings

customFields

Array

Array of custom field strings

listPic

String

Input only; the local file path of the picture to use as this contact’s photo in lists; should be square, roughly 50 × 50 pixels

incomingPic

String

Input only; the local file path of the picture to use as this contact’s high-quality photo

extraDetails

String

Generic overflow field for any metadata the third-party application wants to store (will not be displayed in the Contacts application)

Contact Slice

Properties

Type

Description

id

String

Immutable unique identifier for this Contact record

firstName

String

 
lastName

String

 
middleName

String

 
displayText

String

 
prefix

String

 
suffix

String

 
nickname

String

 
companyName

String

 
pictureLoc

String

File path to picture location; 50 × 50 pixels rough size.

pictureLocSquare

String

File path to picture location; 50 × 50 pixels rough size, but guaranteed to be square

Note

On methods that accept an id as an input argument (get, update, and delete), you can alternately provide an externalId and an accountId.

Method: createContact

Adds the provided record to contacts.

Parameters

Type

Description

accountId

String

Immutable unique identifier for this account

contact

Object

The contact to save

externalId

String

External ID for this contact record

trackChanges

Boolean

Marks this change so that it’s tracked, and getChanges will include this record ID in its response; defaults to false

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

id

String

Immutable unique identifier for this contact record

Method: getContact

Retrieves the details of the named contact.

Parameters

Type

Description

id

String

Immutable unique identifier for this contact

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

contact

Object

Details of the contact record

Method: updateContact

Updates the event details of the named contact.

Parameters

Type

Description

accountId

String

Immutable unique identifier for this account

contact

Object

The contact to save

id

String

Immutable unique identifier for this contact

trackChanges

Boolean

Marks this change so that it’s tracked, and getChanges will include this record ID in its response; defaults to false

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: deleteContact

Deletes the named contact.

Parameters

Type

Description

accountId

String

Immutable unique identifier for this account

id

String

Immutable unique identifier for this contact

trackChanges

Boolean

Marks this change so that it’s tracked, and getChanges will include this record ID in its response; defaults to false

Response

Type

Description

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: listContacts

Lists all contacts created by the calling application; you will see only Contact records that you have created.

Parameters

Type

Description

accountId

String

The account reference for use in the Synergy applications

offset

Integer

Start of range

limit

Integer

Number of contacts to return

filter

String

The filter string to search for; matches are done on the firstName, lastName, and companyName fields

Response

Type

Description

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

list

Array

Array of contactslice objects

Method: startTracking

Enables change tracking for an account. After this is called, all user-initiated changes to records belonging to this account will be returned by getChanges. Change tracking is incremental, and changes are forgotten each time doneWithChanges is called.

Parameters

Type

Description

accountId

String

The account reference for use in the Synergy applications

trackerId

String

A client-chosen handle if multiple independent change trackers are needed per account

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Method: getChanges

Gets a list of contact IDs for records in an account that have been changed or deleted by the user since the last time doneWithChanges was called.

Parameters

Type

Description

accountId

String

The account reference for use in the Synergy applications

trackerId

String

A client-chosen handle if multiple independent change trackers are needed per account

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

token

String

A string to be passed to doneWithChanges after processing of this change set is complete

changed

Array

An array of changed contact record objects (id only)

deleted

Array

An array of deleted contact record objects (id and externalId)

Method: doneWithChanges

Forgets all changes for an account. Future calls to getChanges will only return changes from this point forward.

Parameters

Type

Description

accountId

String

The account reference for use in the Synergy applications

trackerId

String

A client-chosen handle if multiple independent change trackers are needed per account

token

String

A string to be passed to doneWithChanges after processing of this change set is complete

Response

Type

Description

returnValue

Boolean

If true, the account was successfully created; otherwise, there is an error and the account was not created

errorCode

Integer

If returnValue is false, the errorCode provides the error number

errorText

String

An error message; only provided with returnValue set to false

Email

palm://com.palm.applicationManager

The Email application can be launched through the Application Manager service.

Method: open

Launches the Email application to the compose scene, which will be addressed with the provided email address.

Parameters

Type

Description

target

String

A mailto URI formatted as specified in RFC2368

Response

Type

Description

None

  

Method: launch

Launches the Email application to the compose scene.

Parameters

Type

Description

id

String

Set to 'com.palm.app.email'

params

Object

Includes a single property:

  summary

String

Text to display in the subject line

  text

String

Text to display in the body of the email message

  recipients

Array

Recipients array, including:

    value

String

A properly formed email address of the recipient

    type

String

Set to email

    role

Integer

Numeric ID for type of recipient where 1=To, 2=CC, and 3=BCC

    contactDisplay

String

Display name for the recipient

  attachments

Array

Array of objects containing the property fullPath (the full path and file name) and the optional properties displayName and mimeType

  accountId

String

The ID of the account from which to send the email message; default account will be used if not provided

Response

Type

Description

None

  

Location Services

palm://com.palm.location

Palm webOS provides basic location services to get single or multiple location fixes.

Method: getCurrentPosition

You can get the current position sourced from the built in GPS, or through Cell ID or WiFi ID, depending on what’s available.

Parameters

Type

Description

accuracy

Integer

Accuracy or precision of the fix: 1 for high precision, 2 for medium (default), and 3 for low

responseTime

Integer

Accuracy or precision of the fix: 1 for less than 5 seconds, 2 for less than 20 seconds (default), and 3 for greater than 20 seconds

maximumAge

Integer

Accept a cached position no older than maximumAge (in seconds); if 0 or not specified, a new fix will always be requested

Response

Type

Description

errorCode

Integer

Status of service request; if errorCode, a successful request and the following response properties will be available; otherwise, errorCode provides an error number to describe the failure

errorText

String

An error message; only provided with returnValue set to false

timestamp

Double

The time (in milliseconds) when the location fix was retrieved

latitude

Double

The latitude of the location in degrees

longitude

Double

The longitude of the location in degrees

horizAccuracy

Double

Horizontal accuracy (in meters) of the location fix

vertAccuracy

Double

Vertical accuracy (in meters) of the location fix

heading

Double

The compass azimuth (in degrees); set to –1 if unknown

velocity

Double

The velocity (in meters/second); set to –1 if unknown

altitude

Double

The altitude (in meters); set to –1 if unknown

Method: startTracking

Requests a continuous GPS fix by invoking the onSuccess callback with a new location object every time the service determines that the position of the device has changed. In case of error, the service will call the callback with error code set to some value greater than 0.

Parameters

Type

Description

subscribe

Boolean

Set to true for subscriptions, default is false

Response

Type

Description

errorCode

Integer

Status of service request; if errorCode, a successful request and the following response properties will be available; otherwise, errorCode provides an error number to describe the failure

errorText

String

An error message; only provided with returnValue set to false

timestamp

Double

The time (in milliseconds) when the location fix was retrieved

latitude

Double

The latitude of the location in degrees

longitude

Double

The longitude of the location in degrees

horizAccuracy

Double

Horizontal accuracy (in meters) of the location fix

vertAccuracy

Double

Vertical accuracy (in meters) of the location fix

heading

Double

The compass azimuth (in degrees); set to −1 if unknown

velocity

Double

The velocity (in meters/second); set to −1 if unknown

altitude

Double

The altitude (in meters); set to −1 if unknown

Method: getReverseLocation

Requests a location for the given latitude and longitude.

Parameters

Type

Description

latitude

Double

The latitude of the location in degrees

longitude

Double

The longitude of the location in degrees

Response

Type

Description

errorCode

Integer

Status of service request; if errorCode, a successful request and the following response properties will be available; otherwise errorCode provides an error number to describe the failure

errorText

String

An error message; only provided with returnValue set to false

address

String

U.S. only, not available in other regions; formatted user-readable address with individual lines separated by a semicolon (;); typically two or three lines

Maps

palm://com.palm.applicationManager

The Maps application can be launched through the Application Manager service.

Method: open

Launches the Maps application to the map scene, which will be loaded from the results of a query if provided.

Parameters

Type

Description

target

String

URL matching the regular expression:

(.+\.)?google\.(com|[a-z]{2}|com?\.[a-z]{2})(/maps/m|/maps/m/.*)

Or alternately, the target string can be of the form mapto:location, where location is a well-formed location

Response

Type

Description

None

  

Method: launch

Launches the Maps application to the map view scene.

Parameters

Type

Description

id

String

Set to 'com.palm.app.maps'

params

Object

Includes:

  query

String

Well-formed expression complying with the Google Map Parameters spec; options include address, latitude/longitude, location, and business search or driving directions

  zoom

String

Zoom level: numeric value from 1 to 18, with 18 being max zoom in; max zoom level depends on the region (for some regions, zoom level 18 may not be available)

  location

Object

If specified, map will search for query around this location as described by these properties:

lat = latitude in degrees (float)

lng = longitude in degrees (float)

acc = accuracy in meters; optional (float)

age = age of fix in seconds

  type

String

Sets the display type, currently limited to m for map (default when not set) and k for satellite

  layer

String

Activates selective overlays, currently limited to t for traffic or null for no overlay

Response

Type

Description

None

  

Messaging

palm://com.palm.applicationManager

The Messaging application can be launched through the Application Manager service.

Method: launch

Launches the Messaging application to the chat scene.

Parameters

Type

Description

id

String

Set to 'com.palm.app.messaging'

params

Object

Includes:

  personId

String

Contacts ID for the recipient; only apply to the launching the chat view

  contactPointId

String

Contacts entry ID for the contact method (i.e., mobile phone number, IM address); only apply to the launching the chat view; you can optionally pass a contactPointId to set the selected transport when you launch the chat

  messageText

String

The contents of the message

  composeAddress

String

Mobile phone number; an alternative to the personID/contactPointId above; currently only supports one number

  attachment

String

Path to a single attachment file; JPG images only

Response

Type

Description

None

  

Phone

palm://com.palm.applicationManager

The Phone application can be launched through the Application Manager service.

Method: open

Launches the Phone application to the dial scene, prepopulating the dial string if provided.

Parameters

Type

Description

target

String

URL of the from "tel://dialstring", where dialstring is part or all of a phone number; the number can contain pause and wait characters to indicate that DTMF tones should be sent after the call connects

Response

Type

Description

None

  

Method: launch

Launches the Phone application to the dial scene.

Parameters

Type

Description

id

String

Set to 'com.palm.app.phone'

Response

Type

Description

None

  

Photos

palm://com.palm.applicationManager

The Photos application can be launched through the Application Manager service.

Method: launch

Launches the Photos application to its album scene.

Parameters

Type

Description

id

String

Set to 'com.palm.app.photos'

Response

Type

Description

None

  

System Properties

palm://com.palm.preferences/systemProperties

Applications can request a named system property, currently limited to a unique device ID.

Method: getSysProperties

Requests the named property, which is returned in a response object.

Parameters

Type

Description

key

String

Options: "com.palm.properties.nduid" (device ID)

Response

Type

Description

returnValue

Boolean

If true, the key was retrieved and the value was returned

errorText

String

An error message; only provided with returnValue set to false

System Service

palm://com.palm.systemservice/time

The system is designed to expose a set of services allowing applications to access some general system settings.

Method: getSystemTime

Requests the system time, and if the subscribe property is true, it will receive notifications when the timezone changes and/or the system time changes by a significant amount (currently five minutes).

Parameters

Type

Description

subscribe

Boolean

Set to true for subscriptions, default is false

Response

Type

Description

returnValue

Boolean

If true, the key was retrieved and the value was returned

errorCode

Integer

Status of service request; if errorCode, a successful request and the following response properties will be available; otherwise, errorCode provides an error number to describe the failure

localtime

Integer

The time for the current timezone (in seconds)

offset

Integer

Offset from the UTC (in minutes)

timezone

String

The current system timezone

System Sounds

palm://com.palm.audio/systemsounds

The System Sounds service is used to play audio feedback in response to user interaction, with low latency.

Method: playFeedback

Plays a system sound using the feedback stream class. Intended for UI feedback such as UI button clicks, keypad clicks, and similar sounds. The available sound names are enumerated in Table B.4, “System sounds”.

Parameters

Type

Description

name

String

Set to the name of the sound to play (see Table B.4, “System sounds” for a complete list of sound names)

Response

Type

Description

returnValue

Boolean

If true, the key was retrieved and the value was returned

errorCode

Integer

Status of service request; if errorCode, a successful request and the following response properties will be available; otherwise, errorCode provides an error number to describe the failure

errorText

String

An error message; only provided with returnValue set to false

Table B.4. System sounds

Names

appclose

back_01

default_425hz

delete_01

discardingapp_01

down2

dtmf_0

dtmf_1

dtmf_2

dtmf_3

dtmf_4

dtmf_5

dtmf_6

dtmf_7

dtmf_8

dtmf_9

browser_01

card_01

card_02

card_03

card_04

card_05

dtmf_asterisk

dtmf_pound

error_01

error_02

error_03

focusing

launch_01

launch_02

launch_03

pagebacwards

pageforward_01

shuffle_02

shuffle_03

shuffle_04

shuffle_05

shuffle_06

shuffle_07

shuffle_08

shuffling_01

shutter

switchingapps_01

switchingapps_02

switchingapps_03

tones_3beeps_otasp_done

unassigned

up2


Video

palm://com.palm.applicationManager

The Video application can be launched through the Application Manager service.

Method: launch

Launches the Video application to play or stream the file located at the target URI, downloading it first if not already on the device. If a URI is not specified, it will launch the video player to its normal starting scene.

Parameters

Type

Description

id

String

Set to 'com.palm.app.videoplayer'

params

Object

Includes a single property:

  target

String

URL of the form rtsp://video-file, where video-file is a well-formed URI targeting a video file encoded in a supported video format

  videoTitle

String

The name of the video to be displayed to the user

  thumbURL

String

The URL of a thumbnail to be displayed while the video is loading

Response

Type

Description

None

  

Controller APIs

This section includes the application, stage, and scene controller methods used in the book. These are just a subset of the APIs available; refer to the Palm SDK for a complete list of the available APIs.

Each entry includes a very brief description, followed by an enumeration of the arguments used in the method call.

Mojo.Controller.AppController.createStageWithCallback(stageArguments, onCreate, optionalStageType)

Method to create a new stage and be called back when the stage is loaded.

Arguments

Type

Description

stageArguments

String or Object

If a string, the name of the new stage; if a stage exists with this name, its contents will be replaced; if an object, it must have a name property containing the stage name and may have an assistantName property to specify the stage assistant and a height property to specify the height of a pop-up alert

onCreate

Function

A function that is called once the new stage is fully loaded; it is passed the new stage controller as its first parameter

optionalStageType

String

The type of stage to create: 'card', 'dashboard', 'popup', or 'banner'

Returns

Type

Description

None

  

Mojo.Controller.AppController.getActiveStageController(stageType)

Method to return the first currently focused stage’s controller.

Arguments

Type

Description

stageType

String

The type of stage to return: 'card', 'dashboard', 'popup', or 'banner'

Returns

Type

Description

stageController

Object

The stage controller for the active stage

Mojo.Controller.AppController.getScreenOrientation()

Method to return the device orientation.

Arguments

Type

Description

None

String

 

Returns

Type

Description

orientation

String

The orientation of the device: 'up', 'down', 'left', or 'right'

Mojo.Controller.AppController.getStageController(stageName)

Method to get the stage controller for a stage.

Arguments

Type

Description

stageName

String

The name of the stage

Returns

Type

Description

stageController

Object

Mojo.Controller.AppController.getStageProxy(stageName)

Function to get a controller or proxy object for a stage. Returns the stage controller if available, but if the stage is still in the process of being created, a proxy object will be returned instead. This proxy implements delegateToSceneAssistant(), and will delegate the calls as expected when the stage is available.

Arguments

Type

Description

stageName

String

The name of the stage

Returns

Type

Description

stageProxy/
stageController

Object

Returns the stage controller if available, but if the stage is still in the process of being created, a proxy object will be returned instead

Mojo.Controller.AppController.sendToNotificationChain(notificationData)

Sends the passed-in notification data to everyone in the commander stack of the focused window (usually the scene assistant, stage assistant, and application assistant), calling considerForNotification(), if present, on each.

Arguments

Type

Description

notificationData

Object

JSON object with payload of notification

Returns

Type

Description

None

  

Mojo.Controller.AppController.showBanner(bannerParams, launchArguments, category)

Shows the message text from the bannerParams in the banner area. The launchArguments will be used to launch or relaunch the application if the banner is touched.

Arguments

Type

Description

bannerParams

String or Object

Can be a string, in which case it is simply message text, or an object with the following properties: messageText (text to display), soundClass (string containing the sound class to use), soundFile (partial or full path to a sound file to play), and icon (partial or full path to an icon to show)

launchArguments

Varies

Arguments sent to the application when it is launched or relaunched if the banner is touched

category

String

Value defined by the application; used if you have more than one kind of banner message; since banners are displayed for a fixed length of time (five seconds currently), they can back up if there are more requests made than time to display them—if there is more than one banner notification within a named category, the framework will discard all but the last of them

Returns

Type

Description

None

  

Mojo.Controller.SceneController.listen(element, eventType, callback, onCapture)

Wrapper around Mojo.Event.listen that additionally will call get() on the element parameter if it is a string, converting it to a DOM node.

Arguments

Type

Description

element

String or Element

An element reference or DOM ID string identifying the target element

eventType

String

String identifier for the event type

callback

Function

Function object to be called when the event occurs

onCapture

Boolean

Pass true to listen during the capture phase, false to listen during bubbling

Returns

Type

Description

None

Mojo.Controller.SceneController.get(elementId)

If the elementId is a string, calls document.getElementById() with that string and returns the result. Otherwise, it returns elementId.

Arguments

Type

Description

elementid

String

An element reference or DOM ID string identifying the target element

Returns

Type

Description

element

Element

Element referenced by elementId

Mojo.Controller.SceneController.removeRequest(request)

Removes a request from the scene’s list of requests to manage; once a scene is popped this will no longer clear the request.

Arguments

Type

Description

request

Object

A request object, typically the one returned from a serviceRequest() call

Returns

Type

Description

None

  

Mojo.Controller.SceneController.serviceRequest(url, options, resubscribe)

Creates a Palm service request that will be automatically cancelled when the scene is popped. The parameters are passed directly to new Mojo.Service.Request().

Arguments

Type

Description

url

String

URI-formatted service name

options

Object

Service-dependent arguments

resubscribe

Boolean

If set to true, will automatically resubscribe when receiving an error from the service

Returns

Type

Description

request

Object

A request object, important for requests that persist beyond scene’s life or to be able to remove the request

Mojo.Controller.SceneController.setupWidget(name, attributes, model)

Registers the given attributes and model to be used with the widget of the given name. Called by scene assistants in their setup methods.

Arguments

Type

Description

name

String

Element ID for a div in which the widget is declared

attributes

Object

Widget attributes; specific contents are dependent on the widget

model

Object

Widget model; specific contents are dependent on the widget

Returns

Type

Description

None

  

Mojo.Controller.SceneController.stopListening(element, eventType, callback, onCapture)

Wrapper around Mojo.Event.stopListening that additionally will call get() on the element parameter if it is a string, converting it to a DOM node.

Arguments

Type

Description

element

String or Element

An element reference or DOM ID string identifying the target element

eventType

String

String identifier for the event type

callback

Function

Function object passed in previous call to listen()

onCapture

Boolean

Pass true if it was listening during the capture phase; false if it was listening during bubbling

Returns

Type

Description

None

  

Mojo.Controller.StageController.activate()

Activates this stage, similar to window.focus(). Causes card windows to be maximized.

Arguments

Type

Description

None

  

Returns

Type

Description

None

  

Mojo.Controller.StageController.activeScene()

Returns the currently active scene from this stage, if any. If no scenes are active, it returns undefined.

Arguments

Type

Description

None

  

Returns

Type

Description

sceneController

Object

The scene controller for the active scene

Mojo.Controller.StageController.deactivate()

Deactivates this stage. Causes card windows to be minimized.

Arguments

Type

Description

None

  

Returns

Type

Description

None

  

Mojo.Controller.StageController.delegateToSceneAssistant(functionName)

Use to call a method on the assistant of the current scene of this stage. The first parameter is the name of the property that contains the function to call. The remaining parameters are passed to that function. The this keyword is bound to the scene assistant for this call; any additional arguments will be passed to the scene assistant’s method.

Arguments

Type

Description

functionName

Function

Function to be called within the active scene

Returns

Type

Description

None

  

Mojo.Controller.StageController.getScenes()

Returns an array of scene controllers currently on the stack.

Arguments

Type

Description

None

  

Returns

Type

Description

results

Array

Array of scene controllers with the bottom scene on the stack at result[0]

Mojo.Controller.StageController.getWindowOrientation()

Gets the orientation of the stage’s window.

Arguments

Type

Description

None

  

Returns

Type

Description

orientation

String

The orientation of the device: 'up, 'down, 'left', or 'right'

Mojo.Controller.StageController.popScene(returnValue, options)

Removes a scene from the scene stack, passing the return value to the newly revealed scene’s activate method. Note that this is an asynchronous operation. Any additional arguments are also passed to the new scene.

Arguments

Type

Description

returnValue

Object

Passed to the newly activated scene

Returns

Type

Description

None

  

Mojo.Controller.StageController.popScenesTo(targetScene, returnValue, options)

Removes scenes from the scene stack until the target scene is reached, or no scenes remain on the stack. targetScene may be either the SceneController for the desired scene, the scene DOM ID, or the scene name. If targetScene is undefined, all scenes will be popped. Intermediate popped scenes are not reactivated, nor is there any visual transition to signify their removal from the stack. This is an asynchronous operation.

Arguments

Type

Description

targetScene

String or Element

Name or DOM ID of scene to be activated

returnValue

Object

Passed to the newly activated scene

Returns

Type

Description

None

  

Mojo.Controller.StageController.pushScene(sceneArguments)

Pushes a new scene; the Scene Lifecycle initial setup includes this function. This is an asynchronous operation.

Arguments

Type

Description

sceneArguments

String or Element

Either the name of the scene to push or an object with properties including the name of the scene and the ID to use as a DOM ID; all additional arguments are passed to the constructor of the next scene’s assistant

Returns

Type

Description

None

  

Mojo.Controller.StageController.setWindowOrientation(orientation)

Sets the orientation of the stage’s window.

Arguments

Type

Description

orientation

String

The orientation of the device: 'free', 'up', 'down', 'left' or 'right'

Returns

Type

Description

None

  

Mojo.Controller.StageController.swapScene(sceneArguments)

Pops the current scene and simultaneously pushes a new scene without activating and deactivating any underlying scenes. Note that this is an asynchronous operation.

Arguments

Type

Description

sceneArguments

String or Element

Either the name of the scene to push or an object with properties including the name of the scene and the ID to use as a DOM ID; all additional arguments are passed to the constructor of the next scene’s assistant

Returns

Type

Description

None

  

Mojo.Controller.StageController.topScene()

Returns the topmost scene from this stage.

Arguments

Type

Description

None

  

Returns

Type

Description

sceneController

Object

The scene controller for the top scene

If you enjoyed this excerpt, buy a copy of Palm webOS.