recursal/MDN huggingface dataset:
windows.get()
=============

Gets details about a window, given its ID. The details are passed into a callback.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let getting = browser.windows.get(
  windowId,              // integer
  getInfo                // optional object
)
```

### Parameters

`windowId`

`integer`. The ID of the window object you want returned.

`getInfo` Optional

`object`. Contains options to filter the type of window.

`populate` Optional

`boolean`. If `true`, the `windows.Window` object will have a `tabs` property that contains a list of `tabs.Tab` objects representing the tabs open in the window. The `Tab` objects only contain the `url`, `title` and `favIconUrl` properties if the extension's manifest file includes the `"tabs"` permission or a matching host permission.

`windowTypes` Optional

`array` of `windows.WindowType` objects. If set, the `windows.Window` returned will be filtered based on its type. If unset the default filter is set to `['normal', 'panel', 'popup']`, with `'panel'` window types limited to the extension's own windows.


**Note:** If supplied, the `windowTypes` component of `getInfo` is ignored. The use of `windowTypes` has been deprecated as of Firefox 62.

### Return value

A `Promise` that will be fulfilled with a `windows.Window` object containing the details of the window. If any error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This example gets the current window and logs the URLs of the tabs it contains. Note that you'll need the "tabs" permission or matching host permissions to access tab URLs.

**Note:** This example is a bit unrealistic: in this situation you would more probably use `windows.getCurrent()`.


```js
function logTabs(windowInfo) {
  for (const tabInfo of windowInfo.tabs) {
    console.log(tabInfo.url);
  }
}

