messageDisplayAction API
Use a messageDisplayAction to put a button in the message display toolbar. In addition to its icon, a messageDisplayAction button can also have a tooltip, a badge, and a popup.
Manifest file properties
message_display_action
browser_style
Enable browser styles. See the MDN documentation on browser styles for more information.
default_area
Currently unused.
default_icon
The paths to one or more icons for the messageDisplayAction button.
default_label
The label of the messageDisplayAction button, defaults to its title. Can be set to an empty string to not display any label. If the containing toolbar is configured to display text only, the title will be used as fallback.
default_popup
The html document to be opened as a popup when the user clicks on the messageDisplayAction button. Ignored for action buttons with type menu.
default_title
The title of the messageDisplayAction button. This shows up in the tooltip and the label. Defaults to the add-on name.
theme_icons
Specifies dark and light icons to be used with themes. The light icon is used on dark backgrounds and vice versa. The default theme uses the default_icon for light backgrounds (if specified).
type
Permissions
Functions
disable([tabId])
– [Added in TB 71]
Disables the messageDisplayAction button for a specific tab (if a tabId is provided), or for all tabs which do not have a custom enable state. Once the enable state of a tab has been updated individually, all further changes to its state have to be done individually as well.
Parameters
tabId
The id of the tab for which you want to modify the messageDisplayAction button.
enable([tabId])
– [Added in TB 71]
Enables the messageDisplayAction button for a specific tab (if a tabId is provided), or for all tabs which do not have a custom enable state. Once the enable state of a tab has been updated individually, all further changes to its state have to be done individually as well. By default, a messageDisplayAction button is enabled.
Parameters
tabId
The id of the tab for which you want to modify the messageDisplayAction button.
getBadgeBackgroundColor(details)
– [Added in TB 71]
Gets the badge background color of the messageDisplayAction button.
Parameters
details
getBadgeText(details)
– [Added in TB 71]
Gets the badge text of the messageDisplayAction button.
Parameters
details
getBadgeTextColor(details)
– [Added in TB 128]
Gets the text color of the badge.
Parameters
details
getLabel(details)
– [Added in TB 85]
Gets the label of the messageDisplayAction button. Returns null, if no label has been set and the title is used.
Parameters
details
getPopup(details)
– [Added in TB 71]
Gets the html document set as the popup for this messageDisplayAction button.
Parameters
details
getTitle(details)
– [Added in TB 71]
Gets the title of the messageDisplayAction button.
Parameters
details
isEnabled(details)
– [Added in TB 71]
Checks whether the messageDisplayAction button is enabled.
Parameters
details
openPopup([options])
– [Added in TB 71]
Opens the action’s popup window in the specified window. Defaults to the current window. Returns false if the popup could not be opened because the action has no popup, is of type menu, is disabled or has been removed from the toolbar.
Parameters
options
setBadgeBackgroundColor(details)
– [Added in TB 71]
Sets the background color for the badge.
Parameters
details
color
The color to use as background in the badge. Cleared by setting it to null.
tabId
Sets the background color for the badge only for the given tab.
windowId
Will throw an error if used.
setBadgeText(details)
– [Added in TB 71]
Sets the badge text for the messageDisplayAction button. The badge is displayed on top of the icon.
Parameters
details
text
Any number of characters can be passed, but only about four can fit in the space. Cleared by setting it to null or an empty string.
tabId
Sets the badge text only for the given tab.
windowId
Will throw an error if used.
setBadgeTextColor(details)
– [Added in TB 128]
Sets the text color for the badge.
Parameters
details
color
The color to use as text color in the badge. Cleared by setting it to null.
tabId
Sets the text color for the badge only for the given tab.
windowId
Will throw an error if used.
setIcon(details)
– [Added in TB 71]
Sets the icon for the messageDisplayAction button. Either the path or the imageData property must be specified.
Parameters
details
imageData
The image data for one or more icons for the composeAction button.
path
tabId
Sets the icon only for the given tab.
windowId
Will throw an error if used.
setLabel(details)
– [Added in TB 85]
Sets the label of the messageDisplayAction button. Can be used to set different values for the tooltip (defined by the title) and the label. Additionally, the label can be set to an empty string, not showing any label at all.
Parameters
details
label
A string the messageDisplayAction button should use as its label, overriding the defined title. Can be set to an empty string to not display any label at all. If the containing toolbar is configured to display text only, its title will be used. Cleared by setting it to null.
tabId
Sets the label only for the given tab.
windowId
Will throw an error if used.
setPopup(details)
– [Added in TB 71]
Sets the html document to be opened as a popup when the user clicks on the messageDisplayAction button.
Parameters
details
popup
The html file to show in a popup. Can be set to an empty string to not open a popup. Cleared by setting it to null (action will use the popup value defined in the manifest).
tabId
Sets the popup only for the given tab.
windowId
Will throw an error if used.
setTitle(details)
– [Added in TB 71]
Sets the title of the messageDisplayAction button. Is used as tooltip and as the label.
Parameters
details
title
A string the messageDisplayAction button should display as its label and when moused over. Cleared by setting it to null or an empty string (title defined the manifest will be used).
tabId
Sets the title only for the given tab.
windowId
Will throw an error if used.
Events
onClicked
– [Added in TB 71]
Fired when a messageDisplayAction button is clicked. This event will not fire if the messageDisplayAction has a popup. This is a user input event handler. For asynchronous listeners some restrictions apply.
Parameters for onClicked.addListener(listener)
listener(tab, info)
A function that will be called when this event occurs.
Parameters passed to the listener function
tab
info
Types
ColorArray
– [Added in TB 71]
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
ExtensionFileUrl
string
ExtensionURL
A path relative to the root of the extension.
string
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 topic.
object
or
ImageDataDictionary
– [Added in TB 90]
A dictionary object to specify multiple ImageData objects 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 an ImageData object, and name its size.
object
ImageDataType
– [Added in TB 71]
Pixel data for an image. Must be an ImageData object (for example, from a canvas element).
OnClickData
– [Added in TB 74]
Information sent when a messageDisplayAction button is clicked.
object
modifiers
An array of keyboard modifiers that were held while the menu item was clicked.
Supported values:
Alt
Command
Only available on macOS.
Ctrl
Not available on macOS.
MacCtrl
Only available on macOS, but of limited use in a click event: Holding down the CTRL key while clicking with the mouse is referred to as a ‘CTRL click’ under macOS and is interpreted as a right mouse click. In a default profile the dom.event.treat_ctrl_click_as_right_click.disabled preference is not enabled and the MacCtrl modifier key is not forwarded to the API.
Shift
button
An integer value of button by which menu item was clicked.
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
The dark icon to use for light themes
light
A light icon to use for dark themes
size
The size of the icons