recursal/MDN huggingface dataset:
commands.reset()
================

Resets the given command's description and keyboard shortcut to the values given in the extension's `commands` manifest.json key.

This effectively undoes any changes made to the command using the `commands.update()` function.

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

Syntax
------


```js
browser.commands.reset(
  name // string
);
```

### Parameters

`name`

`string`. Name of the command to reset, as given by the `name` property of the `commands.Command` object.

### Return value

A `Promise` that will be fulfilled with no arguments when the shortcut has been reset.

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

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

Examples
--------

Resets the command named "my-command" when the user clicks the "reset" button:


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

function resetShortcut() {
  browser.commands.reset(commandName);
}

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

### Example extensions

* commands
getAll()
========

Gets all commands for the extension that you have registered using the `commands` manifest.json key.

The commands are returned as an array of `commands.Command` objects. Alternately, if you are using the promise-based version of the API, `browser.commands.getAll()`, the commands are passed into the `onFulfilled` argument to `Promise.then()`.

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

Syntax
------


```js
let getCommands = browser.commands.getAll();
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with an array of ``commands.Command`` objects, one for each command registered for the extension. If no commands were registered, the array will be empty.

Examples
--------


```js
function logCommands(commands) {
  commands.forEach((command) => {
    console.log(command);
  });
}

let getCommands = browser.commands.getAll();
getCommands.then(logCommands);
```

### Example extensions

* commands

**Note:** This API is based on Chromium's `chrome.commands` API.

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

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

Information about a command. This contains the information specified for the command in the `commands` manifest.json key.

An array of these objects is returned from `commands.getAll()`.

Type
----

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

`name` Optional

`string`. Name of this command. This will be passed into the `commands.onCommand` event listener.

`description` Optional

`string`. Description of this command. This is primarily used to explain to the user what this command does.

`shortcut` Optional

`string`. Key(s) used to execute this command, specified as a string like "Ctrl+Shift+Y".

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.commands` API.
onCommand
=========

Fired when a command is executed using its associated keyboard shortcut.

The listener is passed the command's name. This matches the name given to the command in its manifest.json entry.

Syntax
------


```js
browser.commands.onCommand.addListener(listener)
browser.commands.onCommand.removeListener(listener)
browser.commands.onCommand.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 user enters the command's shortcut. The function is passed this argument:

`name`

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

`tab`

`tabs.Tab`. The tab that was active when the command shortcut was entered.


Examples
--------

Given a manifest.json entry like this:


```json
"commands": {
  "toggle-feature": {
    "suggested\_key": {
      "default": "Ctrl+Shift+Y"
    },
    "description": "Send a 'toggle-feature' event"
  }
}
```


You could listen for this particular command like this:


```js
browser.commands.onCommand.addListener((command) => {
  if (command === "toggle-feature") {
    console.log("toggling the feature!");
  }
});
```

### Example extensions

* commands
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.commands` API.
omnibox.onDeleteSuggestion
==========================

 Fired whenever the user deletes a suggestion.
 A suggestion can be deleted when `SuggestResult``.deletable` is set to true.

Syntax
------


```js
browser.omnibox.onDeleteSuggestion.addListener(listener)
browser.omnibox.onDeleteSuggestion.removeListener(listener)
browser.omnibox.onDeleteSuggestion.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

`text`

`string`. The description of the deleted suggestion.

Examples
--------

This example prints the deleted suggestion to the console:


```js
function logDeletedSuggestion(text) {
  console.log(`The user deleted: ${text}`);
}

browser.omnibox.onDeleteSuggestion.addListener(logDeletedSuggestion);
```

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

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.
omnibox.OnInputEnteredDisposition
=================================

The **`omnibox.OnInputEnteredDisposition`** type describes how the extension should handle a user selection from the suggestions in the address bar's drop-down list.

It's passed into the `omnibox.onInputEntered` event listener, along with the selection itself.

Type
----

Values of this type are strings. They may take any one of the following values:

"currentTab"

Open the selection in the current tab.

"newForegroundTab"

Open the selection in a new tab, and bring this new tab into the foreground.

"newBackgroundTab"

Open the selection in a new background tab, keeping the current tab in the foreground.

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.omnibox` API.
omnibox.setDefaultSuggestion()
==============================

Set the default suggestion to appear in the address bar drop-down list when the user starts interacting with your extension.

Once the user has entered your keyword and started interacting with your extension, the default suggestion will always appear first in the drop-down list. Unlike the suggestions you supply in `omnibox.onInputChanged`, this item can't be selected. Use it to provide the user with some guidance about what to type and what they can expect to see when they do.

Syntax
------


```js
browser.omnibox.setDefaultSuggestion(
  suggestion            // object
)
```

### Parameters

`suggestion`

`object`. An object containing a single string property `description`, which will be displayed as the first item in the drop-down when the user starts interacting with your extension.

### Return value

None.

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

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

Examples
--------


```js
browser.omnibox.setDefaultSuggestion({
  description: "Type the name of a CSS property",
});
```

### Example extensions

