Welcome What's new in Chrome extensions Getting started API Reference Samples
Welcome What's new in Chrome extensions Getting started API Reference Samples

chrome.app.window

This API is part of the deprecated Chrome Apps platform. Learn more about migrating your app.
  • 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.

Summary

Types

AppWindow

Properties

  • clearAttention
    function

    Clear attention to the window.

    The clearAttention function looks like this:

    clearAttention() => {...}
  • close
    function

    Close the window.

    The close function looks like this:

    close() => {...}
  • contentWindow
    Window

    The JavaScript 'window' object for the created child.

  • drawAttention
    function

    Draw attention to the window.

    The drawAttention function looks like this:

    drawAttention() => {...}
  • focus
    function

    Focus the window.

    The focus function looks like this:

    focus() => {...}
  • fullscreen
    function

    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 this:

    fullscreen() => {...}
  • getBounds
    function

    Deprecated. Use innerBounds or outerBounds.

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

    The getBounds function looks like this:

    getBounds(): ContentBounds => {...}
  • hide
    function

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

    The hide function looks like this:

    hide() => {...}
  • 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.

  • isAlwaysOnTop
    function

    Is the window always on top?

    The isAlwaysOnTop function looks like this:

    isAlwaysOnTop(): boolean => {...}
    • returns
      boolean
  • isFullscreen
    function

    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 this:

    isFullscreen(): boolean => {...}
    • returns
      boolean
  • isMaximized
    function

    Is the window maximized?

    The isMaximized function looks like this:

    isMaximized(): boolean => {...}
    • returns
      boolean
  • isMinimized
    function

    Is the window minimized?

    The isMinimized function looks like this:

    isMinimized(): boolean => {...}
    • returns
      boolean
  • maximize
    function

    Maximize the window.

    The maximize function looks like this:

    maximize() => {...}
  • minimize
    function

    Minimize the window.

    The minimize function looks like this:

    minimize() => {...}
  • moveTo
    function

    Deprecated. Use outerBounds.

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

    The moveTo function looks like this:

    moveTo(left: number, top: number) => {...}
    • left
      number
    • top
      number
  • 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.

  • resizeTo
    function

    Deprecated. Use outerBounds.

    Resize the window to widthxheight pixels in size.

    The resizeTo function looks like this:

    resizeTo(width: number, height: number) => {...}
    • width
      number
    • height
      number
  • restore
    function

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

    The restore function looks like this:

    restore() => {...}
  • setAlwaysOnTop
    function

    Set whether the window should stay above most other windows. Requires the alwaysOnTopWindows permission.

    The setAlwaysOnTop function looks like this:

    setAlwaysOnTop(alwaysOnTop: boolean) => {...}
    • alwaysOnTop
      boolean
  • setBounds
    function

    Deprecated. Use innerBounds or outerBounds.

    Set the window's inner bounds.

    The setBounds function looks like this:

    setBounds(bounds: ContentBounds) => {...}
  • setVisibleOnAllWorkspaces
    function

    Set whether the window is visible on all workspaces. (Only for platforms that support this).

    The setVisibleOnAllWorkspaces function looks like this:

    setVisibleOnAllWorkspaces(alwaysVisible: boolean) => {...}
    • alwaysVisible
      boolean
  • show
    function

    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 this:

    show(focused: boolean) => {...}
    • focused
      boolean

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'.

  • setMaximumSize
    function

    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.

    The setMaximumSize function looks like this:

    setMaximumSize(maxWidth: number, maxHeight: number) => {...}
    • maxWidth
      number
    • maxHeight
      number
  • setMinimumSize
    function

    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.

    The setMinimumSize function looks like this:

    setMinimumSize(minWidth: number, minHeight: number) => {...}
    • minWidth
      number
    • minHeight
      number
  • setPosition
    function

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

    The setPosition function looks like this:

    setPosition(left: number, top: number) => {...}
    • left
      number
    • top
      number
  • setSize
    function

    Set the width and height of the content or window.

    The setSize function looks like this:

    setSize(width: number, height: number) => {...}
    • width
      number
    • height
      number
  • 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.

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

    Deprecated. Use 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 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 new in M36.

  • hidden
    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

    Since 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

    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.

    This property is new in Chrome 36.

  • maxHeight
    number optional

    Deprecated. Use innerBounds or outerBounds.

    Maximum height of the window.

  • maxWidth
    number optional

    Deprecated. Use innerBounds or outerBounds.

    Maximum width of the window.

  • minHeight
    number optional

    Deprecated. Use innerBounds or outerBounds.

    Minimum height of the window.

  • minWidth
    number optional

    Deprecated. Use innerBounds or outerBounds.

    Minimum width of the window.

  • 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.

    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

    Since 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

    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.

  • 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

    Since Chrome 45.

    Deprecated since Chrome 69. All 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 with color.

    Frame coloring is new in Chrome 36.

  • type
    string optional

    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.

State

State of a window: normal, fullscreen, maximized, minimized.

Enum

"normal", "fullscreen", "maximized", or "minimized"

WindowType

Since Chrome 45.

Specifies the type of window to create.

Enum

"shell", or "panel"

Methods

canSetVisibleOnAllWorkspaces

app.window.canSetVisibleOnAllWorkspaces(): boolean

Whether the current platform supports windows being visible on all workspaces.

Returns

  • returns
    boolean

create

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
  • callback
    function

    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(); }

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

    (createdWindow: AppWindow) => {...}

current

app.window.current(): AppWindow

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

get

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

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

getAll

app.window.getAll(): AppWindow[]

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

Returns

Events

onBoundsChanged

app.window.onBoundsChanged.addListener(listener: function)

Fired when the window is resized.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    () => {...}

onClosed

app.window.onClosed.addListener(listener: 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.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    () => {...}

onFullscreened

app.window.onFullscreened.addListener(listener: function)

Fired when the window is fullscreened (either via the AppWindow or HTML5 APIs).

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    () => {...}

onMaximized

app.window.onMaximized.addListener(listener: function)

Fired when the window is maximized.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    () => {...}

onMinimized

app.window.onMinimized.addListener(listener: function)

Fired when the window is minimized.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    () => {...}

onRestored

app.window.onRestored.addListener(listener: function)

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

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    () => {...}
We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.