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. See the Window State Sample for a demonstration of these options.
Types
AppWindow
Properties
-
contentWindow
Window
The JavaScript 'window' object for the created child.
-
id
string
The id the window was created with.
-
innerBounds
The position, size and constraints of the window's content, which does not include window decorations. This property is new in Chrome 36.
-
outerBounds
The position, size and constraints of the window, which includes window decorations, such as the title bar and frame. This property is new in Chrome 36.
-
clearAttention
void
Clear attention to the window.
The
clearAttention
function looks like:() => {...}
-
close
void
Close the window.
The
close
function looks like:() => {...}
-
drawAttention
void
Draw attention to the window.
The
drawAttention
function looks like:() => {...}
-
focus
void
Focus the window.
The
focus
function looks like:() => {...}
-
fullscreen
void
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(), in the keydown and keyup handlers, like this:window.onkeydown = window.onkeyup = function(e) { if (e.keyCode == 27 /* ESC *\/) { e.preventDefault(); } };
Note
window.fullscreen()
will cause the entire window to become fullscreen and does not require a user gesture. The HTML5 fullscreen API can also be used to enter fullscreen mode (see Web APIs for more details).The
fullscreen
function looks like:() => {...}
-
getBounds
void
DeprecatedUse innerBounds or outerBounds.
Get the window's inner bounds as a
ContentBounds
object.The
getBounds
function looks like:() => {...}
-
returns
-
-
hide
void
Hide the window. Does nothing if the window is already hidden.
The
hide
function looks like:() => {...}
-
isAlwaysOnTop
void
Is the window always on top?
The
isAlwaysOnTop
function looks like:() => {...}
-
returns
boolean
-
-
isFullscreen
void
Is the window fullscreen? This will be true if the window has been created fullscreen or was made fullscreen via the
AppWindow
or HTML5 fullscreen APIs.The
isFullscreen
function looks like:() => {...}
-
returns
boolean
-
-
isMaximized
void
Is the window maximized?
The
isMaximized
function looks like:() => {...}
-
returns
boolean
-
-
isMinimized
void
Is the window minimized?
The
isMinimized
function looks like:() => {...}
-
returns
boolean
-
-
maximize
void
Maximize the window.
The
maximize
function looks like:() => {...}
-
minimize
void
Minimize the window.
The
minimize
function looks like:() => {...}
-
moveTo
void
Deprecated since Chrome 43Use outerBounds.
Move the window to the position (
left
,top
).The
moveTo
function looks like:(left: number, top: number) => {...}
-
left
number
-
top
number
-
-
resizeTo
void
Deprecated since Chrome 43Use outerBounds.
Resize the window to
width
xheight
pixels in size.The
resizeTo
function looks like:(width: number, height: number) => {...}
-
width
number
-
height
number
-
-
restore
void
Restore the window, exiting a maximized, minimized, or fullscreen state.
The
restore
function looks like:() => {...}
-
setAlwaysOnTop
void
Set whether the window should stay above most other windows. Requires the
alwaysOnTopWindows
permission.The
setAlwaysOnTop
function looks like:(alwaysOnTop: boolean) => {...}
-
alwaysOnTop
boolean
-
-
setBounds
void
DeprecatedUse innerBounds or outerBounds.
Set the window's inner bounds.
The
setBounds
function looks like:(bounds: ContentBounds) => {...}
-
bounds
-
-
setVisibleOnAllWorkspaces
void
Set whether the window is visible on all workspaces. (Only for platforms that support this).
The
setVisibleOnAllWorkspaces
function looks like:(alwaysVisible: boolean) => {...}
-
alwaysVisible
boolean
-
-
show
void
Show the window. Does nothing if the window is already visible. Focus the window if
focused
is set to true or omitted.The
show
function looks like:(focused?: boolean) => {...}
-
focused
boolean optional
-
Bounds
Properties
-
height
number
This property can be used to read or write the current height of the content or window.
-
left
number
This property can be used to read or write the current X coordinate of the content or window.
-
maxHeight
number optional
This property can be used to read or write the current maximum height of the content or window. A value of
null
indicates 'unspecified'. -
maxWidth
number optional
This property can be used to read or write the current maximum width of the content or window. A value of
null
indicates 'unspecified'. -
minHeight
number optional
This property can be used to read or write the current minimum height of the content or window. A value of
null
indicates 'unspecified'. -
minWidth
number optional
This property can be used to read or write the current minimum width of the content or window. A value of
null
indicates 'unspecified'. -
top
number
This property can be used to read or write the current Y coordinate of the content or window.
-
width
number
This property can be used to read or write the current width of the content or window.
-
setMaximumSize
void
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 ofundefined
will leave a constraint unchanged.The
setMaximumSize
function looks like:(maxWidth: number, maxHeight: number) => {...}
-
maxWidth
number
-
maxHeight
number
-
-
setMinimumSize
void
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 ofundefined
will leave a constraint unchanged.The
setMinimumSize
function looks like:(minWidth: number, minHeight: number) => {...}
-
minWidth
number
-
minHeight
number
-
-
setPosition
void
Set the left and top position of the content or window.
The
setPosition
function looks like:(left: number, top: number) => {...}
-
left
number
-
top
number
-
-
setSize
void
Set the width and height of the content or window.
The
setSize
function looks like:(width: number, height: number) => {...}
-
width
number
-
height
number
-
BoundsSpecification
Properties
-
height
number optional
The height of the content or window.
-
left
number optional
The X coordinate of the content or window.
-
maxHeight
number optional
The maximum height of the content or window.
-
maxWidth
number optional
The maximum width of the content or window.
-
minHeight
number optional
The minimum height of the content or window.
-
minWidth
number optional
The minimum width of the content or window.
-
top
number optional
The Y coordinate of the content or window.
-
width
number optional
The width of the content or window.
ContentBounds
Properties
-
height
number optional
-
left
number optional
-
top
number optional
-
width
number optional
CreateWindowOptions
Properties
-
alwaysOnTop
boolean optional
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
alwaysOnTopWindows
permission. Defaults to false.Call
setAlwaysOnTop()
on the window to change this property after creation. -
bounds
ContentBounds optional
DeprecatedUse innerBounds or outerBounds.
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.
-
focused
boolean optional
If true, the window will be focused when created. Defaults to true.
-
frame
string | FrameOptions optional
Frame type:
none
orchrome
(defaults tochrome
). Fornone
, 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 new in M36. -
boolean optional
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.
-
icon
string optional
Chrome 54+URL of the window icon. A window can have its own icon when showInShelf is set to true. The URL should be a global or an extension local URL.
-
id
string optional
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.
-
innerBounds
BoundsSpecification optional
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 matchingid
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
andouterBounds
will result in an error.This property is new in Chrome 36.
-
maxHeight
number optional
DeprecatedUse innerBounds or outerBounds.
Maximum height of the window.
-
maxWidth
number optional
DeprecatedUse innerBounds or outerBounds.
Maximum width of the window.
-
minHeight
number optional
DeprecatedUse innerBounds or outerBounds.
Minimum height of the window.
-
minWidth
number optional
DeprecatedUse innerBounds or outerBounds.
Minimum width of the window.
-
outerBounds
BoundsSpecification optional
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 matchingid
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
andouterBounds
will result in an error.This property is new in Chrome 36.
-
resizable
boolean optional
If true, the window will be resizable by the user. Defaults to true.
-
showInShelf
boolean optional
Chrome 54+If true, the window will have its own shelf icon. Otherwise the window will be grouped in the shelf with other windows that are associated with the app. Defaults to false. If showInShelf is set to true you need to specify an id for the window.
-
singleton
boolean optional
DeprecatedMultiple 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.
-
state
State optional
The initial state of the window, allowing it to be created already fullscreen, maximized, or minimized. Defaults to 'normal'.
-
type
WindowType optional
Chrome 45+ Deprecated since Chrome 69All app windows use the 'shell' window type
Type of window to create.
-
visibleOnAllWorkspaces
boolean optional
If true, and supported by the platform, the window will be visible on all workspaces.
FrameOptions
Properties
-
activeColor
string optional
Allows the frame color of the window when active to be set. Frame coloring is only available if the frame type is
chrome
.Frame coloring is only available if the frame type is
chrome
.Frame coloring is new in Chrome 36.
-
color
string optional
Allows the frame color to be set. Frame coloring is only available if the frame type is
chrome
.Frame coloring is new in Chrome 36.
-
inactiveColor
string optional
Allows the frame color of the window when inactive to be set differently to the active color. Frame coloring is only available if the frame type is
chrome
.inactiveColor
must be used in conjunction withcolor
.Frame coloring is new in Chrome 36.
-
type
string optional
Frame type:
none
orchrome
(defaults tochrome
).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.
State
State of a window: normal, fullscreen, maximized, minimized.
Enum
"normal" "fullscreen" "maximized" "minimized"
WindowType
Specifies the type of window to create.
Enum
"shell" "panel"
Default window type.
OS managed window (Deprecated).
Methods
canSetVisibleOnAllWorkspaces()
chrome.app.window.canSetVisibleOnAllWorkspaces()
Whether the current platform supports windows being visible on all workspaces.
Returns
-
boolean
create()
chrome.app.window.create(
url: string,
options?: CreateWindowOptions,
callback?: function,
)
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.
To set the position, size and constraints of the window, use the innerBounds
or outerBounds
properties. Inner bounds do not include window decorations. Outer bounds include the window's title bar and frame. Note that the padding between the inner and outer bounds is determined by the OS. Therefore setting the same property for both inner and outer bounds is considered an error (for example, setting both innerBounds.left
and outerBounds.left
).
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
-
url
string
-
options
CreateWindowOptions optional
-
callback
function optional
The
callback
parameter looks like:(createdWindow: AppWindow) => void
-
createdWindow
-
Returns
-
Promise<AppWindow>
Chrome 117+Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
current()
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().
Returns
-
AppWindow | undefined
get()
chrome.app.window.get(
id: string,
)
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
-
id
string
Returns
-
AppWindow | undefined
getAll()
chrome.app.window.getAll()
Gets an array of all currently created app windows. This method is new in Chrome 33.
Returns
Events
onBoundsChanged
chrome.app.window.onBoundsChanged.addListener(
callback: function,
)
Fired when the window is resized.
Parameters
-
callback
function
The
callback
parameter looks like:() => void
onClosed
chrome.app.window.onClosed.addListener(
callback: function,
)
Fired when the window is closed. Note, this should be listened to from a window other than the window being closed, for example from the background page. This is because the window being closed will be in the process of being torn down when the event is fired, which means not all APIs in the window's script context will be functional.
Parameters
-
callback
function
The
callback
parameter looks like:() => void
onFullscreened
chrome.app.window.onFullscreened.addListener(
callback: function,
)
Fired when the window is fullscreened (either via the AppWindow
or HTML5 APIs).
Parameters
-
callback
function
The
callback
parameter looks like:() => void
onMaximized
chrome.app.window.onMaximized.addListener(
callback: function,
)
Fired when the window is maximized.
Parameters
-
callback
function
The
callback
parameter looks like:() => void
onMinimized
chrome.app.window.onMinimized.addListener(
callback: function,
)
Fired when the window is minimized.
Parameters
-
callback
function
The
callback
parameter looks like:() => void
onRestored
chrome.app.window.onRestored.addListener(
callback: function,
)
Fired when the window is restored from being minimized or maximized.
Parameters
-
callback
function
The
callback
parameter looks like:() => void