chrome.app.window

Description:	Use the `chrome.app.window` API to create windows. Windows have an optional frame with title bar and size controls. They are not associated with any Chrome browser windows.
Availability:	Stable since Chrome 23.

Summary

Types
ContentBounds
BoundsSpecification
Bounds
FrameOptions
AppWindow
Methods
create − `chrome.app.window.create(string url, object options, function callback)`
current − `AppWindow chrome.app.window.current()`
getAll − `array of AppWindow chrome.app.window.getAll()`
get − `AppWindow chrome.app.window.get(string id)`
Events
onBoundsChanged
onClosed
onFullscreened
onMaximized
onMinimized
onRestored

Types

ContentBounds

properties
integer	(optional) left
integer	(optional) top
integer	(optional) width
integer	(optional) height

BoundsSpecification

properties
integer	(optional) left	The X coordinate of the content or window.
integer	(optional) top	The Y coordinate of the content or window.
integer	(optional) width	The width of the content or window.
integer	(optional) height	The height of the content or window.
integer	(optional) minWidth	The minimum width of the content or window.
integer	(optional) minHeight	The minimum height of the content or window.
integer	(optional) maxWidth	The maximum width of the content or window.
integer	(optional) maxHeight	The maximum height of the content or window.

Bounds

properties

integer left This property can be used to read or write the current X coordinate of the content or window.

integer top This property can be used to read or write the current Y coordinate of the content or window.

integer width This property can be used to read or write the current width of the content or window.

integer height This property can be used to read or write the current height of the content or window.

integer (optional) minWidth This property can be used to read or write the current minimum width of the content or window. A value of null indicates 'unspecified'.

integer (optional) minHeight This property can be used to read or write the current minimum height of the content or window. A value of null indicates 'unspecified'.

integer (optional) maxWidth This property can be used to read or write the current maximum width of the content or window. A value of null indicates 'unspecified'.

integer (optional) maxHeight This property can be used to read or write the current maximum height of the content or window. A value of null indicates 'unspecified'.

function

setPosition

Set the left and top position of the content or window.

Parameters
integer	left
integer	top

function

setSize

Set the width and height of the content or window.

Parameters
integer	width
integer	height

function

setMinimumSize

Set the minimum size constraints of the content or window. The minimum width or height can be set to null to remove the constraint. A value of undefined will leave a constraint unchanged.

Parameters
integer	minWidth
integer	minHeight

function

setMaximumSize

Set the maximum size constraints of the content or window. The maximum width or height can be set to null to remove the constraint. A value of undefined will leave a constraint unchanged.

Parameters
integer	maxWidth
integer	maxHeight

FrameOptions

properties
string	(optional) type	Frame type: `none` or `chrome` (defaults to `chrome`). For `none`, the `-webkit-app-region` CSS property can be used to apply draggability to the app's window. `-webkit-app-region: drag` can be used to mark regions draggable. `no-drag` can be used to disable this style on nested elements.
string	(optional) color	Allows the frame color to be set. Frame coloring is only available if the frame type is `chrome`. Frame coloring is experimental and only available in dev channel.

AppWindow

properties

function focus Focus the window.

function fullscreen Fullscreens the window.
The user will be able to restore the window by pressing ESC. An application can prevent the fullscreen state to be left when ESC is pressed by requesting the app.window.fullscreen.overrideEsc permission and canceling the event by calling .preventDefault(), like this:
window.onKeyDown = function(e) { if (e.keyCode == 27 /* ESC */) { e.preventDefault(); } };

function isFullscreen Is the window fullscreen?
Returns boolean.

function minimize Minimize the window.

function isMinimized Is the window minimized?
Returns boolean.

function maximize Maximize the window.

function isMaximized Is the window maximized?
Returns boolean.

function restore Restore the window, exiting a maximized, minimized, or fullscreen state.

function

moveTo

Move the window to the position (|left|, |top|).

Parameters
integer	left
integer	top

function

resizeTo

Resize the window to |width|x|height| pixels in size.

Parameters
integer	width
integer	height

function drawAttention Draw attention to the window.

function clearAttention Clear attention to the window.

function close Close the window.

function

show

Show the window. Does nothing if the window is already visible. Focus the window if |focused| is set to true or omitted.

Parameters
boolean	(optional) focused

function hide Hide the window. Does nothing if the window is already hidden.

function getBounds Get the window's inner bounds as a ContentBounds object.
Returns ContentBounds.

function

setBounds

Set the window's inner bounds.

Parameters
ContentBounds	bounds

function isAlwaysOnTop Is the window always on top?
Returns boolean.

function

setAlwaysOnTop

Set whether the window should stay above most other windows. Requires the "app.window.alwaysOnTop" permission.

Parameters
boolean	alwaysOnTop

Window contentWindow The JavaScript 'window' object for the created child.

string id The id the window was created with.

Bounds innerBounds The position, size and constraints of the window's content, which does not include window decorations. Currently only available on the Dev channel from Chrome 35.

Bounds outerBounds The position, size and constraints of the window, which includes window decorations, such as the title bar and frame. Currently only available on the Dev channel from Chrome 35.

Methods

create


              chrome.app.window.create(string url, object options, function callback)

The size and position of a window can be specified in a number of different ways. The most simple option is not specifying anything at all, in which case a default size and platform dependent position will be used.

