# Mojo.Controller.StageController

## Class Detail

This class provides methods to manipulate scenes on the stage. A stage is an HTML structure very similar to a standard browser window. A single application may have multiple stages and a single stage may contain multiple scenes.

This class is a constructor which gets instantiated for you, and is typically accessed using `this.controller`.

## Method Summary

- Mojo.Controller.StageController.activate()
- Mojo.Controller.StageController.activeScene()
- Mojo.Controller.StageController.deactivate()
- Mojo.Controller.StageController.delegateToSceneAssistant(functionName)
- Mojo.Controller.StageController.getAppController()
- Mojo.Controller.StageController.getScenes()
- Mojo.Controller.StageController.getWindowOrientation(orientation)
- Mojo.Controller.StageController.hasNewContent()
- Mojo.Controller.StageController.indicateNewContent(hasNew)
- Mojo.Controller.StageController.isActiveAndHasScenes()
- Mojo.Controller.StageController.isChildWindow()
- Mojo.Controller.StageController.loadStylesheet(path)
- Mojo.Controller.StageController.parentSceneAssistant(targetSceneAssistant)
- Mojo.Controller.StageController.popScene(returnValue, options)
- Mojo.Controller.StageController.popScenesTo(targetScene, options)
- Mojo.Controller.StageController.pushAppSupportInfoScene()
- Mojo.Controller.StageController.pushCommander(cmdr)
- Mojo.Controller.StageController.pushScene(sceneArguments)
- Mojo.Controller.StageController.removeCommander(cmdr)
- Mojo.Controller.StageController.sendEventToCommanders(event)
- Mojo.Controller.StageController.setClipboard(escapeHTML:, escapeHTML)
- Mojo.Controller.StageController.setWindowOrientation(orientation)
- Mojo.Controller.StageController.setWindowProperties(props)
- Mojo.Controller.StageController.swapScene(sceneArguments)
- Mojo.Controller.StageController.topScene()
- Mojo.Controller.StageController.unloadStylesheet(path)

## Method Detail

### Mojo.Controller.StageController.activate()

Programatically activates this stage. Causes card windows to be maximized.

### Mojo.Controller.StageController.activeScene()

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

### Mojo.Controller.StageController.deactivate()

Programatically deactivates this stage. Causes card windows to be minimized.

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

#### Parameters

{Object} functionName - name of property to use to get the function to call.

### Mojo.Controller.StageController.getAppController()

Returns the current application controller.

### Mojo.Controller.StageController.getScenes()

Returns an array of scene controllers currently on the stack. result[0] is the bottom scene on the stack.

### Mojo.Controller.StageController.getWindowOrientation(orientation)

Gets the orientation of the stage's window.

#### Parameters

{String} orientation - One of 'up', 'down', 'left' or 'right'

### {Boolean} Mojo.Controller.StageController.hasNewContent()

Returns true if the current stage has new content for the indicator, and false otherwise.

### Mojo.Controller.StageController.indicateNewContent(hasNew)

Makes the core navi button pulsate if true. This is mainly intended to alert the user to dashboard events that desire user attention.

#### Parameters

hasNew

#### Mojo.Controller.StageController.isActiveAndHasScenes()

Returns true if the stage is both active and has currently pushed.

### {Boolean} Mojo.Controller.StageController.isChildWindow()

Utility function to find out if the current window is a child window. Returns true for child windows.

### Mojo.Controller.StageController.loadStylesheet(path)

Loads a stylesheet -- and any versions of it for the current locale -- into the stage's document.

#### Parameters

{String} path - A path relative to the application's root directory, specifying the stylesheet to load.

### Mojo.Controller.StageController.parentSceneAssistant(targetSceneAssistant)

Returns the scene assistant of the scene above this scene in the scene stack, or undefined if there is no such scene.

#### Parameters

targetSceneAssistant

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

#### Parameters

- {Object} returnValue - Value passed to the next scene active method
- {Object} options - Optional object that can specify: { transition: @see Mojo.Transition }

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

Removes scenes from the scene stack until the target scene is reached, or there are no scenes remaining 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. Note that this is an asynchronous operation.

To avoid showing a transition to the scene if you're already on top, you can use this check:

>     if (myScene.stageController.topScene() !== myScene.controller) {
>       myScene.controller.stageController.popScenesTo(myScene.controller);
>     }

#### Parameters

- {Object} targetScene
- {Object} options - @see #popScene

### Mojo.Controller.StageController.pushAppSupportInfoScene()

#### Overview

This method pushes a scene containing application support information, populated with data gathered from the application's appinfo.json file. It uses the following basic properties from Mojo.appInfo:

- "version": version number of the application
- "vendor": the author of the application
- "vendorurl": the URL of the application author
- "title": the name of the application as it appears in the Launcher
- "smallicon": a 32-pixel-square version of the application's icon
- "copyright": the application's copyright statement