function onError(error) {
  console.error(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener((tab) => {
  browser.windows.get(tab.windowId, { populate: true }).then(logTabs, onError);
});
```


**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.getLastFocused()
========================

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

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingWindow = browser.windows.getLastFocused(
  getInfo               // optional object
)
```

### Parameters

`getInfo` Optional

`object`.

`populate` Optional

`boolean`. If `true`, the `windows.Window` object will have a `tabs` property that contains a list of `tabs.Tab` objects representing the tabs in the window. The `Tab` objects only contain the `url`, `title` and `favIconUrl` properties if the extension's manifest file includes the `"tabs"` permission or host permissions matching the tab's URL.

`windowTypes` Optional

An `array` of `windows.WindowType` objects. If set, the `windows.Window` returned will be filtered based on its type. If unset the default filter is set to `['normal', 'panel', 'popup']`, with `'panel'` window types limited to the extension's own windows.


**Note:** If supplied, the `windowTypes` component of `getInfo` is ignored. The use of `windowTypes` has been deprecated as of Firefox 62.

### Return value

A `Promise` that will be fulfilled with a `windows.Window` object containing the details of the last focused window. If any error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Get the last focused window, and log the tabs it contains. Note that you'll need the "tabs" permission or matching host permissions to access tab URLs.


```js
function logTabs(windowInfo) {
  for (const tabInfo of windowInfo.tabs) {
    console.log(tabInfo.url);
  }
}

function onError(error) {
  console.error(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener((tab) => {
  browser.windows.getLastFocused({ populate: true }).then(logTabs, onError);
});
```


**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.onFocusChanged
======================

Fired when the currently focused window changes. Will be `windows.WINDOW_ID_NONE` if all browser windows have lost focus.

**Note:** In Windows and some Linux window managers, WINDOW\_ID\_NONE will always be sent immediately preceding a switch from one browser window to another.

Syntax
------


```js
browser.windows.onFocusChanged.addListener(listener)
browser.windows.onFocusChanged.removeListener(listener)
browser.windows.onFocusChanged.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`windowId`

`integer`. ID of the newly focused window.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log focus changes:


```js
browser.windows.onFocusChanged.addListener((windowId) => {
  console.log(`Newly focused window: ${windowId}`);
});
```

### Example extensions

* bookmark-it

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.WINDOW\_ID\_CURRENT
===========================

`browser.windows.WINDOW_ID_CURRENT` is a value that can be used as a `windowId` parameter in some APIs to represent the current window.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.update()
================

Updates the properties of a window. Use this to move, resize, and (un)focus a window, etc.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let updating = browser.windows.update(
  windowId,              // integer
  updateInfo             // object
)
```

### Parameters

`windowId`

`integer`. ID of the window to update.

`updateInfo`

`object`. Object containing the properties to update.

`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 `drawAttention` request.

`focused` Optional

`boolean`. If `true`, brings the window to the front. If false, brings the next window in the z-order to the front.

`height` Optional

`integer`. The height to resize the window to in pixels. This value is ignored for panels.

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

`state` Optional

`windows.WindowState`. The new state of the window. The `minimized`, `maximized` and `fullscreen` states cannot be combined with `left`, `top`, `width` or `height`.

`titlePreface` Optional

`string`. Use this to add a string to the beginning of the browser window's title. Depending on the underlying operating system, this might not work on browser windows that don't have a title (such as about:blank in Firefox).

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


### Return value

A `Promise` that will be fulfilled with a `windows.Window` object containing the details of the updated window. If any error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

When the user clicks a browser action's icon, move the window to the top left corner:


```js
function onUpdated(windowInfo) {
  console.log(`Updated window: ${windowInfo.id}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener((tab) => {
  let updating = browser.windows.update(tab.windowId, {
    left: 0,
    top: 0,
  });
  updating.then(onUpdated, onError);
});
```

### Example extensions

* window-manipulator

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.remove()
================

Closes a window and all the tabs inside it, given the window's ID.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let removing = browser.windows.remove(
  windowId        // integer
)
```

### Parameters

`windowId`

`integer`. ID of the window to close.

### Return value

A `Promise` that will be fulfilled with no arguments when the window has been closed. If any error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

When the user clicks a browser action's icon, close the window in which the icon was clicked:


```js
function onRemoved() {
  console.log(`Removed window`);
}

function onError(error) {
  console.error(`Error:`, error);
}

browser.browserAction.onClicked.addListener((tab) => {
  let removing = browser.windows.remove(tab.windowId);
  removing.then(onRemoved, onError);
});
```


Close the current, e.g. popup, window when the user clicks a button on the page:


```js
// in a script loaded by the page in the window
document.querySelector("#close").addEventListener(async ({ button }) => {
  try {
    if (button) return; // not a left click
    const windowId = (await browser.windows.getCurrent()).id;
    await browser.windows.remove(windowId);
    // this point will never be reached, since the window is gone
  } catch (error) {
    console.error("Closing failed:", error);
  }
});
```


In Firefox, the same could be achieved with the `.allowScriptsToClose` window creation property and `window.close()`.

### Example extensions

* window-manipulator

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.Window
==============

Information about a browser window.

Type
----

Values of this type are `objects`. They contain the following properties:

`alwaysOnTop`

`boolean`. Whether the window is set to be always on top.

`focused`

`boolean`. Whether the window is currently the focused window.

`height` Optional

`integer`. The height of the window, including the frame, in pixels.

`id` Optional

`integer`. The ID of the window. Window IDs are unique within a browser session.

`incognito`

`boolean`. Whether the window is incognito (private).

`left` Optional

`integer`. The offset of the window from the left edge of the screen in pixels.

`sessionId` Optional

`string`. The session ID used to uniquely identify a Window obtained from the `sessions` API.

`state` Optional

A `windows.WindowState` value representing the state of this browser window — maximized, minimized, etc.

`tabs` Optional

Array of `tabs.Tab` objects representing the current tabs in the window.

`title` Optional

The title of the browser window. Requires "tabs" permission or host permissions for the active tab's URL. Read only.

`top` Optional

`integer`. The offset of the window from the top edge of the screen in pixels.

`type` Optional

A `windows.WindowType` value representing the type of browser window this is — normal browser window, popup, etc.

`width` Optional

`integer`. The width of the window, including the frame, in pixels.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
sidebarAction.getTitle()
========================

Gets the sidebar's title.

Just as you can set the title on a per-tab basis using `sidebarAction.setTitle()`, so you can retrieve a tab-specific title by passing the tab's ID into this function.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingTitle = browser.sidebarAction.getTitle(
  details               // object
)
```

### Parameters

`details`

`object`. An object with the following properties:

`tabId` Optional

`integer`. Get the title for the sidebar specific to the given tab.

`windowId` Optional

`integer`. Get the title for the sidebar specific to the given window.



* If `windowId` and `tabId` are both supplied, the function fails and the promise it returns is rejected.
* If `windowId` and `tabId` are both omitted, the global title is returned.
### Return value

A `Promise` that will be fulfilled with a string containing the sidebar's title.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This code switches the title between "this" and "that" each time the user clicks the browser action


```js
function toggleTitle(title) {
  if (title === "this") {
    browser.sidebarAction.setTitle({ title: "that" });
  } else {
    browser.sidebarAction.setTitle({ title: "this" });
  }
}

browser.browserAction.onClicked.addListener(() => {
  let gettingTitle = browser.sidebarAction.getTitle({});
  gettingTitle.then(toggleTitle);
});
```


**Note:** This API is based on Opera's `chrome.sidebarAction` API.
sidebarAction.toggle()
======================

Toggles the visibility of the sidebar in the active window, if the sidebar belongs to the extension.

You can only call this function from inside the handler for a user action.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
browser.sidebarAction.toggle()
```

### Parameters

None.

### Return value

A `Promise` that is resolved with no arguments.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Toggles the sidebar when the user selects an item from the context menu:


```js
browser.menus.create({
  id: "toggle-sidebar",
  title: "Toggle sidebar",
  contexts: ["all"],
});

browser.menus.onClicked.addListener(() => {
  browser.sidebarAction.toggle();
});
```
sidebarAction.close()
=====================

Closes the sidebar in the active window, if it is the extension's own sidebar.

You can only call this function from inside the handler for a user action.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
browser.sidebarAction.close()
```

### Parameters

None.

### Return value

A `Promise` that is resolved with no arguments.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Close the sidebar when the user selects a context menu item:


```js
browser.menus.create({
  id: "close-sidebar",
  title: "close sidebar",
  contexts: ["all"],
});

browser.menus.onClicked.addListener(() => {
  browser.sidebarAction.close();
});
```
sidebarAction.getPanel()
========================

Gets a URL to the HTML document that defines the sidebar's contents.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingPanel = browser.sidebarAction.getPanel(
  details               // object
)
```

### Parameters

`details`

`object`. An object with the following properties:

`tabId` Optional

`integer`. Get the panel for the sidebar specific to the given tab.

`windowId` Optional

`integer`. Get the panel for the sidebar specific to the given window.



* If `windowId` and `tabId` are both supplied, the function fails and the promise it returns is rejected.
* If `windowId` and `tabId` are both omitted, the global panel is returned.
### Return value

A `Promise` that will be fulfilled with a string containing the URL for the panel's document. This will be a fully qualified URL, such as:


```url
moz-extension://d1d8a2eb-fe60-f646-af30-a866c5b39942/sidebar.html
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Get the panel's URL:


```js
function onGot(sidebarUrl) {
  console.log(sidebarUrl);
}

let gettingPanel = browser.sidebarAction.getPanel({});
gettingPanel.then(onGot);
```


**Note:** This API is based on Opera's `chrome.sidebarAction` API.
sidebarAction.isOpen()
======================

Returns `true` if the extension's sidebar is open in a given window.

This function accepts a `windowId` as a parameter:

* If you supply `windowId`, the function will check the given browser window.
* If you omit `windowId`, the function will check the topmost browser window.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingIsOpen = browser.sidebarAction.isOpen(
  details // object
)
```

### Parameters

`details`

`object`. An object optionally containing the `windowId` to check.

`windowId` Optional

`integer`. ID of a browser window to check. If omitted defaults to `windows.WINDOW_ID_CURRENT`, which refers to the topmost browser window.


### Return value

A `Promise` that will be fulfilled with `true` if the extension's sidebar is open in the given window, or `false` otherwise.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Check the topmost window:


```js
browser.sidebarAction.isOpen({}).then((result) => {
  console.log(result);
});
```


Check all open windows:


```js
async function checkWindow(windowId) {
  const result = await browser.sidebarAction.isOpen({ windowId });
  console.log(`window: ${windowId} status: ${result}`);
}

browser.windows.getAll().then((all) => {
  for (const { id } of all) {
    checkWindow(id);
  }
});
```
sidebarAction.setTitle()
========================

Sets the sidebar's title. The title is displayed anywhere the browser lists available sidebars. For example, Firefox will show it in the "View > Sidebar" menu. It's also shown at the top o the sidebar when the sidebar is open.

Types of title
--------------

Your extension should specify an title for the sidebar in the sidebar\_action manifest key. This is called the *"manifest title"*. If you don't specify the manifest title, it will default to the extension name.

If you set a new title using `setTitle()`, and include the `tabId` option, then the title is set only for the given tab. This title is called the *"tab-specific title"*.

If you set a new title using `setTitle()`, and include the `windowId` option, then the title is set only for the given window. This title is called the *"window-specific title"*, and will appear in all tabs of that window that do not have a tab-specific title set.

If you set a new title using `setTitle()`, and omit both the `tabId` and `windowId` options, then this sets the *"global title"*. The global title will then appear in all tabs that do not have a tab-specific title set and whose window does not have a window-specific title.

Syntax
------


```js
browser.sidebarAction.setTitle(
  details // object
)
```

### Parameters

`details`

`object`. An object with the following properties:

`title`

`string` or `null`. The sidebar's new title.

If `title` is an empty string, the used title will be the extension name, but `sidebarAction.getTitle` will still provide the empty string.

If `title` is `null`, then a previously set title will be removed, so that:

* If `tabId` is specified, and the tab has a tab-specific title set, then the tab will inherit the title from the window it belongs to.
* If `windowId` is specified, and the window has a window-specific title set, then the window will inherit the global title.
* Otherwise, the global title will be reset to the manifest title.

`tabId` Optional

`integer`. Sets the title only for the given tab.

`windowId` Optional

`integer`. Sets the title only for the given window.



* If `windowId` and `tabId` are both supplied, the function fails and the title is not set.
* If `windowId` and `tabId` are both omitted, the global title is set.
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This code changes the title for the sidebar when the user clicks a browser action, but only for the current tab:


```js
let title = "A different title";

function setTitleForTab(tab) {
  browser.sidebarAction.setTitle({ title, tabId: tab.id });
}

browser.browserAction.onClicked.addListener(setTitleForTab);
```


**Note:** This API is based on Opera's `chrome.sidebarAction` API.