commands

The commands API first appeared in Thunderbird 66. It’s more or less the same as the Firefox commands API.

Use the commands API to add keyboard shortcuts that trigger actions in your extension, for example, an action to open the browser action or send a command to the xtension.

Manifest file properties

[commands]

(object)

Object defining one or more commands as key-value pairs, the key being the name of the command and the value being a CommandsShortcut. The key may also be one of the following built-in special shortcuts:

  • _execute_browser_action

  • _execute_compose_action

  • _execute_message_display_action

Example:

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event"
  },
  "_execute_compose_action": {
    "suggested_key": {
      "default": "Alt+F5"
    },
    "description": "Open the compose action popup"
  }
}

Note

A manifest entry named commands is required to use commands.

Functions

update(detail)

Update the details of an already defined command.

Parameters

detail

(object)

name

(string)

The name of the command.

[description]

(string)

The new description for the command.

[shortcut]

(string)

An empty string to clear the shortcut, or a string matching the format defined by the MDN page of the commands API to set a new shortcut key. If the string does not match this format, the function throws an error.

reset(name)

Reset a command’s details to what is specified in the manifest.

Parameters

name

(string)

The name of the command.

getAll()

Returns all the registered extension commands for this extension and their shortcut (if active).

Return type (Promise)

array of Command

Events

onCommand(command)

Fired when a registered command is activated using a keyboard shortcut. This is a user input event handler. For asynchronous listeners some restrictions apply.

Parameters for event listeners

command

(string)

Types

Command

object

[description]

(string)

The Extension Command description

[name]

(string)

The name of the Extension Command

[shortcut]

(string)

The shortcut active for this command, or blank if not active.

CommandsShortcut

object

[description]

(string)

[suggested_key]

(object)

[default]

Default key combination.

[linux]

Key combination on Linux.

[mac]

Key combination on Mac.

[windows]

Key combination on Windows.

KeyName

Definition of the shortcut, for example Alt+F5. The string must match the shortcut format as defined by the MDN page of the commands API.

string