recursal/MDN huggingface dataset:
downloads.DangerType
====================

The `DangerType` type of the `downloads` API defines a set of possible reasons that a downloadable file might be considered dangerous.

A `downloads.DownloadItem`'s `danger` property will contain a string taken from the values defined in this type.

**Note:** These string constants will never change, however the set of DangerTypes may change.

Type
----

Values of this type are strings. Possible values are:

`file`

The download's filename is suspicious.

`url`

The download's URL is known to be malicious.

`content`

The downloaded file is known to be malicious.

`uncommon`

The download's URL is not commonly downloaded.

`host`

The download came from a host known to distribute malicious binaries.

`unwanted`

The download is potentially unwanted or unsafe.

`safe`

The download presents no known danger to the user's computer.

`accepted`

The user has accepted the dangerous download.

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.downloads` API.
downloads.open()
================

The **`open()`** function of the `downloads` API opens the downloaded file with its associated application. A `downloads.onChanged` event fires when the item is opened for the first time.

To use this function in your extension you must ask for the "downloads.open" manifest permission, as well as the "downloads" permission. Also, 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
let opening = browser.downloads.open(
  downloadId      // integer
)
```

### Parameters

`downloadId`

An `integer` representing the `id` of the `downloads.DownloadItem` you want to open.

### Return value

A `Promise`. If the request is successful, the promise is fulfilled with no arguments. If the request failed, the promise is 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 opens the most recently downloaded item:


```js
function onOpened() {
  console.log(`Opened download item`);
}

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

function openDownload(downloadItems) {
  if (downloadItems.length > 0) {
    let opening = browser.downloads.open(downloadItems[0].id);
    opening.then(onOpened, onError);
  }
}

let searching = browser.downloads.search({
  limit: 1,
  orderBy: ["-startTime"],
});

searching.then(openDownload, onError);
```

### Example extensions

* latest-download

**Note:** This API is based on Chromium's `chrome.downloads` API.
browserSettings.ftpProtocolEnabled
==================================

A `BrowserSetting` object that determines whether the FTP protocol is enabled in the browser.

The underlying value is a boolean.

**Note:** From Firefox version 88 this setting is read-only.

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

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

Examples
--------

Toggle the setting:


```js
function toggleAllowFtp() {
  function toggle(current) {
    console.log(`Current value: ${current.value}`);
    browser.browserSettings.ftpProtocolEnabled.set({ value: !current.value });
  }

  browser.browserSettings.ftpProtocolEnabled.get({}).then(toggle);
}

browser.browserAction.onClicked.addListener(() => {
  toggleAllowFtp();
});
```
browserSettings.overrideContentColorScheme
==========================================

A `BrowserSetting` object whose underlying value is a string.

Firefox enables users to choose a theme for the browser UI. These themes apply either a light or dark theme to webpages. Using the `layout.css.prefers-color-scheme.content-override` preference, users can override the theme and choose to render webpages in a light or dark theme or follow the device's theme. This browser setting exposes that preference.

This object takes these values:

* "light": Applies a light theme to webpages.
* "dark": Applies a dark theme to webpages.
* "system": Applies a light or dark theme to webpages based on the device's theme.
* "browser": Applies a light or dark theme to webpages based on the browser's theme.
Browser compatibility
---------------------

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

Examples
--------

This example overrides the setting to use the dark theme for webpages:


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.overrideContentColorScheme
  .set({ value: "dark" })
  .then(logResult);
```
browserSettings.allowPopupsForUserEvents
========================================

A `BrowserSetting` object that can be used to enable or disable the ability of web pages to open popups in response to user actions.

The underlying value is a boolean.

By default, browsers allow web pages to open popups in response to a particular set of events: for example, click, mouseup, submit. If `allowPopupsForUserEvents` is set to `false`, no user events will be able to open popups. If it is set to `true`, the default set of events will be allowed to open popups.

For example, suppose a web page has code like this:


```js
window.addEventListener("click", (e) => {
  window.open("https://example.com", "myPopup", "height=400,width=400");
});
```


By default, this will open a popup window. If your extension sets `allowPopupsForUserEvents` to `false`, then it will not open a popup, and the user will be informed that the popup was blocked.

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

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

Examples
--------

Toggle the setting:


```js
function toggleAllowPopup() {
  function toggle(current) {
    console.log(`Current value: ${current.value}`);
    browser.browserSettings.allowPopupsForUserEvents.set({
      value: !current.value,
    });
  }

  browser.browserSettings.allowPopupsForUserEvents.get({}).then(toggle);
}

