commands API

Use the commands API to add keyboard shortcuts that trigger actions in your extension, for example opening one of the action popups or sending a command to the extension.

Thunderbird’s commands API is largely the same as the Firefox commands API.

Manifest file properties

commands

[commands]

(object, optional)

– [Added in TB 66]



A dictionary object defining one or more commands as name-value pairs, the name being the name of the command and the value being a CommandsShortcut.

The name 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"
    }
  }
}

Permissions

Note

A manifest entry named commands is required to use messenger.commands.*.

Functions

getAll()

– [Added in TB 66]

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

Return type (Promise)

_returns

array of Command



openShortcutSettings()

– [Added in TB 137]

Open extension shortcuts configuration page.

reset(name)

– [Added in TB 66]

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

Parameters

name

name

(string)



The name of the command.

update(detail)

– [Added in TB 66]

Update the details of an already defined command.

Parameters

detail

detail

(object)



The new details for the command.

name

name

(string)



The name of the command.

description

[description]

(string, optional)



The description for the command.

shortcut

[shortcut]

(string, optional)



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.

Events

onChanged

– [Added in TB 115]

Fired when a registered command’s shortcut is changed.

Parameters for onChanged.addListener(listener)

listener(changeInfo)

listener(changeInfo)



A function that will be called when this event occurs.

Parameters passed to the listener function

changeInfo

changeInfo

(object)



name

name

(string)



The name of the shortcut.

newShortcut

newShortcut

(string)



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

oldShortcut

oldShortcut

(string)



The old shortcut which is no longer active for this command, or blank if the shortcut was previously inactive.

onCommand

– [Added in TB 66]

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 onCommand.addListener(listener)

listener(command, tab)

listener(command, tab)



A function that will be called when this event occurs.

Parameters passed to the listener function

command

command

(string)



tab

tab