recursal/MDN huggingface dataset:
tabs.onActivated
================

Fires when the active tab in a window changes. Note that the tab's URL may not be set at the time this event fired, but you can listen to `tabs.onUpdated` events to be notified when a URL is set.

Syntax
------


```js
browser.tabs.onActivated.addListener(listener)
browser.tabs.onActivated.removeListener(listener)
browser.tabs.onActivated.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 `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:

`activeInfo`

`object`. ID of the tab that was made active, and ID of its window. See the activeInfo section for more details.


Additional objects
------------------

### activeInfo

`previousTabId`

`integer`. The ID of the previous activated tab, if that tab is still open.

`tabId`

`integer`. The ID of the tab that has become active.

`windowId`

`integer`. The ID of the tab's window.

Examples
--------

Listen for and log tab activation events:


```js
function handleActivated(activeInfo) {
  console.log(`Tab ${activeInfo.tabId} was activated`);
}

browser.tabs.onActivated.addListener(handleActivated);
```

### Example extensions

* annotate-page
* bookmark-it
* chill-out
* cookie-bg-picker
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.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.onSelectionChanged
=======================

**Warning:** This event is deprecated. Use `tabs.onActivated` instead.

Fires when the selected tab in a window changes.

Syntax
------


```js
browser.tabs.onSelectionChanged.addListener(listener)
browser.tabs.onSelectionChanged.removeListener(listener)
browser.tabs.onSelectionChanged.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 `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 these arguments:

`tabId`

`integer`. The ID of the tab that has become active.

`selectInfo`

`object`. See the selectInfo section for more details.


Additional objects
------------------

### selectInfo

`windowId`

`integer`. The ID of the window the selected tab changed in.

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.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.connect()
==============

Call this function to set up a connection between the extension's background scripts (or other privileged scripts, such as popup scripts or options page scripts) and any content scripts that belong to this extension and are running in the specified tab. This function returns a `runtime.Port` object.

When this is called, the `runtime.onConnect` event will be fired in any content script belonging to this extension that are running in the specified tab. The event listener will be passed another `runtime.Port` object. The two sides can then use the `Port` objects to exchange messages.

For more details, see connection-based messaging. You can message without creating a connection, for advice on choosing between the options, see Choosing between one-off messages and connection-based messaging.

Syntax
------


```js
browser.tabs.connect(
  tabId,      // integer
  connectInfo // optional object
)
```

### Parameters

`tabId`

`integer`. ID of the tab whose content scripts we want to connect to.

`connectInfo` Optional

An object with the following properties:

`name` Optional

`string`. Will be passed into `runtime.onConnect` event listeners in content scripts belonging to this extension and running in the specified tab.

`frameId` Optional

`integer`. Open a port to a specific frame identified by `frameId` instead of all frames in the tab.


### Return value

`runtime.Port`. A port that can be used to communicate with the content scripts running in the specified tab.

Examples
--------

In this example a background script listens for a click on a browser action, then connects to the currently active tab, then sends a message using the `Port` that's returned from `connect()`:


```js
function connectToTab(tabs) {
  if (tabs.length > 0) {
    let examplePort = browser.tabs.connect(tabs[0].id, {
      name: "tabs-connect-example",
    });
    examplePort.postMessage({ greeting: "Hi from background script" });
  }
}

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

browser.browserAction.onClicked.addListener(() => {
  let gettingActive = browser.tabs.query({
    currentWindow: true,
    active: true,
  });
  gettingActive.then(connectToTab, onError);
});
```

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.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.ZoomSettingsMode
=====================

Defines how zoom changes are handled. Extensions can pass this value into `tabs.setZoomSettings()` to control how the browser handles attempts to change zoom settings for a tab. Defaults to "automatic".

Type
----

Values of this type are strings. Possible values are:

"automatic"

Zoom changes are handled normally by the browser.

"disabled"

Disables all zooming in the tab. The tab will revert to the default zoom level, and all attempted zoom changes will be ignored.