Additionally, this method uses a "support" property, which is an object containing at least one of the three following properties:

- "url": the URL specifically meant for obtaining support for the application
- "email": an object containing information for obtaining email-based support for the application. It must have an "address" property, and optionally a "subject" property:
  - "address": address for obtaining email-based support
  - "subject": an optional subject line for support emails
- "phone": a phone number for obtaining support

The "support" object can, optionally, contain a "resources" property; an array of objects with the following properties:

- "type": "web" or "scene", specifying a support resource that is web-based or an application scene, respectively
- "label": the text to display in the support scene for this resource
- "url": for "web" type resources only; the URL of the resource web page
- "sceneName": for "scene" type resources only; the name of the scene to launch for the resource

Here is an example appinfo.json:

>     {
>       "id": "com.mycompany.myapp",
>       "version": "1.0.0",
>       "vendor": "My Company",
>       "vendorurl": "http://www.mycompany.com",
>       "type": "web",
>       "main": "index.html",
>       "title": "My App",
>       "icon": "icon.png",
>       "smallicon": "icon32x32.png",
>       "copyright": "© Copyright 2009 My Company, Inc.",
>       "support": {
>           "url": "http://support.mycompany.com",
>           "email": {
>               "address": "support@mycompany.com",
>               "subject": "Support"
>           },
>           "phone": "555-555-5555",
>           "resources": [
>               {
>                   "type": "scene",
>                   "label": "Help Topics",
>                   "sceneName": "topics"
>               },
>               {
>                   "type": "web",
>                   "label": "Discussion Forums",
>                   "url": "http://forums.mycompany.com/"
>               }
>           ]
>       }
>     }

#### Function Call

>     this.controller.StageController.pushAppSupportInfoScene();

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

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

#### Parameters

{Object} cmdr

### Mojo.Controller.StageController.pushScene(sceneArguments)

Push a new scene; the Scene Lifecycle initial setup includes this function. Note that this is an asynchronous operation. An app calls StageController.pushScene('myScene'):

1. A div is created with the view HTML for the new scene, and inserted into the `<body>`.
2. A SceneController for 'myScene' is instantiated.
3. A scene assistant for 'myScene' is instantiated, if available.
4. The new scene is placed on the stage's scene stack then the Scene Controller and assistant's setup() methods are called and Widgets (divs that specify `x-mojo-element`) are created, rendered, and added to the DOM.

At this point, scene should now be ready for initial display, even if the app is waiting for a service request to complete to provide dynamic data to fill out the scene.

1. The StageController transitions the scene onto the stage.
2. When the transition is complete, the scene controller and assistant's activate method is called, and the scene is ready for action.

#### Parameters

{String|Object} sceneArguments - either the name of the scene to push, or an object with these properties: { name, assistantConstructor, sceneTemplate, [id] } Note that all additional arguments are passed to the constructor of the next scene's assistant.

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

Removes a commander from the commander stack.

#### Parameters

{Object} cmdr - commander to remove.

### Mojo.Controller.StageController.sendEventToCommanders(event)

Sends the given event through the entire command chain, starting with the CommanderStack in the current scene, and progressing to the StageController's stack if the current scene does not call event.stopPropagation().

#### Parameters

{Object} event

### Mojo.Controller.StageController.setClipboard(escapeHTML:, escapeHTML)

This allows the client application to send text to the clipboard to be pasted elsewhere later.

#### Parameters

- {Boolean} escapeHTML: - ignored in initial setClipboard api; later will allow pasting of rich text
- escapeHTML

### Mojo.Controller.StageController.setWindowOrientation(orientation)

Sets the orientation of the stage's window.

#### Parameters

{String} orientation - One of 'up', 'down', 'left', 'right', or 'free'

### Mojo.Controller.StageController.setWindowProperties(props)

Change properties of the window.

#### Parameters

{Object} props - A map representing the properties to change. Keys are the property names, and values are the new values. Possible values include:

- blockScreenTimeout - Boolean. If true, the screen will not dim or turn off in the absence of user activity. If false, the timeout behavior will be reinstated.

- setSubtleLightbar - Boolean. If true, the light bar will be made somewhat dimmer than normal. If false, it will return to normal.

- fastAccelerometer - Boolean. If true, the accelerometer rate will increase to 30mhz; false by default, rate is at 4hz. Note that fast rate is active only for apps when maximized.

### Mojo.Controller.StageController.swapScene(sceneArguments)

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

#### Parameters

{String|Object} sceneArguments - 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.

### Mojo.Controller.StageController.topScene()

Return the topmost scene from this stage.

### Mojo.Controller.StageController.unloadStylesheet(path)

Unloads a stylesheet -- and any versions of it for the current locale -- from the stage's document.

#### Parameters

{String} path - A path relative to the application's root directory, specifying the stylesheet to unload.