spacesToolbar

The spacesToolbar API first appeared in Thunderbird 100. It allows to add buttons to Thunderbird’s spaces toolbar. These buttons are shortcuts to open html pages in a new tab.

Warning

This API will change in future releases of Thunderbird.

Functions

addButton(id, properties)

Adds a new button to the spaces toolbar. Throws an exception, if the used id is not unique within the extension.

Parameters

id

(string)

The unique id to assign to this button. May only contain alphanumeric characters and underscores.

properties

Properties of the new button. The url is mandatory.

removeButton(id)

Removes the specified button from the spaces toolbar. Throws an exception if the requested spaces toolbar button does not exist. If the tab of this button is currently open, it will be closed.

Parameters

id

(string)

The id of the button which is to be removed. May only contain alphanumeric characters and underscores.

updateButton(id, properties)

Updates properties of the specified spaces toolbar button. Throws an exception if the requested spaces toolbar button does not exist.

Parameters

id

(string)

The id of the button which is to be updated. May only contain alphanumeric characters and underscores.

properties

Only specified properties will be updated.

Types

ButtonProperties

object

[badgeBackgroundColor]

(string or ColorArray)

Sets the background color of the badge. Can be specified as an array of four integers in the range [0,255] that make up the RGBA color of the badge. For example, opaque red is [255, 0, 0, 255]. Can also be a string with an HTML color name (red) or a HEX color value (#FF0000 or #F00). Reset when set to an empty string.

[badgeText]

(string)

Sets the badge text for the spaces toolbar button. The badge is displayed on top of the icon. Any number of characters can be set, but only about four can fit in the space. Removed when set to an empty string.

[defaultIcons]

(string or IconPathDictionary)

Either a relative image path defining a single icon used for all sizes or an IconPathDictionary object defining dedicated icons for different sizes. At least the 16px icon should be specified. The 32px icon will be used on screens with a very high pixel density, if specified. Defaults to the extension icon, if set to an empty string.

[themeIcons]

(array of spacesToolbar.ThemeIcons)

Specifies dark and light icons for the spaces toolbar button to be used with themes: The light icons will be used on dark backgrounds and vice versa. At least the set for 16px icons should be specified. The set for 32px icons will be used on screens with a very high pixel density, if specified.

[title]

(string)

The title for the spaces toolbar button, used in the tooltip of the button and as the displayed name in the overflow menu. Defaults to the name of the extension, if set to an empty string.

[url]

(string)

The page url, loaded into a tab when the button is clicked. Supported are https:// and http:// links, as well as links to WebExtension pages.

ColorArray

An array of four integers in the range [0,255] that make up the RGBA color. For example, opaque red is [255, 0, 0, 255].

array of integer

External Types

The following types are not defined by this API, but by the underlying Mozilla WebExtension code base. They are included here, because there is no other public documentation available.

IconPathDictionary

A {size: path} dictionary representing the icon to be set. The actual image to be used is chosen depending on the screen’s pixel density. See the MDN documentation about choosing icon sizes for more information on this. At least one icon must be specified. Example:

{
  "48": "icon48.png",
  "96": "icon96.png"
}