spacesToolbar API
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
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 of the new button. The url is mandatory.
Return type (Promise)
integer
The id of the space belonging to the newly created button, as used by the tabs API.
Trigger a click on the specified spaces toolbar button. Throws an exception if the requested spaces toolbar button does not exist or was not created by this extension.
Parameters
id
(string)
The id of the spaces toolbar button. May only contain alphanumeric characters and underscores.
[windowId]
(integer, optional)
The id of the normal window, where the spaces toolbar button should be clicked. Defaults to the most recent normal window.
Removes the specified button from the spaces toolbar. Throws an exception if the requested spaces toolbar button does not exist or was not created by this extension. If the tab of this button is currently open, it will be closed.
Parameters
id
(string)
The id of the spaces toolbar button, which is to be removed. May only contain alphanumeric characters and underscores.
Updates properties of the specified spaces toolbar button. Throws an exception if the requested spaces toolbar button does not exist or was not created by this extension.
Parameters
id
(string)
The id of the spaces toolbar button, which is to be updated. May only contain alphanumeric characters and underscores.
Only specified properties will be updated.
Types
object
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, optional)
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.
The paths to one or more icons for the button in the spaces toolbar. Defaults to the extension icon, if set to an empty string.
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, optional)
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, optional)
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.
IconPath
Either a string to specify a relative path of a single icon to be used for all sizes, or a dictionary object to specify paths for multiple icons in different sizes, so the icon does not have to be scaled for a device with a different pixel density. Each entry is a name-value pair with value being a relative path to an icon file, and name its size. Example:
{
"16": "icon16.png",
"32": "icon32.png"
}
See the MDN documentation about choosing icon sizes for more information on this.
ThemeIcons
Define a set of icons for themes depending on whether Thunderbird detects that the theme uses dark or light text. All provided URLs must be relative to the manifest.json file.
object
dark
(string)
A URL pointing to an icon. This icon displays when a theme using dark text is active (such as the Light theme, and the Default theme if no default_icon is specified).
light
(string)
A URL pointing to an icon. This icon displays when a theme using light text is active (such as the Dark theme).
size
(integer)
The size of the two icons in pixels, for example 16 or 32.