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

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.118.142.245