"manual"

The extension will handle zoom changes itself, by listening for the `tabs.onZoomChange` event and scaling the page accordingly. This mode does not support `per-origin` zooming: it will ignore the `scope` `zoom setting` and always use `per-tab`.

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.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.onRemoved
==============

Fired when a tab is closed.

Syntax
------


```js
browser.tabs.onRemoved.addListener(listener)
browser.tabs.onRemoved.removeListener(listener)
browser.tabs.onRemoved.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 `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 these arguments:

`tabId`

`integer`. ID of the tab that closed.

`removeInfo`

`object`. The tab's window ID, and a boolean indicating whether the window is also being closed. See the removeInfo section for more details.


Additional objects
------------------

### removeInfo

`windowId`

`integer`. The window whose tab is closed.

`isWindowClosing`

`boolean`. `true` if the tab is being closed because its window is being closed.

Examples
--------

Listen for close events, and log the info:


```js
function handleRemoved(tabId, removeInfo) {
  console.log(`Tab: ${tabId} is closing`);
  console.log(`Window ID: ${removeInfo.windowId}`);
  console.log(`Window is closing: ${removeInfo.isWindowClosing}`);
}

browser.tabs.onRemoved.addListener(handleRemoved);
```

### Example extensions

* tabs-tabs-tabs
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.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
permissions.onAdded
===================

Fired when the extension granted new permissions.

Syntax
------


```js
browser.permissions.onAdded.addListener(listener)
browser.permissions.onAdded.removeListener(listener)
browser.permissions.onAdded.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 `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:

`permissions`

`permissions.Permissions` object containing the permissions that were granted.


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

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

Examples
--------


```js
function handleAdded(permissions) {
  console.log(`New API permissions: ${permissions.permissions}`);
  console.log(`New host permissions: ${permissions.origins}`);
}

browser.permissions.onAdded.addListener(handleAdded);
```


**Note:** This API is based on Chromium's `chrome.permissions` API.
permissions.request()
=====================

Ask for the set of permissions listed in the given `permissions.Permissions` object.

The `Permissions` argument may contain either an `origins` property, which is an array of host permissions, or a `permissions` property, which is an array of API permissions, or both. Permissions must come from the set of permissions defined in the `optional_permissions` manifest.json key. The `origins` property may include permissions that match a subset of the hosts matched by an optional permission: for example, if optional\_permissions include "\*://mozilla.org/", then `permissions.origins` may include "https://developer.mozilla.org/".

The request can only be made inside the handler for a user action.

Depending on a circumstances, the browser will probably handle the request by asking the user whether to grant the requested permissions. Only a single request is made for all requested permissions: thus either all permissions are granted or none of them are.

Any permissions granted are retained by the extension, even over upgrade and disable/enable cycling.

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

Syntax
------


```js
let requesting = browser.permissions.request(
  permissions                // Permissions object
)
```

### Parameters

`permissions`

A `permissions.Permissions` object.

### Return value

A `Promise` that is fulfilled with `true` if the extension is now granted all the permissions listed in the `permissions` argument, or `false` otherwise.

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

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

Examples
--------

This code adds a click handler that asks for various permissions, then logs the result of the request and the extension's permissions after the request completed.


```js
const permissionsToRequest = {
  permissions: ["bookmarks", "history"],
  origins: ["https://developer.mozilla.org/"],
};

async function requestPermissions() {
  function onResponse(response) {
    if (response) {
      console.log("Permission was granted");
    } else {
      console.log("Permission was refused");
    }
    return browser.permissions.getAll();
  }

  const response = await browser.permissions.request(permissionsToRequest);
  const currentPermissions = await onResponse(response);

  console.log(`Current permissions:`, currentPermissions);
}

document
  .querySelector("#request")
  .addEventListener("click", requestPermissions);
```

### Example extensions

* dnr-dynamic-with-options
* dnr-redirect-url
* permissions