browser.browserAction.onClicked.addListener(() => {
  toggleAllowPopup();
});
```
browserSettings.contextMenuShowEvent
====================================

A `BrowserSetting` object which determines whether the browser's context menu is shown on the mouseup event or on the mousedown event.

Its underlying value is a string that may be either "mouseup" or "mousedown".

The default value is "mouseup" on Windows, and "mousedown" on macOS and Linux. Assigning to it on Windows has no effect - the setting is only designed to allow the context menu to be opened on mouseup instead of mousedown, not the inverse.

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

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

Examples
--------

Set the setting to "mouseup":


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.contextMenuShowEvent
  .set({ value: "mouseup" })
  .then(logResult);
```
browserSettings.newTabPageOverride
==================================

A `BrowserSetting` object that can be used to get a string representing the URL for the "new tab" page: that is, the page that's loaded when the user opens a new empty tab.

Note that this is a read-only setting.

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

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

Examples
--------

Get the current value of the new tab URL:


```js
browser.browserSettings.newTabPageOverride.get({}).then((result) => {
  console.log(result.value);
});
```
browserSettings.closeTabsByDoubleClick
======================================

A `BrowserSetting` object that can be used to enable or disable the user's ability to close a tab using double-click.

The underlying value is a boolean.

By default, closeTabsByDoubleClick is false. The setting can be changed by the user in about:config.

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

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

A `BrowserSetting` object that can be used to get a string representing the URL currently set as the browser's homepage.

Note that this is a read-only setting. To change the homepage, see chrome\_settings\_overrides.

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

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

Examples
--------

Get the current value of the homepage URL:


```js
browser.browserSettings.homepageOverride.get({}).then((result) => {
  console.log(result.value);
});
```
browserSettings.newTabPosition
==============================

A `BrowserSetting` object that can be used to control the position of newly opened tabs relative to already open tabs.

The underlying value is a string that can take one of three values:

* "afterCurrent": Open all new tabs next to the current tab.
* "relatedAfterCurrent": The default. Open new tabs next to the current tab if they are related to the current tab (for example, if they were opened via a link in the current tab). Otherwise, open new tabs at the end of the tabstrip.
* "atEnd": Open all tabs at the end of the tabstrip.
Browser compatibility
---------------------

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

Examples
--------

This code sets the value to "afterCurrent" and then logs the new value:


```js
async function setAfterCurrent() {
  let result = await browser.browserSettings.newTabPosition.set({
    value: "afterCurrent",
  });
  console.log(`Result: ${result}`);
  let newValue = await browser.browserSettings.newTabPosition.get({});
  console.log(`New value: ${newValue.value}`);
}
```
browserSettings.zoomSiteSpecific
================================

A `BrowserSetting` object whose underlying value is a boolean.

This property sets the configuration setting `browser.zoom.siteSpecific`, which controls how zoom settings are applied to sites and tabs.

If `browser.zoom.siteSpecific` is true, zoom operations apply to all pages from the same site so that:

* when a page loads, if there is a zoom level for that site it is applied to the page otherwise the global default zoom level is applied.
* when the zoom level for a page changes, the zoom levels of other pages from the site in other tabs are also changed.

If `browser.zoom.siteSpecific` is set false, zoom operations apply to the active tab only so that:

* when a new tab opens, the global default zoom level is applied.
* when the zoom level in a tab changes, it persists across page loads and does not affect the zoom level in any other tab.

When Firefox is installed, `browser.zoom.siteSpecific` is true.

If `privacy.websites``.resistFingerprinting` is true, this setting has no effect and zoom is set on a per-tab basis.

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

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

Examples
--------

