# Child

Namespace dealing with child windows.

webOS offers a much richer experience than the standard web browser. An important part of this experience is the ability to notify the user of events without bringing the full application to the foreground or blocking the current activity of the user. Another aspect is the ability to open new windows, allowing you to keep your place in the parent window while doing work in a child.

Not surprisingly, these added features are just regular browser windows similar to what you get when you call `window.open` in the web browser. Unlike most browsers, however, webOS does not prevent these windows from being opened.

The API in this namespace makes dealing with the different types of child windows offered by webOS as painless as possible.

## Child.Types Namespace

The various window types that are supported by webOS.

## Constants

### Child.Types.card

A card window is the default card type. It is a fullscreen window. Most simple apps are just a single card window.

### Child.Types.dashboard

A dashboard window is a small window that alerts the user that something interesting happened. It is persistent in that a small icon will be present in the notification area until the user taps on the icon (which brings it to full size) and dismisses the dashboard by flicking it off the screen.

### Child.Types.dockMode

A dockMode stage is a stage that is used when the device is on the touchstone charging dock.

### Child.Types.popupAlert

A popupAlert is an urgent dialog that pops up under whatever the user is currently doing. It is normally used for high priority interactions such as calendar alerts.

## Classes

### Child.Banner

Created through `Child.createBanner` only.

#### Instance Methods

##### Child.Banner#close

>     Child.Banner#close() -> undefined

Closes a banner (i.e., removes the banner text from the screen).

## Class Methods

### Child.createBanner

>     Child.createBanner(message[, options]) -> Child.Banner

- `message (String)` – The message to display in the banner.
- `options (Object)` – An object containing the plethora of optional banner features.

A banner is a line of text that temporarily appears at the bottom of the user's screen. It can be accompanied by a sound to grab the user's attention. When the banner is tapped, it relaunches your app (optionally with additional parameters).

Options is an object that may (or may not) contain any of the following properties:

- `icon`: A path to an icon to display next to the text, relative to the root of the running app. Defaults to a miniature version of your application icon.

- `launchArguments`: An object that will be passed to your application's relaunch method when the banner is tapped.

- `sound`: An object that may contain the following:
  - `path`: The path to the sound file, relative to the running app.
  - `audioClass`: The class of the sound file.
  - `duration`: The length of time to play the sound in milliseconds.

### Child.createWindow

>     Child.createWindow(url, name, features, attributes) -> window

- `url (String)` – An X/HTML file to render in the new card.
- `name (String)` – The name of the new card.
- `features (Object)` – A key/value pairing of standard window features
- `attributes (Object)` – A key/value pairing of Mojo window attributes

Creates a child window. The available child window types are specified in `Child.Types`

`features` is an object consisting of standard browser window features. The vast majority of window features are not supported, nor do they make sense on webOS. This is largely included to future-proof the API. Currently, the one supported feature is:

- `height (Number)`: Ignored by many window types, popup alerts allow the developer to customize the window height.

`attributes` is an object consisting of Mojo specific window features. Currently, the supported Mojo feature is:

- window: Specifies the window type. Valid values are the constants defined in Child.Types. Defaults to Child.Types.card if unspecified.

#### Example

>     MojoCore.Child.createCard(url, name, { height: 150 },
>       { window: MojoCore.Child.Types.popupAlert }
>     );

Returns the newly created window reference, which, as a DOM level 0 object, is most completely documented by Mozilla.

This window has been properly set up to work with webOS-specific events.