webextension-polyfill/types/namespaces/windows.d.ts

373 lines
12 KiB
TypeScript
Raw Permalink Normal View History

2022-03-24 01:03:59 +00:00
/**
* Namespace: browser.windows
* Generated from Mozilla sources. Do not manually edit!
*
* Use the <code>browser.windows</code> API to interact with browser windows. You can use this API to create, modify,
* and rearrange windows in the browser.
*
* Comments found in source JSON schema files:
* Copyright (c) 2012 The Chromium Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
import { Tabs } from "./tabs";
import { Events } from "./events";
export namespace Windows {
/**
* 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 $(ref:sessions) API.
*/
type WindowType = "normal" | "popup" | "panel" | "app" | "devtools";
/**
* 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 $(ref:sessions) API.
*/
type WindowState = "normal" | "minimized" | "maximized" | "fullscreen" | "docked";
interface Window {
/**
* 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 $(ref:sessions) API, in which case a session ID may be
* present.
* Optional.
*/
id?: number;
/**
* Whether the window is currently the focused window.
*/
focused: boolean;
/**
* 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 $(ref:sessions) API.
* Optional.
*/
top?: number;
/**
* 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 $(ref:sessions) API.
* Optional.
*/
left?: number;
/**
* 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 $(ref:sessions) API.
* Optional.
*/
width?: number;
/**
* 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 $(ref:sessions) API.
* Optional.
*/
height?: number;
/**
* Array of $(ref:tabs.Tab) objects representing the current tabs in the window.
* Optional.
*/
tabs?: Tabs.Tab[];
/**
* Whether the window is incognito.
*/
incognito: boolean;
/**
* The type of browser window this is.
* Optional.
*/
type?: WindowType;
/**
* The state of this browser window.
* Optional.
*/
state?: WindowState;
/**
* Whether the window is set to be always on top.
*/
alwaysOnTop: boolean;
/**
* The session ID used to uniquely identify a Window obtained from the $(ref:sessions) API.
* Optional.
*/
sessionId?: string;
/**
* The title of the window. Read-only.
* Optional.
*/
title?: string;
}
/**
* Specifies what type of browser window to create. The 'panel' and 'detached_panel' types create a popup unless the
* '--enable-panels' flag is set.
*/
type CreateType = "normal" | "popup" | "panel" | "detached_panel";
/**
* Specifies whether the $(ref:windows.Window) returned should contain a list of the $(ref:tabs.Tab) objects.
*/
interface GetInfo {
/**
* If true, the $(ref:windows.Window) returned will have a <var>tabs</var> property that contains a list of the $(ref:tabs.
* Tab) objects. The <code>Tab</code> objects only contain the <code>url</code>, <code>title</code> and <code>
* favIconUrl</code> properties if the extension's manifest file includes the <code>"tabs"</code> permission.
* Optional.
*/
populate?: boolean;
}
/**
* Specifies properties used to filter the $(ref:windows.Window) returned and to determine whether they should contain a
* list of the $(ref:tabs.Tab) objects.
*/
interface GetAllGetInfoType extends GetInfo {
/**
* If set, the $(ref:windows.Window) returned will be filtered based on its type. If unset the default filter is set to
* <code>['app', 'normal', 'panel', 'popup']</code>, with <code>'app'</code> and <code>'panel'</code>
* window types limited to the extension's own windows.
* Optional.
*/
windowTypes?: WindowType[];
}
interface CreateCreateDataType {
/**
* 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.
* Optional.
*/
url?: string | string[];
/**
* The id of the tab for which you want to adopt to the new window.
* Optional.
*/
tabId?: number;
/**
* 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.
* Optional.
*/
left?: number;
/**
* 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.
* Optional.
*/
top?: number;
/**
* The width in pixels of the new window, including the frame. If not specified defaults to a natural width.
* Optional.
*/
width?: number;
/**
* The height in pixels of the new window, including the frame. If not specified defaults to a natural height.
* Optional.
*/
height?: number;
/**
* If true, the new window will be focused. If false, the new window will be opened in the background and the currently
* focused window will stay focused. Defaults to true.
* Optional.
*/
focused?: boolean;
/**
* Whether the new window should be an incognito window.
* Optional.
*/
incognito?: boolean;
/**
* Specifies what type of browser window to create. The 'panel' and 'detached_panel' types create a popup unless the
* '--enable-panels' flag is set.
* Optional.
*/
type?: CreateType;
/**
* The initial state of the window. The 'minimized', 'maximized' and 'fullscreen' states cannot be combined with 'left',
* 'top', 'width' or 'height'.
* Optional.
*/
state?: WindowState;
/**
* Allow scripts to close the window.
* Optional.
*/
allowScriptsToClose?: boolean;
/**
* The CookieStoreId to use for all tabs that were created when the window is opened.
* Optional.
*/
cookieStoreId?: string;
/**
* A string to add to the beginning of the window title.
* Optional.
*/
titlePreface?: string;
}
interface UpdateUpdateInfoType {
/**
* The offset from the left edge of the screen to move the window to in pixels. This value is ignored for panels.
* Optional.
*/
left?: number;
/**
* The offset from the top edge of the screen to move the window to in pixels. This value is ignored for panels.
* Optional.
*/
top?: number;
/**
* The width to resize the window to in pixels. This value is ignored for panels.
* Optional.
*/
width?: number;
/**
* The height to resize the window to in pixels. This value is ignored for panels.
* Optional.
*/
height?: number;
/**
* If true, brings the window to the front. If false, brings the next window in the z-order to the front.
* Optional.
*/
focused?: 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.
* Optional.
*/
drawAttention?: boolean;
/**
* The new state of the window. The 'minimized', 'maximized' and 'fullscreen' states cannot be combined with 'left', 'top',
* 'width' or 'height'.
* Optional.
*/
state?: WindowState;
/**
* A string to add to the beginning of the window title.
* Optional.
*/
titlePreface?: string;
}
interface Static {
/**
* Gets details about a window.
*
* @param windowId
* @param getInfo Optional.
*/
get(windowId: number, getInfo?: GetInfo): Promise<Window>;
/**
* Gets the $(topic:current-window)[current window].
*
* @param getInfo Optional.
*/
getCurrent(getInfo?: GetInfo): Promise<Window>;
/**
* Gets the window that was most recently focused &mdash; typically the window 'on top'.
*
* @param getInfo Optional.
*/
getLastFocused(getInfo?: GetInfo): Promise<Window>;
/**
* Gets all windows.
*
* @param getInfo Optional. Specifies properties used to filter the $(ref:windows.Window)
* returned and to determine whether they should contain a list of the $(ref:tabs.Tab) objects.
*/
getAll(getInfo?: GetAllGetInfoType): Promise<Window[]>;
/**
* Creates (opens) a new browser with any optional sizing, position or default URL provided.
*
* @param createData Optional.
*/
create(createData?: CreateCreateDataType): Promise<Window>;
/**
* Updates the properties of a window. Specify only the properties that you want to change; unspecified properties will be
* left unchanged.
*
* @param windowId
* @param updateInfo
*/
update(windowId: number, updateInfo: UpdateUpdateInfoType): Promise<Window>;
/**
* Removes (closes) a window, and all the tabs inside it.
*
* @param windowId
*/
remove(windowId: number): Promise<void>;
/**
* Fired when a window is created.
*
* @param window Details of the window that was created.
*/
onCreated: Events.Event<(window: Window) => void>;
/**
* Fired when a window is removed (closed).
*
* @param windowId ID of the removed window.
*/
onRemoved: Events.Event<(windowId: number) => void>;
/**
* Fired when the currently focused window changes. Will be $(ref:windows.WINDOW_ID_NONE)
* if all browser windows have lost focus. Note: On some Linux window managers, WINDOW_ID_NONE will always be sent
* immediately preceding a switch from one browser window to another.
*
* @param windowId ID of the newly focused window.
*/
onFocusChanged: Events.Event<(windowId: number) => void>;
/**
* The windowId value that represents the absence of a browser window.
*/
WINDOW_ID_NONE: -1;
/**
* The windowId value that represents the $(topic:current-window)[current window].
*/
WINDOW_ID_CURRENT: -2;
}
}