# Mojo.Controller.SceneController

## 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.

## Summary

Mojo.Controller.SceneController.sceneContainerLayer

## Method Summary

- Mojo.Controller.SceneController.commitChanges()
- Mojo.Controller.SceneController.enableFullScreenMode(yesNo)
- Mojo.Controller.SceneController.get(elementId)
- Mojo.Controller.SceneController.getSceneScroller()
- Mojo.Controller.SceneController.hideWidgetContainer(elementOrId)
- Mojo.Controller.SceneController.listen(element, eventType, callback, onCapture)
- Mojo.Controller.SceneController.modelChanged(model, who)
- Mojo.Controller.SceneController.popupSubmenu()
- Mojo.Controller.SceneController.prepareTransition(transitionType, isPop, transitionType, isPop)
- Mojo.Controller.SceneController.pushCommander(cmdr)
- Mojo.Controller.SceneController.pushContainer(container, layer, options)
- Mojo.Controller.SceneController.removeCommander(cmdr)
- Mojo.Controller.SceneController.removeContainer(container)
- Mojo.Controller.SceneController.removeRequest(request)
- Mojo.Controller.SceneController.removeWatcher(watcher, model)
- Mojo.Controller.SceneController.serviceRequest(url, options, resubscribe)
- Mojo.Controller.SceneController.setDefaultTransition(transitionType)
- Mojo.Controller.SceneController.setInitialFocusedElement(focusedElement)
- Mojo.Controller.SceneController.setupWidget(name, attributes, model)
- Mojo.Controller.SceneController.setUserIdleTimeout(element, func, delay, watchMouse, watchKeys)
- Mojo.Controller.SceneController.setWidgetModel(widget, model)
- Mojo.Controller.SceneController.showWidgetContainer(elementOrId)
- Mojo.Controller.SceneController.stopListening(element, eventType, callback, onCapture)
- Mojo.Controller.SceneController.topContainer()
- Mojo.Controller.SceneController.useLandscapePageUpDown(yesNo)
- Mojo.Controller.SceneController.watchModel(model, who, changeFunc)

## Detail

### Mojo.Controller.SceneController.sceneContainerLayer

Constants for standard pushContainer layers.

## Method Detail

### Mojo.Controller.SceneController.commitChanges()

Utility function to tell listening widgets to commit themselves

### Mojo.Controller.SceneController.enableFullScreenMode(yesNo)

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.

#### Parameter

{bool} yesNo - is 'true' to enable and 'false' to disable full screen mode for just this scene.

### Mojo.Controller.SceneController.get(elementId)

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

#### Parameter

{String|Element} elementId - DOM Element reference or string

### Mojo.Controller.SceneController.getSceneScroller()

Returns the automatically created scene scroller.

### Mojo.Controller.SceneController.hideWidgetContainer(elementOrId)

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.

#### Parameter

elementOrId

### 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.

#### Parameters

- {String|Element} element - An elemement reference or DOM ID string identifying the target element.
- {String} eventType - String identifier for the event type.
- {Function} callback - Function object to be called when the event occurs.
- {Boolean} onCapture - (optional) Pass true to listen during the capture phase, false to listen during bubbling.

### 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.

#### Parameters

- {Object} model - Model object that changed
- {Object} who - Object responsible for changing it (usually the widget object or scene assistant).

### Mojo.Controller.SceneController.popupSubmenu()

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.

Example:

>     sceneController.popupSubmenu(this.controller, {
>       onChoose:this.popupChoose,
>       placeNear:clickEvent.target,
>       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
>     transition.run();

#### Parameters

- {string} transitionType Optional - Specifies the kind of transition to run, and may be one of Mojo.Transition.none, Mojo.Transition.zoomFade, Mojo.Transition.crossFade, or Mojo.Transition.defaultTransition.

- {bool} isPop Optional - Is true if the current scene is being popped, false otherwise.

### Mojo.Controller.SceneController.pushCommander(cmdr)

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.

#### Parameter

{Object} cmdr - commander to add.

### 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.

#### Parameters

- {Element} container - The new container.
- {string} layer - Constant for the layer of this container. Usually one of dialogContainerLayer or submenuContainerLayer.
- {object} options Optional - Object specifying optional arguments. May be omitted, or may contain a 'cancelFunc' property mapped to a function to be called when the container is cancelled.

### Mojo.Controller.SceneController.removeCommander(cmdr)

Removes a commander from the commander stack.

#### Parameter

{Object} cmdr - commander to remove.

### Mojo.Controller.SceneController.removeContainer(container)

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

#### Parameter

{Element} container - The container to remove.

### Mojo.Controller.SceneController.removeRequest(request)

Remove 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.

#### Parameter

{Object} request - Request to remove

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

Remove 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.

#### Parameters

- {Object} watcher - The object owning the changeFunc, when watchModel was called.
- {Object} model - Model name, or left undefined all registered "model watches" for the given watcher are removed.

### {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().

#### Parameters

- {String} url - url string of the service request
- {Object} options - options for the request
- {Boolean} resubscribe - pass true to automatically resubscribe when receiving an error from the service

#### Returns

A Mojo.Service.Request object

### Mojo.Controller.SceneController.setDefaultTransition(transitionType)

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.

#### Parameter

transitionType - {string} A transition name from Mojo.Transition

### Mojo.Controller.SceneController.setInitialFocusedElement(focusedElement)

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

#### Parameter

{String|Element|null} focusedElement - Pass null to prevent automatic focus, or an elementId or element to focus.

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

Register 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.

#### Parameters

- {Object} name
- {Object} attributes
- {Object} model

### {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.

#### Parameters

- {string} element - The element to watch for user events on. This can be the SceneController.sceneElement, or some element within the scene. The id or element itself is accepted.
- {function} func - This is the idle handler that will be called after the user has been idle for enough time.
- {int} delay - This is the amount of time in milliseconds to wait after the last user event before calling the idle handler.
- {boolean} watchMouse - If true, mouse events will be monitored and considered signs of user activity. Defaults to true if unspecified.
- {boolean} watchKeys - If true, key events will be monitored and considered signs of user activity. Defaults to true if unspecified.

#### Returns

{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.

#### Parameters

- {Object} widget
- {Object} model

### Mojo.Controller.SceneController.showWidgetContainer(elementOrId)

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.

#### Parameter

elementOrId

### 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.

#### Parameters

- {String|Element} element - An element reference or DOM ID string identifying the target element.
- {String} eventType - String identifier for the event type.
- {Function} callback - Function object that was registered to be called when the event occurred.
- {Boolean} onCapture Optional - Pass true to listen during the capture phase, false to listen during bubbling.

### Mojo.Controller.SceneController.topContainer()

Returns the top container in this scene.

### Mojo.Controller.SceneController.useLandscapePageUpDown(yesNo)

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.

#### Parameter

{bool} yesNo - is 'true' to enable and 'false' to disable receiving 'page up/down' key events for just this scene.

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

Sign 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'.

#### Parameters

- {Object} model - Model name.
- {Object} who - The object owning the changeFunc.
- {Object} changeFunc - Function called when modelChanged with the model of interest.