Class Detail

This section describes the Mojo.Controller.SceneController class. This is a constructor that is instantiated for you, and typically accessed using this.controller.



Method Summary



Constants for standard pushContainer layers.

Method Detail


Utility function to tell listening widgets to commit themselves


Enables and disables full screen mode for the scene. This property is persistent for each scene, so it is not necessary for client code to manage it.



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



Returns the automatically created scene scroller.


Used to notify widgets that a div containing widgets has changed visibility to 'display:none'. This is important for getting correct measurements where widgets are dependent upon them for drawing.


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.


Mojo.Controller.SceneController.modelChanged(model, who)

Scene assistants can call this method when their data changes and a widget displaying that data needs to be updated.

'who' is used to avoid notifying objects of their own changes to a model, in the case where both the scene assistant and widget change and watch the same model.



Popup submenus can be used to offer a transient textual list of choices to the user. It accepts standard menu models, but a few additional properties are supported.

You can create them dynamically as shown in the example below.


sceneController.popupSubmenu(this.controller, {
  items: [{label: $L('Apply'), command: 'apply-cmd'},
      {label: $L('Applique'), command: 'applique-cmd'},
      {label: $L('Applaud'), command: 'applaud-cmd'},
      {label: $L('Approximate'), command: 'approx-cmd'}]

A modal list will appear with the label choices presented. When the user taps one, the onChoose function will be called (in the scope of the scene assistant) with the command property of the chosen item. If the user taps outside the popup menu, it's still dismissed, and the onChoose function is called with undefined instead.

Additional model properties, beyond standard menus:

Property Description
onChoose Function, required.
Called when user makes a choice and the popup is dismissed.
placeNear Element, optional.
Used to position the popup menu near the triggering element.
toggleCmd Command from items array, optional.
Causes the appropriate item to appear with a check mark. Supported in top-level model for popups.
popupClass String, optional.
CSS class for the popup menu, referenced from the HTML templates.
scrimClass String, optional.
CSS class for the popup scrim. Defaults to 'submenu-popup'.
manualPlacement Boolean, optional.
If true, popup menu will not be placed automatically (centered, or near 'placeNear' element).

Additional menu item properties, beyond standard menus:

Property Description
secondaryIcon String, optional.
CSS class for a seconadry icon to display, generally used for some kind of status, and appearing to the left of the menu item.
secondaryIconPath String, optional.
Just like iconPath, but for secondaryIcon.
chosen Boolean, optional.
Causes item to be styled as the selected item in a toggle group (displays a check mark, currently).

Note that while keyboard shortcuts are rendered, they are for display purposes only. Since the popupmenu widget is created dynamically, it cannot actually implement the shortcut functionality itself, so for true submenus this is handled by the menu system.

Mojo.Controller.SceneController.prepareTransition(transitionType, isPop)

Creates a Transition object that the caller can use to run a transition within the scene. Events to the scene are frozen and a snapshot of the scene's window is taken. Any processing to change the scene's state should be done prior to calling run() on the returned Mojo.Transition object. Once run() is called, events will flow to the scene again.

This code example must run within a scene, e.g., when a change in toggle state results in the scene changing significantly.

var transition = this.controller.prepareTransition(Mojo.Transition.crossFade, false);
// Code setting up the scene's new state goes here;



Adds the given commander to the top of this SceneController's stack. The commanders in this stack are only used when this scene is the current scene.


Mojo.Controller.SceneController.pushContainer(container, layer, options)

Pushes a new container on the container stack for this scene. Mojo.Event.key* events are sent to the top container. When a new container is pushed, all containers with lower or same layer will be cancelled if they specify a cancelFunc in their options.



Removes a commander from the commander stack.



Removes the given container element from the stack. Returns true if it was successfully removed.



Removes a request from the scene's list of requests to manage. A removed request will not be cancelled when the scene is popped, and unless another reference is kept to the request, it can be garbage collected (and thus cancelled) at any time.


Mojo.Controller.SceneController.removeWatcher(watcher, model)

Removes a "model watch" for the given watcher. If 'model' is undefined, then all registered "model watches" for the given watcher are removed.

Used by the framework when re-rendering HTML that includes Mojo widgets, so that the old/removed widgets are not notified of changes to models.


{Object} Mojo.Controller.SceneController.serviceRequest(url, options, resubscribe)

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



A Mojo.Service.Request object


Sets the default transition to be used for pushing and popping this scene. This transition will be used when not overridden by an option specified when pushing or popping the scene.



Called by the scene assistant during setup to set the element that should be focused.


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. If a model is specified here for a widget that is rendered in a list item, the model will be overridden by the one for the list item.


{Function} Mojo.Controller.SceneController.setUserIdleTimeout(element, func, delay, watchMouse, watchKeys)

Utility function to call an idle handler when the user has been idle for a given amount of time. Once set, the timeout will remain dormant until the user has been continuously idle for the given delay in milliseconds.



{Function} Calling the returned function will cancel the idle timeout.

Mojo.Controller.SceneController.setWidgetModel(widget, model)

Sets the model for a widget, and notifies the widget of the new model.

The widget can be specified by either the DOM element or the id, since we operate on $(widget). Unlike setupWidget(), this API cannot operate on a widget name, since it is intended to operate on single widget only. The setup associated with the widget is not modified.



Used to notify widgets that a div containing widgets has changed visibility to be shown. This is important for getting correct measurements where widgets are dependent upon them for drawing.


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.



Returns the top container in this scene.


Enables and disables receiving 'page up' and 'page down' key events in response to the "swipe" gesture when the scene is in landscape mode, instead of the "back" signal. This property is persistent for each scene, so it is not necessary for client code to manage it.


Mojo.Controller.SceneController.watchModel(model, who, changeFunc)

Signs up for change notifications for the given model.

When someone calls modelChanged with the model of interest, the changeFunc will be called. Usually used by the framework to notify widgets when their models change.

'who' is the object owning the changeFunc. This is used to ensure that objects are not notified of their own changes to the model, and also changeFunc will be called in the context of 'who'.