**Note:** Currently has a bug with requesting origins and requesting permissions on the about:addons page.

**Note:** This API is based on Chromium's `chrome.permissions` API.
permissions.contains()
======================

Check whether the extension has the permissions listed in the given `permissions.Permissions` object.

The `Permissions` argument may contain either an origins property, which is an array of host permissions, or a `permissions` property, which is an array of API permissions, or both.

This is an asynchronous function that returns a `Promise`. The promise is fulfilled with true only if all the extension currently has all the given permissions. For host permissions, if the extension's permissions pattern-match the permissions listed in `origins`, then they are considered to match.

Syntax
------


```js
let getContains = browser.permissions.contains(
  permissions                // Permissions object
)
```

### Parameters

`permissions`

A `permissions.Permissions` object.

### Return value

A `Promise` that will be fulfilled with `true` if the extension already has all the permissions listed in the `permissions` argument, or `false` otherwise.

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

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

Examples
--------


```js
// Extension permissions are:
// "webRequest", "tabs", "\*://\*.mozilla.org/\*"

let testPermissions1 = {
  origins: ["\*://mozilla.org/"],
  permissions: ["tabs"],
};

const testResult1 = await browser.permissions.contains(testPermissions1);
console.log(testResult1); // true

let testPermissions2 = {
  origins: ["\*://mozilla.org/"],
  permissions: ["tabs", "alarms"],
};

const testResult2 = await browser.permissions.contains(testPermissions2);
console.log(testResult2); // false, "alarms" doesn't match

let testPermissions3 = {
  origins: ["https://developer.mozilla.org/"],
  permissions: ["tabs", "webRequest"],
};

const testResult3 = await browser.permissions.contains(testPermissions3);
console.log(testResult3); // true: "https://developer.mozilla.org/", matches: "\*://\*.mozilla.org/\*"

let testPermissions4 = {
  origins: ["https://example.org/"],
};

const testResult4 = await browser.permissions.contains(testPermissions4);
console.log(testResult4); // false: "https://example.org/", `origins` doesn't match
```

### Example extensions

* dnr-redirect-url

**Note:** This API is based on Chromium's `chrome.permissions` API.
permissions.remove()
====================

Ask to give up the permissions listed in the given `permissions.Permissions` object.

The `Permissions` argument may contain either an `origins` property, which is an array of host permissions, or a `permissions` property, which is an array of API permissions, or both. Permissions must come from the set of permissions defined in the `optional_permissions` manifest.json key.

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

Syntax
------


```js
let removing = browser.permissions.remove(
  permissions                // Permissions object
)
```

### Parameters

`permissions`

A `permissions.Permissions` object.

### Return value

A `Promise` that is fulfilled with `true` if the permissions listed in the `permissions` argument are now not granted to the extension, or `false` otherwise.

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

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

Examples
--------

This code adds a click handler that removes a given permission.


```js
const permissionToRemove = {
  permissions: ["history"],
};

async function remove() {
  console.log("removing");
  const removed = await browser.permissions.remove(permissionToRemove);
  console.log(removed);
}

document.querySelector("#remove").addEventListener("click", remove);
```

### Example extensions

* dnr-dynamic-with-options
* dnr-redirect-url
* permissions

**Note:** This API is based on Chromium's `chrome.permissions` API.
Permissions
===========

A `Permissions` object represents a collection of permissions.

Type
----

An `object` with the following properties:

`origins` Optional

An array of match patterns, representing host permissions.

`permissions` Optional

An array of named permissions, including API permissions and clipboard permissions.

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.permissions` API.
permissions.getAll()
====================

Retrieve a `permissions.Permissions` object containing all the permissions currently granted to the extension.

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

Syntax
------


```js
let gettingAll = browser.permissions.getAll()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with a `permissions.Permissions` object containing all the permissions currently granted to the extension. This includes all permissions the extension has listed in the `permissions` key, and any permissions listed in `optional_permissions` that the extension has been granted by calling `permissions.request()`.

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

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

