FirefoxOS SystemApp API documentation

Index

AppWindow

new AppWindow()

AppWindow creates, contains, manages a mozbrowser iframe. AppWindow is directly managed by AppWindowManager, by call resize(), open(), close() on AppWindow.

Basically AppWindow would manipulate all mozbrowser events fired from the mozbrowser iframe by itself and show relevant UI.

AppWindow is also the parent class of ActivityWindow and HomescreenWindow. Mostly they do the same thing but is different at some points like the way transitioning.

About creating an AppWindow, you need to provide at least the web app/page URL. If you have also provided the manifest, then you would get an AppWindow object which is a web app. Otherwise you would get an AppWindow which is in 'Wrapper' type. The only one different thing between web app and web page is just the manifestURL.

Example
var app = new AppWindow({
  url: 'http://uitest.gaiamobile.org:8080/index.html',
  manifestURL: 'http://uitest.gaiamobile.org:8080/manifest.webapp'
});
app.open();

Mixes In

Members

_screenshotBlob

A temp variable to store current screenshot blob. We should store the blob and create objectURL once we need to display the image, and revoke right away after we finish rendering the image.

_screenshotOverlayState

Represent the current screenshoting state, i.e. what is currently visible. Possible value: 'frame': the actual app iframe 'screenshot': the screenshot overlay, serve as a placeholder for visible but not active apps. 'none': nothing is currently visible.

_visibilityState

Represent the current pagee visibility state, i.e. what is currently visible. Possible value: 'foreground': setVisible(true) 'background': setVisible(false)

Default value is foreground.

eventPrefix :String

Event prefix presents the object type when publishing an event from the element. Always 'app' for now.

rotatingDegree

The rotating degree of current frame.

Methods

static addMixin(mixin)

Mixin the appWindow prototype with {mixin} object.

Parameters:
Name Type Description
mixin Object

The object to be mixed.

_changeState(type, state)

Modify an attribute on this.element

Parameters:
Name Type Description
type String

State type.
state String

State name.

_hideFrame()

_hideFrame will check |this._screenshotOverlayState| and then turn off the frame visibility. So this shouldn't be invoked by others directly.

_hideScreenshotOverlay()

Check if current visibility state is screenshot or not, to hide the screenshot overlay.

_render()

Render the mozbrowser iframe and some overlays.

_showFrame()

_showFrame will check |this._screenshotOverlayState| and then turn on the frame visibility. So this shouldn't be invoked by others directly.

_showScreenshotOverlay()

Show screenshot overlay and hide the iframe.

close(animation)

Close the window; the detail is done in appTransitionController.

Parameters:
Name Type Description
animation String

The animation class name

destroy()

Destroy the instance.

Fires:

generateID()

Generate instanceID of this instance.

handleEvent(evt)

General event handler interface. Child classes shouldn't change this.

Parameters:
Name Type Description
evt DOMEvent

The event

isFullScreen() → {Boolean}

Detect whether this is a full screen app by its manifest.

Returns:
Boolean

We're a fullscreen app or not.

isTransitioning() → {Boolean}

TODO: Swipe transition.

Returns:
Boolean

[description]

modifyURLatBackground(url)

Change URL only when we're at background.

Parameters:
Name Type Description
url String

URL.

open(animation)

Open the window; the detail is done in appTransitionController.

Parameters:
Name Type Description
animation String

The animation class name

publish(event, detail)

Publish an event.

Parameters:
Name Type Description
event String

Event name, without object type prefix.
detail Object

Parameters in JSON format.

ready(callback)

Do resize and/or ensure repaint before opening the app.

Parameters:
Name Type Description
callback function

Callback when app is ready to be opened.

reConfig(configuration)

Generate all configurations we need.

Parameters:
Name Type Description
configuration Object

Initial configuration object Includes manifestURL, manifest, url, origin, name

requestClose()

The app window is requesting to be closed.

Fires:

requestOpen()

The app window is requesting to be opened.

Fires:

requestScreenshotURL()

Request a screenshot ObjectURL temporarily. The image would be discarded after 200ms or the revoke callback is invoked.

resize()

Set the size of the app's iframe to match the size of the screen. We have to call this on resize events (which happen when the phone orientation is changed). And also when an app is launched and each time an app is brought to the front, since the orientation could have changed since it was last displayed

An appWindow instance only resizes if it's active. Since we already pre-config the size in window.css, if an app is launched by system message we don't need to resize it.

setFrameBackground()

Set splash as our inital background. If the content is loaded then just skip.

setVisible()

In order to prevent flashing of unpainted frame/screenshot overlay during switching from one to another, many event listener & callbacks are employed.

  1. Switching from 'frame' to 'screenshot' state: _showScreenshotOverlay() is called get screenshot from frame when getting the screenshot, show the screenshot overlay and hide the frame

  2. Switching from 'screenshot' to 'frame' state: _showFrame() is called register next paint listener, and set the frame to visible finally, when next painted, hide the screenshot

  3. Switching from 'none' to 'frame' state: _showFrame() is called

  4. Switching from 'frame' to 'none' state: _hideFrame() is called

  5. Switching from 'none' to 'screenshot' state: get screenshot from frame when getting the screenshot, show the screenshot overlay

  6. Switching from 'screenshot' to 'none' state: _hideScreenshotOverlay is called

tryWaitForFullRepaint()

Wait for a full repaint of the mozbrowser iframe.

Events

appclose

Fired when the app's closing animation is ended.

appclosing

Fired when the app is doing closing animation.

appcreated

This is fired when the app window is instantiated.

appdestroyed

Fired after the instance id destroyed.

appopen

Fired when the app's opening animation is ended.

appopening

Fired when the app is doing opening animation.

apprendered

Fired after the app window element is appended to the DOM tree.

apprequestclose

Fired once we'd like to be closed. The one who makes decision to call close() would be AppWindowManager.

apprequestopen

Fired once we'd like to be opened. The one who makes decision to call open() would be AppWindowManager.

appresize

Fired when the app is resized.

appterminated

Fired when the instance is terminated.

appwilldestroy

Fired before the instance id destroyed.

appwillrender

Fired before this element is appended to the DOM tree.

_swipein

The event is necessary for edge gesture swiper. It means the app window is swiped in.

_swipeout

The event is necessary for edge gesture swiper. It means the app window is swiped out.

_withkeyboard

The event is dispatched on the app window only when keyboard is up.

_withoutkeyboard

The event is dispatched on the app window only when keyboard is hidden.