# Mojo.Controller.AppController

## Class Detail

The application controller is responsible for creating the application assistant and providing the interfaces for creating and managing stages. The following describes the class - the controller will get instantiated for you. You can get the instance of the controller with Mojo.Controller.getAppController().The controller object is typically accessed using this.controller.

## Method Summary

- Mojo.Controller.AppController.closeAllStages()
- Mojo.Controller.AppController.closeStage(stageName)
- Mojo.Controller.AppController.createStageWithCallback(stageArguments, onCreate, optionalStageType)
- Mojo.Controller.AppController.getActiveStageController(stageType)
- Mojo.Controller.AppController.getScreenOrientation()
- Mojo.Controller.AppController.getStageController(stageName)
- Mojo.Controller.AppController.getStageProxy(stageName)
- Mojo.Controller.AppController.launch(appId, params, onSuccess, onFailure)
- Mojo.Controller.AppController.open(params, onSuccess, onFailure)
- Mojo.Controller.AppController.playSoundNotification(soundClass, soundFile, duration)
- Mojo.Controller.AppController.removeAllBanners()
- Mojo.Controller.AppController.removeBanner(category)
- Mojo.Controller.AppController.sendToNotificationChain(notificationData)
- Mojo.Controller.AppController.showBanner(bannerParams, launchArguments, category)

## Method Detail

### Mojo.Controller.AppController.closeAllStages()

Function to close all stages.

### Mojo.Controller.AppController.closeStage(stageName)

Function to close a stage.

#### Parameter

{String} stageName The name of the stage.

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

Method to create a new stage and be called back when the stage is loaded. You can bind as much data to your callback function as needed, eliminating the need to pass parameters in the URI. The callback function can use the passed-in stage controller to push the first scene.

#### Parameters

- {String|Object} stageArguments - If a string, the name of the new stage. If a stage exists with this name, its contents will be replaced. If an object, supported properties are:

  Property | Type | Required | Description
  --- | --- | --- | ---
  name | string | Required | Stage name
  assistantName | string | Optional | Name of stageAssistant
  htmlFilePath | string | Optional | Path to initial HTML file of the new stage. Only valid if htmlFileName is specified.
  htmlFileName | string | Optional | The file name of the HTML file of the new stage.
  lightweight | boolean | Optional | Defines stage as a lightweight stage. Should always be set to true.
  height | integer | Optional | Popup stages only. Height of stage in pixels.
  clickableWhenLocked | boolean | Optional | Dashboard stages only. Allows dashboard to receive tap events when locked.

  If you call createStageWithCallback without specifying `htmlFileName`, the new stage will use the application's main HTML file (which defaults to index.html in the application's root directory, but may be specified in the `appinfo.json` file).

  If you specify `htmlFileName` without `htmlFilePath`, the framework will look in the application's root directory for a file with the specified name.

  By providing both `htmlFilePath` and `htmlFileName`, you can specify an HTML file anywhere in your application's directory structure. When specifying `htmlFilePath`, you should use `Mojo.appPath` to get your app's root directory and append the remainder of the desired path. For example, you could set `htmlFilePath` to `Mojo.appPath + "rest/of/path"` and `htmlFileName` to `"file"`.

- {Function} onCreate - A function that is called once the new stage is fully loaded. It is passed the new stage controller as its first parameter.

- {String} optionalStageType - The type of stage to create. See Mojo.Controller.StageType in controller.js for legal values.

### Mojo.Controller.AppController.getActiveStageController(stageType)

    Function to return the first currently focused stage.

#### Parameter

{String} stageType - optional parameter to limit the focused stage returned to the specified type. See Mojo.Controller.StageType for details on stageType.

### {string} Mojo.Controller.AppController.getScreenOrientation()

Returns the current orientation of the physical screen.

#### Returns

{string} one of 'up', 'down', 'left', or 'right'.

### Mojo.Controller.AppController.getStageController(stageName)

Function to get the stage controller for a stage. Returns undefined if the stage does not exist, or is not yet fully constructed.

#### Parameter

{String} stageName - The name of the stage.

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

#### Parameter

{String} stageName - The name of the stage.

### {Object} Mojo.Controller.AppController.launch(appId, params, onSuccess, onFailure)

Launch another application, with optional parameters.

#### Parameters

- {String} appId - Application ID of application to launch.
- {Object} params - Launch parameters to send to the launched application.
- {Function} onSuccess - Function that is called if the launch is successful. Default is to do nothing.
- {Function} onFailure - Function that is called if the launch fails. Default is to do nothing.

#### Returns

The Mojo.Service.Request object used to make the launch request.

### {Object} Mojo.Controller.AppController.open(params, onSuccess, onFailure)

Launch an application appropriate for "opening" the data indicated in the launch parameters.

#### Parameters

- {Object} params - Launch parameters to send to the opening application
- {Function} onSuccess - Function that is called if the open is successful. Default is to do nothing.
- {Function} onFailure - Function that is called if the open fails. Default is to do nothing.

#### Returns

The Mojo.Service.Request object used to make the launch request.

### Mojo.Controller.AppController.playSoundNotification(soundClass, soundFile, duration)

Immediately play a notification sound. Note that soundClass should be set to "notifications". If you need the device to vibrate, set soundClass to "vibrate".

#### Parameters

- {String} soundClass - class of the sound
- {String} soundFile - partial or full path to the sound file
- {String} duration - duration of sound in ms

### Mojo.Controller.AppController.removeAllBanners()

Remove all pending banner messages from the banner area. Will not remove messages that are already displayed.

### Mojo.Controller.AppController.removeBanner(category)

Remove a banner from the banner area. The category parameter defaults to 'banner'. Will not remove messages that are already displayed.

#### Parameter

{String} category - Value defined by the application and usually same one used in showBanner. It is used if you have more than one kind of banner message.

### Mojo.Controller.AppController.sendToNotificationChain(notificationData)

Hand the passed-in notification data to everyone in the commander stack of the focused window (scene assistant, stage assistant, app assistant, usually), calling considerForNotification, if present, on each. Each assistant before the app assistant should return the notification data with any properties that aren't needed for building a notification removed. The app assistant can then use the remaining data (in its own considerForNotification function) to call showBanner or to create or update a dashboard stage.

#### Parameter

notificationData

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

Show 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. The category parameter defaults to 'banner'. New banners of each category will replace existing banners of the same category.

#### Parameters

- {String|object} bannerParams - Can be either a string, in which case it is simply message text, or an object with the following properties:

  Property | Description
  --- | ---
  messageText | text to display
  soundClass | string containing the sound class to use
  soundFile | partial or full path to a sound file to play
  icon | partial or full path to an icon to show
  soundDuration | duration of sound in milliseconds

- {String} launchArguments - Arguments sent to the application when it is launched or relaunched if the banner is touched.

- {String} category - Value defined by the application. It is used if you have more than one kind of banner message. Without categories, any banner shown would replace an existing banner that had not yet been shown.