paramName
( optional Type array of paramType )
Undocumented.
Description of this parameter from the json schema.

Google Chrome Extensions (Labs)

Windows

Windows

Use the chrome.windows module to interact with browser windows. You can use this module to create, modify, and rearrange windows in the browser.

Two windows, each with one tab

Manifest

To use the windows API, you must declare the "tabs" permission in manifest.json. (No, that isn't a typo — the window and tabs modules interact so closely we decided to just share one permission between them.) For example: 

{
  "name": "My extension",
  ...
  "permissions": ["tabs"],
  ...
}

The current window

Many functions in the extension system take an optional windowId parameter, which defaults to the current window.

The current window is the window that contains the code that is currently executing. It's important to realize that this can be different from the topmost or focused window.

For example, say an extension creates a few tabs or windows from a single HTML file, and that the HTML file contains a call to chrome.tabs.getSelected. The current window is the window that contains the page that made the call, no matter what the topmost window is.

In the case of the background page, the value of the current window falls back to the topmost window.

Examples

You can find simple examples of using the windows module in the examples/api/windows directory. Another example is in the tabs_api.html file of the inspector example. For other examples and for help in viewing the source code, see Samples.

API reference: chrome.windows

Methods

create

void chrome.windows.create(, object createData, function callback)

Creates (opens) a new browser with any optional sizing, position or default URL provided.

Parameters

createData
( optional Type array of object )
Undocumented.
Description of this parameter from the json schema.
url
( optional Type array of string )
The URL to navigate the first tab to. Fully-qualified URLs must include a scheme (i.e. 'http://www.google.com', not 'www.google.com'). Relative URLs will be relative to the current page within the extension. Defaults to the New Tab Page.
left
( optional Type array of integer )
The number of pixels to position the new window from the left edge of the screen. If not specified, the new window is offset naturally from the last focusd window.
top
( optional Type array of integer )
The number of pixels to position the new window from the top edge of the screen. If not specified, the new window is offset naturally from the last focusd window.
width
( optional Type array of integer )
The width in pixels of the new window. If not specified defaults to a natural width.
height
( optional Type array of integer )
The height in pixels of the new window. If not specified defaults to a natural height.
incognito
( optional Type array of boolean )
Whether the new window should be an incognito window.
type
( optional Type array of string )
Specifies what type of browser window to create.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

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

function(Window window) {...});
window
( optional Window array of paramType )
Contains details about the created window.

get

void chrome.windows.get(, integer windowId, function callback)

Gets details about a window.

Parameters

windowId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

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

function(Window window) {...});
window
( Window array of paramType )
Undocumented.
Description of this parameter from the json schema.

getAll

void chrome.windows.getAll(, object getInfo, function callback)

Gets all windows.

Parameters

getInfo
( optional Type array of object )
Undocumented.
Description of this parameter from the json schema.
populate
( optional Type array of boolean )
If true, each window object will have a tabs property that contains a list of the Tab objects for that window.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

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

function(array of Window windows) {...});
windows
( Type array of Window array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

getCurrent

void chrome.windows.getCurrent(, function callback)

Gets the current window.

Parameters

callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

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

function(Window window) {...});
window
( Window array of paramType )
Undocumented.
Description of this parameter from the json schema.

getLastFocused

void chrome.windows.getLastFocused(, function callback)

Gets the window that was most recently focused — typically the window 'on top'.

Parameters

callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

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

function(Window window) {...});
window
( Window array of paramType )
Undocumented.
Description of this parameter from the json schema.

remove

void chrome.windows.remove(, integer windowId, function callback)

Removes (closes) a window, and all the tabs inside it.

Parameters

windowId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

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

function() {...});

update

void chrome.windows.update(, integer windowId, object updateInfo, function callback)

Updates the properties of a window. Specify only the properties that you want to change; unspecified properties will be left unchanged.

Parameters

windowId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
updateInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
left
( optional Type array of integer )
The offset from the left edge of the screen to move the window to in pixels.
top
( optional Type array of integer )
The offset from the top edge of the screen to move the window to in pixels.
width
( optional Type array of integer )
The width to resize the window to in pixels.
height
( optional Type array of integer )
The height to resize the window to in pixels.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

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

function(Window window) {...});
window
( Window array of paramType )
Undocumented.
Description of this parameter from the json schema.

Events

onCreated

chrome.windows.onCreated.addListener(function(Window window) {...});

Fired when a window is created.

Parameters

window
( Window array of paramType )
Details of the window that was created.

onFocusChanged

chrome.windows.onFocusChanged.addListener(function(integer windowId) {...});

Fired when the currently focused window changes.

Parameters

windowId
( Type array of integer )
ID of the newly focused window.

onRemoved

chrome.windows.onRemoved.addListener(function(integer windowId) {...});

Fired when a window is removed (closed).

Parameters

windowId
( Type array of integer )
ID of the removed window.

Types

Window

paramName
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
id
( Type array of integer )
The ID of the window. Window IDs are unique within a browser session.
focused
( Type array of boolean )
Whether the window is currently the focused window.
top
( Type array of integer )
The offset of the window from the top edge of the screen in pixels.
left
( Type array of integer )
The offset of the window from the left edge of the screen in pixels.
width
( Type array of integer )
The width of the window in pixels.
height
( Type array of integer )
The height of the window in pixels.
tabs
( optional Type array of Tab array of paramType paramType )
Array of Tab objects representing the current tabs in the window.
incognito
( Type array of boolean )
Whether the window is incognito.
type
( Type array of string )
The type of browser window this is.