* firefox-code-search

**Note:** This API is based on Chromium's chrome.omnibox API.
omnibox.onInputStarted
======================

Fired when the user starts interacting with your extension by entering its keyword in the address bar and then pressing the space key.

This will be sent before any `omnibox.onInputChanged` events.

Syntax
------


```js
browser.omnibox.onInputStarted.addListener(listener)
browser.omnibox.onInputStarted.removeListener(listener)
browser.omnibox.onInputStarted.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 no arguments.

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

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

Examples
--------


```js
browser.omnibox.onInputStarted.addListener(() => {
  console.log("User has started interacting with me.");
});
```


**Note:** This API is based on Chromium's `chrome.omnibox` API.
omnibox.onInputCancelled
========================

Fired when the user has cancelled their interaction with your extension (for example, by clicking outside the address bar).

Syntax
------


```js
browser.omnibox.onInputCancelled.addListener(listener)
browser.omnibox.onInputCancelled.removeListener(listener)
browser.omnibox.onInputCancelled.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
------------------

The listener function is passed no parameters.

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

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

Examples
--------


```js
browser.omnibox.onInputCancelled.addListener(() => {
  console.log("The user cancelled the session.");
});
```


**Note:** This API is based on Chromium's `chrome.omnibox` API.
omnibox.SuggestResult
=====================

The **`omnibox.SuggestResult`** type defines a suggestion that the extension can add to the address bar's drop-down list.

The extension's `omnibox.onInputChanged` event listener is passed a callback. To populate the address bar's drop-down list in response to the user's input, the extension can pass an array of `omnibox.SuggestResult` objects into this callback.

Type
----

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

`content`

This is the value that will appear in the address bar itself when the user highlights this suggestion in the drop-down list. This is also the string sent to the `omnibox.onInputEntered` event listener if the user selects this suggestion. If the string is the same as what the user has already typed, this entry will not appear in the drop-down list.

`deletable`

Whether the suggest result can be deleted by the user.

`description`

This is the string that's displayed in the address bar's drop-down list.

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.omnibox` API.
sessions.Filter
===============

The `Filter` object enables you to restrict the number of `Session` objects returned by a call to `sessions.getRecentlyClosed()`.

Type
----

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

`maxResults` Optional

`number`. The maximum number of results to return.

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.sessions` API.
sessions.removeTabValue()
=========================

Removes a value previously stored by a call to `sessions.setTabValue`.

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

Syntax
------


```js
let removing = browser.sessions.removeTabValue(
  tabId,    // integer
  key       // string
)
```

### Parameters

`tabId`

`integer`. ID of the tab whose data you are trying to remove. Error is thrown if ID is invalid.

`key`

`string`. Key identifying the particular value to remove. This needs to match the key previously given in `sessions.setTabValue`.

### Return value

A `Promise` that will be resolved no arguments if the item was successfully removed. If the call failed (for example, because the tab ID could not be found) then 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 code adds two context menu items: one stores a value associated with the current tab, the other one removes it:


```js
async function setOnActiveTab() {
  let tabArray = await browser.tabs.query({
    currentWindow: true,
    active: true,
  });
  let tabId = tabArray[0].id;
  await browser.sessions.setTabValue(tabId, "my-key", "my-value");
}

async function removeFromActiveTab() {
  let tabArray = await browser.tabs.query({
    currentWindow: true,
    active: true,
  });
  let tabId = tabArray[0].id;
  await browser.sessions.removeTabValue(tabId, "my-key");
}

browser.menus.create({
  id: "add-my-item",
  title: "add item",
  contexts: ["all"],
});

browser.menus.create({
  id: "remove-my-item",
  title: "remove item",
  contexts: ["all"],
});

browser.menus.onClicked.addListener((info) => {
  if (info.menuItemId === "add-my-item") {
    setOnActiveTab();
  } else {
    removeFromActiveTab();
  }
});
```
sessions.MAX\_SESSION\_RESULTS
==============================

This value represents the maximum number of sessions that will be returned by a call to `sessions.getRecentlyClosed()`. It is read-only for WebExtension code, and is set to 25.

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.sessions` API.
sessions.Session
================

The `Session` object represents a tab or window that the user has closed in the current browsing session.

Sessions are represented as `Tab` objects if the tab was closed but its window was not closed: for example, because the user clicked the "Close tab" button, and this tab was not the only tab in its window.

Sessions are represented as `Window` objects if the window was closed: for example, because the user clicked the "Close window" button, or closed the only tab open in a window.

Note that different browsers might have a different idea of when a session is a Tab and when it is a Window. For example:

* In Chrome a session is recorded as a Window if the user closes a window that contained more than one tab. If the user closed a window that contained only one tab, this is recorded as a Tab.
* In Firefox, a session is recorded as a Window if the user closes a window (or a tab that was the last tab in the window), and a Tab if the user closes a tab that wasn't the last tab in its window.

The Tab object for a tab that is open will not have a `sessionId`. When the tab is closed, it will have a `sessionId` but will not have a tab `id`. If the tab is restored, it will get a new tab `id` and will lose the `sessionId`.

Type
----

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

`lastModified`

`number`. The time the tab or window was closed, in milliseconds since the epoch.

`tab` Optional

`object`. If the object represents a closed tab, then this property is present and will be a `tabs.Tab` object. This will contain `url`, `title`, and `favIconUrl` only if the extension has the "tabs" permission or host permissions to access the tab's URL.

`window` Optional

`object`. If the object represents a closed window, then this property is present and will be a `windows.Window` object.

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.sessions` API.
sessions.getWindowValue()
=========================