Set the setting to `false`:


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.zoomSiteSpecific.set({ value: false }).then(logResult);
```
browserSettings.colorManagement
===============================

A `BrowserSetting` object used to query and set the browser's color management features.

By default, Firefox applies color management to tagged media and defaults to sRGB for untagged media. This behavior means that some untagged media, such as that used in animation and movie production, may have undesired color corrections made to it. Use these settings to prevent that.

The object has these properties:

`mode`

A string that represents the mode used for color management. Valid values are `off`, `full`, and `tagged_only`.

`useNativeSRGB`

A boolean representing whether or not built-in sRGB color management is used.

`useWebRenderCompositor`

A boolean representing whether or not the WebRender compositor is used.

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

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

Examples
--------

Set color mode to "full":


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.colorManagement.mode
  .set({ value: "full" })
  .then(logResult);
```


Get the native sRGB color management color mode:


```js
function logResult(result) {
  console.log(`Current useNativeSRGB value: ${result.value}`);
}

browser.browserSettings.colorManagement.useNativeSRGB.get({}).then(logResult);
```
browserSettings.useDocumentFonts
================================

A `BrowserSetting` object whose underlying value is a boolean.

By default, of course, web pages can specify the fonts they want using CSS properties like `font-family`. This setting enables an extension to instruct Firefox to ignore the fonts specified by the page, and only use system fonts.

Its underlying value is a boolean:

* `true`: use the fonts specified by the web page. This is the default.
* `false`: use the system fonts.
Browser compatibility
---------------------

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

Examples
--------

Set the setting to `false`:


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.useDocumentFonts.set({ value: false }).then(logResult);
```
browserSettings.tlsVersionRestrictionConfig
===========================================

A `BrowserSetting` object used to read the highest and lowest versions of TLS supported by the browser.

The object has these properties:

`minimum`

The lowest TLS version supported by the browser. Valid values are `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`, and `unknown`.

`maximum`

The highest TLS version supported by the browser. Valid values are `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`, and `unknown`.

This is a read-only setting.

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

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

Examples
--------

Get the highest TLS version supported by the browser:


```js
browser.browserSettings.tlsVersionRestrictionConfig.maximum
  .get({})
  .then((result) => {
    console.log(`Highest TLS version supported: ${result}`);
  });
```
browserSettings.openBookmarksInNewTabs
======================================

A `BrowserSetting` object whose underlying value is a boolean.

If set to `true`, then when the user selects a bookmark, it will be opened in a new tab. If set to `false` (the default) bookmarks are opened in the current tab.

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

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

Examples
--------

Set the setting to `true`:


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.openBookmarksInNewTabs
  .set({ value: true })
  .then(logResult);
```
browserSettings.imageAnimationBehavior
======================================

A `BrowserSetting` object that can be used to change the way the browser handles animated images, such as GIFs.

The underlying value is a string that can take one of three values:

* "normal": the default. Play animated images as normal.
* "none": don't animate images at all.
* "once": play the animation once.
Browser compatibility
---------------------

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

Examples
--------

Disable animated images:


```js
browser.browserSettings.imageAnimationBehavior.set({ value: "none" });
```
browserSettings.cacheEnabled
============================

A `BrowserSetting` object that can be used to globally enable or disable the browser cache.

The underlying value is a boolean.

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

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

Examples
--------

Getting the current value of this setting:


```js
function logResult(result) {
  console.log(`Current value: ${result.value}`);
  console.log(`Current level of control: ${result.levelOfControl}`);
}

browser.browserSettings.cacheEnabled.get({}).then(logResult);
```


Disabling the browser cache:


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.cacheEnabled.set({ value: false }).then(logResult);
```
browserSettings.overrideDocumentColors
======================================

A `BrowserSetting` object whose underlying value is a string.

Firefox enables the user to set their own colors for document backgrounds and text. By default these values are only applied when a high-contrast theme is selected (a high-contrast theme is a feature of some operating system UIs that increases the contrast for improved accessibility). However, users can also choose to apply these colors always or never. This browser setting exposes that preference.

Its underlying value is a string that may take any one of the following values:

* "high-contrast-only": Apply the user's choices only when a high-contrast theme is selected. This is the default.
* "never": Never apply the user's choices.
* "always": Always apply the user's choices.
Browser compatibility
---------------------

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

Examples
--------

Set the setting to "always":


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.overrideDocumentColors
  .set({ value: "always" })
  .then(logResult);
```
browserSettings.openSearchResultsInNewTabs
==========================================

