chrome.windows
| Description: |
Use the chrome.windows API to interact with browser windows. You can use this API to create, modify, and rearrange windows in the browser.
|
| Availability: |
Stable since Chrome 5.
|
| Permissions: |
The chrome.windows API can be used without declaring any permission. However, the "tabs" permission is required in order to populate the url, title, and favIconUrl properties of Tab objects.
|
Manifest
When requested, a Window
will contain an array of tabs.Tab objects.
You must declare the "tabs" permission in your
manifest if you require access to the
url,
title, or
favIconUrl properties of
tabs.Tab.
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
tabs.query.
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 event page,
the value of the current window falls back to the last active window. Under some
circumstances, there may be no current window for background pages.
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.
chrome.windows reference
Types
Window
properties of Window
-
id
(
optional
integer
)
-
The ID of the window. Window IDs are unique within a browser session. Under some circumstances a Window may not be assigned an ID, for example when querying windows using the sessions API, in which case a session ID may be present.
-
focused
(
boolean
)
-
Whether the window is currently the focused window.
-
top
(
optional
integer
)
-
The offset of the window from the top edge of the screen in pixels. Under some circumstances a Window may not be assigned top property, for example when querying closed windows from the sessions API.
-
left
(
optional
integer
)
-
The offset of the window from the left edge of the screen in pixels. Under some circumstances a Window may not be assigned left property, for example when querying closed windows from the sessions API.
-
width
(
optional
integer
)
-
The width of the window, including the frame, in pixels. Under some circumstances a Window may not be assigned width property, for example when querying closed windows from the sessions API.
-
height
(
optional
integer
)
-
The height of the window, including the frame, in pixels. Under some circumstances a Window may not be assigned height property, for example when querying closed windows from the sessions API.
-
tabs
(
optional
array of tabs.Tab
)
-
Array of tabs.Tab objects representing the current tabs in the window.
-
incognito
(
boolean
)
-
Whether the window is incognito.
-
type
(
optional
enum of
"normal", "popup", "panel", or "app"
)
-
The type of browser window this is. Under some circumstances a Window may not be assigned type property, for example when querying closed windows from the sessions API.
-
state
(
optional
enum of
"normal", "minimized", "maximized", or "fullscreen"
)
-
The state of this browser window. Under some circumstances a Window may not be assigned state property, for example when querying closed windows from the sessions API.
-
alwaysOnTop
(
boolean
)
-
Whether the window is set to be always on top.
-
sessionId
(
optional
string
)
-
The session ID used to uniquely identify a Window obtained from the sessions API.
Properties
WINDOW_ID_NONE
chrome.windows.WINDOW_ID_NONE
WINDOW_ID_NONE ( )
The windowId value that represents the absence of a chrome browser window.
WINDOW_ID_CURRENT
chrome.windows.WINDOW_ID_CURRENT
WINDOW_ID_CURRENT ( )
The windowId value that represents the current window.
Methods
get
chrome.windows.get(integer windowId, object getInfo, function callback)
Gets details about a window.
Parameters
-
getInfo
(
optional
object
)
-
-
-
populate
(
optional
boolean
)
-
If true, the Window object will have a tabs property that contains a list of the tabs.Tab objects. The
Tab objects only contain the url, title and favIconUrl properties if the extension's manifest file includes the "tabs" permission.
Callback
The callback parameter should specify a function
that looks like this:
function(Window window) {...};
getCurrent
chrome.windows.getCurrent(object getInfo, function callback)
Gets the current window.
Parameters
-
getInfo
(
optional
object
)
-
-
-
populate
(
optional
boolean
)
-
If true, the Window object will have a tabs property that contains a list of the tabs.Tab objects. The
Tab objects only contain the url, title and favIconUrl properties if the extension's manifest file includes the "tabs" permission.
Callback
The callback parameter should specify a function
that looks like this:
function(Window window) {...};
getLastFocused
chrome.windows.getLastFocused(object getInfo, function callback)
Gets the window that was most recently focused — typically the window 'on top'.
Parameters
-
getInfo
(
optional
object
)
-
-
-
populate
(
optional
boolean
)
-
If true, the Window object will have a tabs property that contains a list of the tabs.Tab objects. The
Tab objects only contain the url, title and favIconUrl properties if the extension's manifest file includes the "tabs" permission.
Callback
The callback parameter should specify a function
that looks like this:
function(Window window) {...};
getAll
chrome.windows.getAll(object getInfo, function callback)
Gets all windows.
Parameters
-
getInfo
(
optional
object
)
-
-
-
populate
(
optional
boolean
)
-
If true, each Window object will have a tabs property that contains a list of the tabs.Tab objects for that window. The
Tab objects only contain the url, title and favIconUrl properties if the extension's manifest file includes the "tabs" permission.
Callback
The callback parameter should specify a function
that looks like this:
function(array of Window windows) {...};
create
chrome.windows.create(object createData, function callback)
Creates (opens) a new browser with any optional sizing, position or default URL provided.
Parameters
-
createData
(
optional
object
)
-
-
url
(
optional
string or
array of string
)
-
A URL or array of URLs to open as tabs in the window. 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.
-
tabId
(
optional
integer
)
-
The id of the tab for which you want to adopt to the new window.
-
left
(
optional
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 focused window. This value is ignored for panels.
-
top
(
optional
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 focused window. This value is ignored for panels.
-
width
(
optional
integer
)
-
The width in pixels of the new window, including the frame. If not specified defaults to a natural width.
-
height
(
optional
integer
)
-
The height in pixels of the new window, including the frame. If not specified defaults to a natural height.
-
focused
(
optional
boolean
)
-
If true, opens an active window. If false, opens an inactive window.
-
incognito
(
optional
boolean
)
-
Whether the new window should be an incognito window.
-
type
(
optional
enum of
"normal", "popup", "panel", or "detached_panel"
)
-
Specifies what type of browser window to create. The 'panel' and 'detached_panel' types create a popup unless the '--enable-panels' flag is set.
-
callback
(
optional
function
)
Callback
If you specify the callback parameter, it should
specify a function that looks like this:
function(Window window) {...};
-
window
(
optional
Window
)
-
Contains details about the created window.
update
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
-
updateInfo
(
object
)
-
-
left
(
optional
integer
)
-
The offset from the left edge of the screen to move the window to in pixels. This value is ignored for panels.
-
top
(
optional
integer
)
-
The offset from the top edge of the screen to move the window to in pixels. This value is ignored for panels.
-
width
(
optional
integer
)
-
The width to resize the window to in pixels. This value is ignored for panels.
-
height
(
optional
integer
)
-
The height to resize the window to in pixels. This value is ignored for panels.
-
focused
(
optional
boolean
)
-
If true, brings the window to the front. If false, brings the next window in the z-order to the front.
-
drawAttention
(
optional
boolean
)
-
If true, causes the window to be displayed in a manner that draws the user's attention to the window, without changing the focused window. The effect lasts until the user changes focus to the window. This option has no effect if the window already has focus. Set to false to cancel a previous draw attention request.
-
state
(
optional
enum of
"normal", "minimized", "maximized", or "fullscreen"
)
-
The new state of the window. The 'minimized', 'maximized' and 'fullscreen' states cannot be combined with 'left', 'top', 'width' or 'height'.
-
callback
(
optional
function
)
Callback
If you specify the callback parameter, it should
specify a function that looks like this:
function(Window window) {...};
remove
chrome.windows.remove(integer windowId, function callback)
Removes (closes) a window, and all the tabs inside it.
Parameters
-
callback
(
optional
function
)
Callback
If you specify the callback parameter, it should
specify a function that looks like this:
function() {...};
Events
onCreated
Fired when a window is created.
addListener
chrome.windows.onCreated.addListener(function callback)
Parameters
Callback
The callback parameter should specify a function
that looks like this:
function(Window window) {...};
-
window
(
Window
)
-
Details of the window that was created.
onRemoved
Fired when a window is removed (closed).
addListener
chrome.windows.onRemoved.addListener(function callback)
Parameters
Callback
The callback parameter should specify a function
that looks like this:
function(integer windowId) {...};
-
windowId
(
integer
)
-
ID of the removed window.
onFocusChanged
Fired when the currently focused window changes. Will be chrome.windows.WINDOW_ID_NONE if all chrome windows have lost focus. Note: On some Linux window managers, WINDOW_ID_NONE will always be sent immediately preceding a switch from one chrome window to another.
addListener
chrome.windows.onFocusChanged.addListener(function callback)
Parameters
Callback
The callback parameter should specify a function
that looks like this:
function(integer windowId) {...};
-
windowId
(
integer
)
-
ID of the newly focused window.
Sample Extensions that use chrome.windows
Cookie API Test Extension
– Testing Cookie API
Live HTTP headers
– Displays the live log with the http requests headers
Download Selected Links
– Select links on a page and download them.
Keep Awake
– Override system power-saving settings.
Show Tabs in Process
– Adds a browser action showing which tabs share the current tab's process.
Tab Inspector
– Utility for working with the extension tabs api
Console TTS Engine
– A "silent" TTS engine that prints text to a small window rather than synthesizing speech.
Merge Windows
– Merges all of the browser's windows into the current window
Page Benchmarker
– Chromium Page Benchmarker.
Chrome Sounds
– Enjoy a more magical and immersive experience when browsing the web using the power of sound.
Google Mail Checker
– Displays the number of unread messages in your Google Mail inbox. You can also click the button to open your inbox.
Imageinfo
– Get image info for images, including EXIF data
Speak Selection
– Speaks the current selection out loud.
chrome