Retrieves a value previously stored by a call to `sessions.setWindowValue`.

You can retrieve a value from a window even over a close/restore cycle: meaning that if you set a value, then the user closes the window, then restores the window using the browser's "restore window" feature (for example, by pressing Control+Shift+N), then you will be able to retrieve the value from the restored window. Note, though, that a restored window does not get the same ID as the original, so the ID you pass into `getWindowValue()` will be different from the ID you passed into `setWindowValue()`, even though they both refer to the same window.

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

Syntax
------


```js
let retrieving = browser.sessions.getWindowValue(
  windowId,    // integer
  key          // string
)
```

### Parameters

`windowId`

`integer`. ID of the window whose data you are trying to retrieve. Error is thrown if ID is invalid.

`key`

`string`. Key identifying the particular value to retrieve. This needs to match the key previously given in `sessions.setWindowValue`.

### Return value

A `Promise` that will be resolved with the value if it exists, or `undefined` if it does not exist. If the call failed (for example, because the window ID could not be found) then 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
--------

Log the value of "my-key" for all newly created windows (this will include any windows that have been restored):


```js
function onGetResolved(r) {
  console.log(`success: ${r}`);
}

function onGetRejected(e) {
  console.log(`error: ${e}`);
}

browser.windows.onCreated.addListener((window) => {
  browser.sessions
    .getWindowValue(window.id, "my-key")
    .then(onGetResolved, onGetRejected);
});
```
sessions.getRecentlyClosed()
============================

Returns an array of `Session` objects, representing windows and tabs that were closed in the current browsing session (that is: the time since the browser was started).

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

Syntax
------


```js
let gettingSessions = browser.sessions.getRecentlyClosed(
  filter             // optional object
)
```

### Parameters

`filter` Optional

`object`. A `sessions.Filter` object that limits the set of sessions returned.

### Return value

A `Promise`. This will be fulfilled with an array of `Session` objects, one for each of the most recently closed tabs or windows in the current browsing session, up to `sessions.MAX_SESSION_RESULTS` or the number included in the `filter` argument, whichever is smaller. The array is given in the reverse of the order in which tabs or windows were closed, so the most recently closed will be at index 0.

If an 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 code restores the single most recently-closed session, whether it's a tab or a window:


```js
function restoreMostRecent(sessionInfos) {
  if (!sessionInfos.length) {
    console.log("No sessions found");
    return;
  }
  let sessionInfo = sessionInfos[0];
  if (sessionInfo.tab) {
    browser.sessions.restore(sessionInfo.tab.sessionId);
  } else {
    browser.sessions.restore(sessionInfo.window.sessionId);
  }
}

function onError(error) {
  console.log(error);
}

browser.browserAction.onClicked.addListener(() => {
  let gettingSessions = browser.sessions.getRecentlyClosed({
    maxResults: 1,
  });
  gettingSessions.then(restoreMostRecent, onError);
});
```


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

Restores a closed tab or window. Restoring doesn't just reopen the tab or window: it also restores the tab's navigation history so the back/forward buttons will work. Restoring a window will restore all the tabs that the window contained when it was closed.

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

Syntax
------


```js
let restoringSession = browser.sessions.restore(
  sessionId             // string
)
```

### Parameters

`sessionId`

`string`. A string containing the session ID for the window or tab to restore. This can be found in the `sessionId` property of the `Tab` or `Window` object in the `Session` returned from `sessions.getRecentlyClosed()`.

### Return value

A `Promise`. This will be fulfilled with a `Session` object representing the session that was restored.

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

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

Examples
--------

This restores the single most recently-closed session, whether it's a window or tab:


```js
function restoreMostRecent(sessionInfos) {
  if (!sessionInfos.length) {
    console.log("No sessions found");
    return;
  }
  let sessionInfo = sessionInfos[0];
  if (sessionInfo.tab) {
    browser.sessions.restore(sessionInfo.tab.sessionId);
  } else {
    browser.sessions.restore(sessionInfo.window.sessionId);
  }
}

function onError(error) {
  console.log(error);
}

browser.browserAction.onClicked.addListener(() => {
  let gettingSessions = browser.sessions.getRecentlyClosed({
    maxResults: 1,
  });
  gettingSessions.then(restoreMostRecent, onError);
});
```


**Note:** This API is based on Chromium's `chrome.sessions` API.

Known issues
------------

Bug 1538119 - Duplicate sessionId in browser.sessions.getRecentlyClosed() after "Restore previous session"