Examples
--------


```js
// Extension permissions are:
// "webRequest", "tabs", "\*://\*.mozilla.org/\*"

const currentPermissions = await browser.permissions.getAll();

console.log(currentPermissions.permissions); // [ "webRequest", "tabs" ]
console.log(currentPermissions.origins); // [ "\*://\*.mozilla.org/\*" ]
```

### Example extensions

* dnr-dynamic-with-options
* permissions

**Note:** This API is based on Chromium's `chrome.permissions` API.
permissions.onRemoved
=====================

Fired when some permissions are removed from the extension.

Syntax
------


```js
browser.permissions.onRemoved.addListener(listener)
browser.permissions.onRemoved.removeListener(listener)
browser.permissions.onRemoved.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 `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:

`permissions`

`permissions.Permissions` object containing the permissions that were removed.


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

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

Examples
--------


```js
function handleRemoved(permissions) {
  console.log(`Removed API permissions: ${permissions.permissions}`);
  console.log(`Removed host permissions: ${permissions.origins}`);
}

browser.permissions.onRemoved.addListener(handleRemoved);
```


**Note:** This API is based on Chromium's `chrome.permissions` API.
topSites.MostVisitedURL
=======================

The `MostVisitedURL` type contains two properties: the title of a page and its URL.

Type
----

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

`favicon` Optional

`String`. A data: URL containing the favicon for the page, if `includeFavicon` was given in `topSites.get()` and the favicon was available.

`title`

`String`. The page's title.

`url`

`String`. The page's URL.

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

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

Examples
--------

**Note:** This API is based on Chromium's `chrome.topSites` API.
commands.update()
=================

Change the description or keyboard shortcut for the given command.

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

Syntax
------


```js
browser.commands.update(
  details // object
);
```

### Parameters

`details`

`object`. An object with the following properties:

`name`

`string`. The name of the command to update. This must match the name of an existing command, as given for example in the `name` property of the `commands.Command` object.

`description` Optional

`string`. A new description to set for the command.

`shortcut` Optional

`string`. A new shortcut to set for the command. This can be:

* an empty string to clear the shortcut.
* a string matching the format of the `commands` manifest.json key to set a new shortcut key. If the string does not match this format, the function throws an error.


### Return value

A `Promise` that will be fulfilled with no arguments when the shortcut has been updated. The promise will be rejected with an error if the command could not be found.

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

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

Examples
--------

Updates the command named "my-command" with the given shortcut value, when the user clicks "update":


```js
const commandName = "my-command";

function updateShortcut() {
  browser.commands.update({
    name: commandName,
    shortcut: document.querySelector("#shortcut").value,
  });
}

document.querySelector("#update").addEventListener("click", updateShortcut);
```

### Example extensions

* commands
onChanged
=========

Fired when the keyboard shortcut for a command is changed.

The listener is passed an object containing the name of the command, its new active shortcut, and its old shortcut.

Syntax
------


```js
browser.commands.onChanged.addListener(listener)
browser.commands.onChanged.removeListener(listener)
browser.commands.onChanged.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 `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

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

### Parameters

`listener`

The function called when a command's shortcut changes. The function is passed these arguments:

`changeInfo`

`object`. An object containing the name of the command, its new active shortcut, and its old shortcut.

`name`

`string`. Name of the command. This matches the name given to the command in its manifest.json entry.

`newShortcut`

`string`. The new active shortcut for this command, or blank if no shortcut is active.

`oldShortcut`

`string`. The shortcut that was active for this command, or blank if no shortcut was active.


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

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

Examples
--------

You could log changes to command shortcuts like this:


```js
function handleChanged(changeInfo) {
  console.log(`Shortcut for: ${changeInfo.name} changed`);
  console.log(`From: ${changeInfo.oldShortcut}`);
  console.log(`To: ${changeInfo.newShortcut}`);
}

browser.commands.onChanged.addListener(handleChanged);
```