Another option is to use the bounds property, which will put the window at the specified coordinates with the specified size. If the window has a frame, it's total size will be the size given plus the size of the frame; that is, the size in bounds is the content size, not the window size.

To automatically remember the positions of windows you can give them ids. If a window has an id, This id is used to remember the size and position of the window whenever it is moved or resized. This size and position is then used instead of the specified bounds on subsequent opening of a window with the same id. If you need to open a window with an id at a location other than the remembered default, you can create it hidden, move it to the desired location, then show it.

Parameters

string url

object

(optional) options

string	(optional) id	Id to identify the window. This will be used to remember the size and position of the window and restore that geometry when a window with the same id is later opened. If a window with a given id is created while another window with the same id already exists, the currently opened window will be focused instead of creating a new window.
BoundsSpecification	(optional) innerBounds	Used to specify the initial position, initial size and constraints of the window's content (excluding window decorations). If an `id` is also specified and a window with a matching `id` has been shown before, the remembered bounds will be used instead. Note that the padding between the inner and outer bounds is determined by the OS. Therefore setting the same bounds property for both the `innerBounds` and `outerBounds` will result in an error. Currently only available on the Dev channel from Chrome 35.
BoundsSpecification	(optional) outerBounds	Used to specify the initial position, initial size and constraints of the window (including window decorations such as the title bar and frame). If an `id` is also specified and a window with a matching `id` has been shown before, the remembered bounds will be used instead. Note that the padding between the inner and outer bounds is determined by the OS. Therefore setting the same bounds property for both the `innerBounds` and `outerBounds` will result in an error. Currently only available on the Dev channel from Chrome 35.
integer	(optional) minWidth	Minimum width of the window.
integer	(optional) minHeight	Minimum height of the window.
integer	(optional) maxWidth	Maximum width of the window.
integer	(optional) maxHeight	Maximum height of the window.
string or FrameOptions	(optional) frame	Frame type: `none` or `chrome` (defaults to `chrome`). For `none`, the `-webkit-app-region` CSS property can be used to apply draggability to the app's window. `-webkit-app-region: drag` can be used to mark regions draggable. `no-drag` can be used to disable this style on nested elements. Use of `FrameOptions` is only supported in dev channel.
ContentBounds	(optional) bounds	Size and position of the content in the window (excluding the titlebar). If an id is also specified and a window with a matching id has been shown before, the remembered bounds of the window will be used instead.
boolean	(optional) transparentBackground	Enable window background transparency. Only supported in ash. Requires experimental API permission.
enum of `"normal"`, `"fullscreen"`, `"maximized"`, or `"minimized"`	(optional) state	The initial state of the window, allowing it to be created already fullscreen, maximized, or minimized. Defaults to 'normal'.
boolean	(optional) hidden	If true, the window will be created in a hidden state. Call show() on the window to show it once it has been created. Defaults to false.
boolean	(optional) resizable	If true, the window will be resizable by the user. Defaults to true.
boolean	(optional) singleton	singleton is deprecated. Multiple windows with the same id is no longer supported. By default if you specify an id for the window, the window will only be created if another window with the same id doesn't already exist. If a window with the same id already exists that window is activated instead. If you do want to create multiple windows with the same id, you can set this property to false.
boolean	(optional) alwaysOnTop	If true, the window will stay above most other windows. If there are multiple windows of this kind, the currently focused window will be in the foreground. Requires the `"app.window.alwaysOnTop"` permission. Defaults to false. Call `setAlwaysOnTop()` on the window to change this property after creation.
boolean	(optional) focused	If true, the window will be focused when created. Defaults to true.

function

(optional) callback

Called in the creating window (parent) before the load event is called in the created window (child). The parent can set fields or functions on the child usable from onload. E.g. background.js:
function(createdWindow) { createdWindow.contentWindow.foo = function () { }; };
window.js:
window.onload = function () { foo(); }

If you specify the callback parameter, it should be a function that looks like this:

function(AppWindow createdWindow) {...};

AppWindow

createdWindow

current


                  AppWindow
              chrome.app.window.current()

Returns an AppWindow object for the current script context (ie JavaScript 'window' object). This can also be called on a handle to a script context for another page, for example: otherWindow.chrome.app.window.current().

getAll


              array of     AppWindow
              chrome.app.window.getAll()

Gets an array of all currently created app windows. This method is new in Chrome 33.

get


                  AppWindow
              chrome.app.window.get(string id)

Gets an AppWindow with the given id. If no window with the given id exists null is returned. This method is new in Chrome 33.

Parameters
string	id

Events

onBoundsChanged

Fired when the window is resized.

addListener


                    chrome.app.window.onBoundsChanged.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`

onClosed

Fired when the window is closed.

addListener


                    chrome.app.window.onClosed.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`

onFullscreened

Fired when the window is fullscreened.

addListener


                    chrome.app.window.onFullscreened.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`

onMaximized

Fired when the window is maximized.

addListener


                    chrome.app.window.onMaximized.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`

onMinimized

Fired when the window is minimized.

addListener


                    chrome.app.window.onMinimized.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`

onRestored

Fired when the window is restored from being minimized or maximized.

addListener


                    chrome.app.window.onRestored.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`