A `BrowserSetting` object whose underlying value is a boolean.

If set to `true`, then when the user selects a term in the browser's search box, the search results are displayed in a new tab. If set to `false` (the default) the search results are shown in the current tab.

Note that this does not affect the behavior when selecting items from the omnibox/awesomebar,only the dedicated search box.

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

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

Examples
--------

Set the setting to `true`:


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.openSearchResultsInNewTabs
  .set({ value: true })
  .then(logResult);
```
browserSettings.openUrlbarResultsInNewTabs
==========================================

A `BrowserSetting` object whose underlying value is a boolean.

When the user focuses the address bar and starts typing, the browser offers autocomplete suggestions: a dropdown list of web pages based on the user's incomplete input and their browsing history.

If set to `true`, then when the user selects one of these items, the item is opened in a new tab. If set to `false` (the default) the item is opened in the current tab.

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

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

Examples
--------

Set the setting to `true`:


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.openUrlbarResultsInNewTabs
  .set({ value: true })
  .then(logResult);
```
browserSettings.webNotificationsDisabled
========================================

A `BrowserSetting` object that can be used to prevent websites from showing notifications using the `Notifications` Web API.

The `Notifications` API is used to display desktop notifications to the user. There are three levels of permission for notifications: *allow*, *deny*, and *prompt*. Users can set this permission for every site. If the user has not set a permission for a particular site, then the browser will fall back to a global permission, which defaults to *prompt*.

Setting `browserSettings.webNotificationsDisabled` to `true` switches the global permission to *deny*.

Note that this won't affect sites for which the user has set a per-site preference. For example, if the user sets https://example.org to *allow*, and an extension then sets `browserSettings.webNotificationsDisabled` to `true`, then pages under https://example.org will still be allowed to show notifications.

Setting `browserSettings.webNotificationsDisabled` to `false` switches the global default back to its default value.

Note that this setting has no effect on notifications created by extensions using the `notifications` API.

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

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

Examples
--------

Toggle the setting:


```js
async function toggleWebNotifications() {
  let current = await browser.browserSettings.webNotificationsDisabled.get({});
  console.log(`Current value: ${current.value}`);
  browser.browserSettings.webNotificationsDisabled.set({
    value: !current.value,
  });
}

browser.browserAction.onClicked.addListener(() => {
  toggleWebNotifications();
});
```
browserSettings.zoomFullPage
============================

A `BrowserSetting` object whose underlying value is a boolean.

By default zoom applies to all the content of a web page. Using the Zoom Text Only setting users can choose to zoom only the text on a page. This settings enables web extensions to control this setting and determine whether zoom is applied to the entire page or to text only.

The settings are:

* `true`: zoom applies to all the content of a web page (default).
* `false`: zoom applies to web page text only.
Browser compatibility
---------------------

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

Examples
--------

Set the setting to `false`:


```js
function logResult(result) {
  console.log(`Setting was modified: ${result}`);
}

browser.browserSettings.zoomFullPage.set({ value: false }).then(logResult);
```
action.ColorArray
=================

Type
----

An `array` of four integers in the range 0-255, defining an RGBA color. The four values specify the following channels:

1. Red
2. Green
3. Blue
4. Alpha (opacity).

For example, opaque red is `[255, 0, 0, 255]`.

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

Disables the browser action for a tab, meaning that it cannot be clicked when that tab is active.

**Note:** This API is available in Manifest V3 or higher.

Syntax
------


```js
browser.action.disable(
  tabId // optional integer
)
```

### Parameters

`tabId` Optional

`integer`. The id of the tab for which you want to disable the browser action.

Examples
--------

Disable the browser action when clicked, and re-enable it every time a new tab is opened:


```js
browser.tabs.onCreated.addListener(() => {
  browser.action.enable();
});

browser.action.onClicked.addListener(() => {
  browser.action.disable();
});
```


Disable the browser action only for the active tab:


```js
browser.action.onClicked.addListener((tab) => {
  browser.action.disable(tab.id);
});
```

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