Revision control
Copy as Markdown
Other Tools
// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
[
{
"namespace": "manifest",
"types": [
{
"$extend": "PermissionNoPrompt",
"choices": [
{
"type": "string",
"enum": ["menus"]
}
]
},
{
"$extend": "OptionalPermissionNoPrompt",
"choices": [
{
"type": "string",
"enum": ["menus.overrideContext"]
}
]
}
]
},
{
"namespace": "menus",
"permissions": ["menus"],
"description": "The menus API allows to add items to Thunderbird's menus. You can choose what types of objects your context menu additions apply to, such as images, hyperlinks, and pages.",
"properties": {
"ACTION_MENU_TOP_LEVEL_LIMIT": {
"value": 6,
"description": "The maximum number of top level extension items that can be added to an extension action context menu. Any items beyond this limit will be ignored."
}
},
"types": [
{
"id": "ContextType",
"choices": [
{
"type": "string",
"enum": [
"all",
"all_message_attachments",
"audio",
"compose_action",
"compose_action_menu",
"compose_attachments",
"compose_body",
"editable",
"folder_pane",
"frame",
"image",
"link",
"message_attachments",
"message_display_action",
"message_display_action_menu",
"message_list",
"page",
"password",
"selection",
"tab",
"tools_menu",
"video"
]
},
{
"type": "string",
"max_manifest_version": 2,
"enum": ["browser_action", "browser_action_menu"]
},
{
"type": "string",
"min_manifest_version": 3,
"enum": ["action", "action_menu"]
}
],
"description": "The different contexts a menu can appear in. Specifying <var>all</var> is equivalent to the combination of all other contexts excluding <var>tab</var> and <var>tools_menu</var>. More information about each context can be found in the <a href='url-ui-elements'>Supported UI Elements</a> article on developer.thunderbird.net."
},
{
"id": "ItemType",
"type": "string",
"enum": ["normal", "checkbox", "radio", "separator"],
"description": "The type of menu item."
},
{
"id": "OnShowData",
"type": "object",
"description": "Information sent when a context menu is being shown. Some properties are only included if the extension has host permission for the given context, for example <permission>activeTab</permission> for content tabs, <permission>compose</permission> for compose tabs and <permission>messagesRead</permission> for message display tabs.",
"properties": {
"menuIds": {
"description": "A list of IDs of the menu items that were shown.",
"type": "array",
"items": {
"choices": [
{
"type": "integer"
},
{
"type": "string"
}
]
}
},
"contexts": {
"description": "A list of all contexts that apply to the menu.",
"type": "array",
"items": {
"$ref": "ContextType"
}
},
"editable": {
"type": "boolean",
"description": "A flag indicating whether the element is editable (text input, textarea, etc.)."
},
"mediaType": {
"type": "string",
"optional": true,
"description": "One of <var>image</var>, <var>video</var>, or <var>audio</var> if the context menu was activated on one of these types of elements."
},
"viewType": {
"$ref": "extension.ViewType",
"optional": true,
"description": "The type of view where the menu is shown. May be unset if the menu is not associated with a view."
},
"linkText": {
"type": "string",
"optional": true,
"description": "If the element is a link, the text of that link. **Note:** Host permission is required."
},
"linkUrl": {
"type": "string",
"optional": true,
"description": "If the element is a link, the URL it points to. **Note:** Host permission is required."
},
"srcUrl": {
"type": "string",
"description": "Will be present for elements with a <em>src</em> URL. **Note:** Host permission is required.",
"optional": true
},
"pageUrl": {
"type": "string",
"description": "The URL of the page where the menu item was clicked. This property is not set if the click occurred in a context where there is no current page, such as in a launcher context menu. **Note:** Host permission is required.",
"optional": true
},
"frameUrl": {
"type": "string",
"description": "The URL of the frame of the element where the context menu was clicked, if it was in a frame. **Note:** Host permission is required.",
"optional": true
},
"selectionText": {
"type": "string",
"description": "The text for the context selection, if any. **Note:** Host permission is required.",
"optional": true
},
"targetElementId": {
"type": "integer",
"optional": true,
"description": "An identifier of the clicked content element, if any. Use $(ref:menus.getTargetElement) in the page to find the corresponding element."
},
"fieldId": {
"type": "string",
"optional": true,
"description": "An identifier of the clicked Thunderbird UI element, if any.",
"enum": [
"composeSubject",
"composeTo",
"composeCc",
"composeBcc",
"composeReplyTo",
"composeNewsgroupTo"
]
},
"selectedMessages": {
"$ref": "messages.MessageList",
"optional": true,
"description": "The selected message(s) in the message list (a.k.a. the thread pane). Only available for the <var>message_list</var> context. The <permission>messagesRead</permission> permission is required. The returned selection includes the messages which would be affected by a context action through Thunderbirds UI, which may not be the actuall selected messages. For example, if the user has multiple messages selected and opens the context menu for a message outside that selection, only the message for which the context menu was opened, is returned."
},
"displayedFolder": {
"$ref": "folders.MailFolder",
"optional": true,
"description": "The displayed folder. Only available for the <var>message_list</var> context. The <permission>accountsRead</permission> permission is required."
},
"selectedFolder": {
"$ref": "folders.MailFolder",
"max_manifest_version": 2,
"optional": true,
"deprecated": "Deprecated since Thunderbird 128 and removed in Manifest V3: The selectedFolder property has been replaced by the selectedFolders property.",
"description": "The selected folder in the folder pane (where the context menu was opened). Only available for the <var>folder_pane</var> context. The <permission>accountsRead</permission> permission is required."
},
"selectedFolders": {
"type": "array",
"items": {
"$ref": "folders.MailFolder"
},
"optional": true,
"description": "The selected folders in the folder pane. Only available for the <var>folder_pane</var> context. The <permission>accountsRead</permission> permission is required. The returned selection includes the folders which would be affected by a context action through Thunderbirds UI, which may not be the actuall selected folders. For example, if the user has multiple folders selected and opens the context menu for a folder outside that selection, only the folder for which the context menu was opened, is returned."
},
"selectedAccount": {
"$ref": "accounts.MailAccount",
"max_manifest_version": 2,
"optional": true,
"deprecated": "Deprecated since Thunderbird 128 and removed in Manifest V3: The selectedAccount property has been replaced by the selectedFolders property, returning the root folder of the account.",
"description": "The selected account in the folder pane, if the context menu was opened on an account entry. Only available for the <var>folder_pane</var> context. The <permission>accountsRead</permission> permission is required."
},
"attachments": {
"type": "array",
"optional": true,
"description": "The selected attachments. The <permission>compose</permission> permission is required to return attachments of a message being composed. The <permission>messagesRead</permission> permission is required to return attachments of displayed messages.",
"items": {
"choices": [
{
"$ref": "compose.ComposeAttachment"
},
{
"$ref": "messages.MessageAttachment"
}
]
}
}
}
},
{
"id": "OnClickData",
"type": "object",
"description": "Information sent when a context menu item is clicked.",
"properties": {
"menuItemId": {
"choices": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "The ID of the menu item that was clicked."
},
"parentMenuItemId": {
"choices": [
{
"type": "integer"
},
{
"type": "string"
}
],
"optional": true,
"description": "The parent ID, if any, for the item clicked."
},
"editable": {
"type": "boolean",
"description": "A flag indicating whether the element is editable (text input, textarea, etc.)."
},
"mediaType": {
"type": "string",
"optional": true,
"description": "One of <var>image</var>, <var>video</var>, or <var>audio</var> if the context menu was activated on one of these types of elements."
},
"viewType": {
"$ref": "extension.ViewType",
"optional": true,
"description": "The type of view where the menu is clicked. May be unset if the menu is not associated with a view."
},
"linkText": {
"type": "string",
"optional": true,
"description": "If the element is a link, the text of that link."
},
"linkUrl": {
"type": "string",
"optional": true,
"description": "If the element is a link, the URL it points to."
},
"srcUrl": {
"type": "string",
"optional": true,
"description": "Will be present for elements with a <em>src</em> URL."
},
"pageUrl": {
"type": "string",
"optional": true,
"description": "The URL of the page where the menu item was clicked. This property is not set if the click occurred in a context where there is no current page, such as in a launcher context menu."
},
"frameId": {
"type": "integer",
"optional": true,
"minimum": 0,
"description": "The id of the frame of the element where the context menu was clicked."
},
"frameUrl": {
"type": "string",
"optional": true,
"description": "The URL of the frame of the element where the context menu was clicked, if it was in a frame."
},
"selectionText": {
"type": "string",
"optional": true,
"description": "The text for the context selection, if any."
},
"wasChecked": {
"type": "boolean",
"optional": true,
"description": "A flag indicating the state of a checkbox or radio item before it was clicked."
},
"checked": {
"type": "boolean",
"optional": true,
"description": "A flag indicating the state of a checkbox or radio item after it is clicked."
},
"modifiers": {
"type": "array",
"items": {
"type": "string",
"enum": ["Shift", "Alt", "Command", "Ctrl", "MacCtrl"]
},
"description": "An array of keyboard modifiers that were held while the menu item was clicked."
},
"button": {
"type": "integer",
"optional": true,
"description": "An integer value of button by which menu item was clicked."
},
"targetElementId": {
"type": "integer",
"optional": true,
"description": "An identifier of the clicked content element, if any. Use $(ref:menus.getTargetElement) in the page to find the corresponding element."
},
"fieldId": {
"type": "string",
"optional": true,
"description": "An identifier of the clicked Thunderbird UI element, if any.",
"enum": [
"composeSubject",
"composeTo",
"composeCc",
"composeBcc",
"composeReplyTo",
"composeNewsgroupTo"
]
},
"selectedMessages": {
"$ref": "messages.MessageList",
"optional": true,
"description": "The selected message(s) in the message list (a.k.a. the thread pane). Only available for the <var>message_list</var> context. The <permission>messagesRead</permission> permission is required. The returned selection includes the messages which would be affected by a context action through Thunderbirds UI, which may not be the actuall selected messages. For example, if the user has multiple messages selected and opens the context menu for a message outside that selection, only the message for which the context menu was opened, is returned."
},
"displayedFolder": {
"$ref": "folders.MailFolder",
"optional": true,
"description": "The displayed folder. Only available for the <var>message_list</var> context. The <permission>accountsRead</permission> permission is required."
},
"selectedFolder": {
"$ref": "folders.MailFolder",
"max_manifest_version": 2,
"optional": true,
"deprecated": "Deprecated since Thunderbird 128 and removed in Manifest V3: The selectedFolder property has been replaced by the selectedFolders property.",
"description": "The selected folder in the folder pane (where the context menu was opened). Only available for the <var>folder_pane</var> context. The <permission>accountsRead</permission> permission is required."
},
"selectedFolders": {
"type": "array",
"items": {
"$ref": "folders.MailFolder"
},
"optional": true,
"description": "The selected folders in the folder pane. Only available for the <var>folder_pane</var> context. The <permission>accountsRead</permission> permission is required. The returned selection includes the folders which would be affected by a context action through Thunderbirds UI, which may not be the actuall selected folders. For example, if the user has multiple folders selected and opens the context menu for a folder outside that selection, only the folder for which the context menu was opened, is returned."
},
"selectedAccount": {
"$ref": "accounts.MailAccount",
"max_manifest_version": 2,
"optional": true,
"deprecated": "Deprecated since Thunderbird 128 and removed in Manifest V3: The selectedAccount property has been replaced by the selectedFolders property, returning the root folder of the account.",
"description": "The selected account in the folder pane, if the context menu was opened on an account entry. Only available for the <var>folder_pane</var> context. The <permission>accountsRead</permission> permission is required."
},
"attachments": {
"type": "array",
"optional": true,
"description": "The selected attachments. The <permission>compose</permission> permission is required to return attachments of a message being composed. The <permission>messagesRead</permission> permission is required to return attachments of displayed messages.",
"items": {
"choices": [
{
"$ref": "compose.ComposeAttachment"
},
{
"$ref": "messages.MessageAttachment"
}
]
}
}
}
},
{
"id": "MenuIconPath",
"choices": [
{
"type": "string",
"format": "imageDataOrStrictRelativeUrl"
},
{
"type": "string",
"pattern": "^(moz-extension|blob|http|https):.*$"
}
],
"description": "The path for a menu icon may be a relative path to an icon file, a <var>moz-extension:</var> URL, an image <var>data:</var> URL, a <var>blob:</var> URL, or a remote <var>http(s):</var> URL."
},
{
"id": "MenuIconDictionary",
"type": "object",
"patternProperties": {
"^[1-9]\\d*$": {
"$ref": "MenuIconPath"
}
},
"description": "A <em>dictionary object</em> to specify paths for multiple icons in different sizes, so the best matching icon can be used, instead of scaling a standard icon to fit the pixel density of the user's display. Each entry is a <em>name-value</em> pair, with <em>name</em> being a size and <em>value</em> being a $(ref:menus.MenuIconPath). Example: <literalinclude>includes/IconPath.json<lang>JSON</lang></literalinclude>See the <a href='url-choosing-icon-size'>MDN documentation about choosing icon sizes</a> for more information on this. "
},
{
"id": "MenuActionCommand",
"choices": [
{
"type": "string",
"enum": [
"_execute_browser_action",
"_execute_compose_action",
"_execute_message_display_action"
],
"max_manifest_version": 2
},
{
"type": "string",
"enum": [
"_execute_action",
"_execute_compose_action",
"_execute_message_display_action"
],
"min_manifest_version": 3
}
],
"description": "A predefined command to open an action popup."
}
],
"functions": [
{
"name": "create",
"type": "function",
"description": "Creates a new context menu item. Note that if an error occurs during creation, you may not find out until the creation callback fires (the details will be in <a href='url-runtime-last-error'>runtime.lastError</a>).",
"returns": {
"choices": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "The ID of the newly created item."
},
"parameters": [
{
"type": "object",
"name": "createProperties",
"properties": {
"type": {
"$ref": "ItemType",
"optional": true,
"description": "The type of menu item. Defaults to <var>normal</var> if not specified."
},
"id": {
"type": "string",
"optional": true,
"description": "The unique ID to assign to this item. Mandatory for event pages. Cannot be the same as another ID for this extension."
},
"icons": {
"choices": [
{
"$ref": "MenuIconPath"
},
{
"$ref": "MenuIconDictionary"
}
],
"optional": true,
"description": "Custom icons to display next to the menu item. Custom icons can only be set for items appearing in submenus."
},
"title": {
"type": "string",
"optional": true,
"description": "The text to be displayed in the item; this is <em>required</em> unless <var>type</var> is <var>separator</var>. When the context is <var>selection</var>, you can use <var>%s</var> within the string to show the selected text. For example, if this parameter's value is <var>Translate '%s' to Latin</var> and the user selects the word <var>cool</var>, the context menu item for the selection is <var>Translate 'cool' to Latin</var>. To specify an access key for the new menu entry, include a <var>&</var> before the desired letter in the title. For example <var>&Help</var>."
},
"checked": {
"type": "boolean",
"optional": true,
"description": "The initial state of a checkbox or radio item: <var>true</var> for selected and <var>false</var> for unselected. Only one radio item can be selected at a time in a given group of radio items."
},
"contexts": {
"type": "array",
"items": {
"$ref": "ContextType"
},
"minItems": 1,
"optional": true,
"description": "List of contexts this menu item will appear in. Defaults to <var>['page']</var> if not specified."
},
"viewTypes": {
"type": "array",
"items": {
"$ref": "extension.ViewType"
},
"minItems": 1,
"optional": true,
"description": "List of view types where the menu item will be shown. Defaults to any view, including those without a viewType."
},
"visible": {
"type": "boolean",
"optional": true,
"description": "Whether the item is visible in the menu."
},
"onclick": {
"type": "function",
"optional": true,
"description": "A function that will be called back when the menu item is clicked. Event pages cannot use this.",
"parameters": [
{
"name": "info",
"$ref": "OnClickData",
"description": "Information about the item clicked and the context where the click happened."
},
{
"name": "tab",
"$ref": "tabs.Tab",
"description": "The details of the tab where the click took place."
}
]
},
"parentId": {
"choices": [
{
"type": "integer"
},
{
"type": "string"
}
],
"optional": true,
"description": "The ID of a parent menu item; this makes the item a child of a previously added item."
},
"documentUrlPatterns": {
"type": "array",
"items": {
"type": "string"
},
"optional": true,
"description": "Lets you restrict the item to apply only to documents whose URL matches one of the given patterns. (This applies to frames as well.) For details on the format of a pattern, see <a href='url-match-patterns'>Match Patterns</a>."
},
"targetUrlPatterns": {
"type": "array",
"items": {
"type": "string"
},
"optional": true,
"description": "Similar to documentUrlPatterns, but lets you filter based on the src attribute of img/audio/video tags and the href of anchor tags."
},
"enabled": {
"type": "boolean",
"optional": true,
"description": "Whether this context menu item is enabled or disabled. Defaults to true."
},
"command": {
"optional": true,
"choices": [
{
"type": "string"
},
{
"$ref": "menus.MenuActionCommand"
}
],
"description": "Specifies a command to issue for the context click. Can either be a user defined command, or one of the predefined action commands."
}
}
},
{
"type": "function",
"name": "callback",
"optional": true,
"description": "Called when the item has been created in the browser. If there were any problems creating the item, details will be available in <a href='url-runtime-last-error'>runtime.lastError</a>.",
"parameters": []
}
]
},
{
"name": "update",
"type": "function",
"description": "Updates a previously created context menu item.",
"async": "callback",
"parameters": [
{
"choices": [
{
"type": "integer"
},
{
"type": "string"
}
],
"name": "id",
"description": "The ID of the item to update."
},
{
"type": "object",
"name": "updateProperties",
"description": "The properties to update. Accepts the same values as the create function.",
"properties": {
"type": {
"$ref": "ItemType",
"optional": true
},
"icons": {
"choices": [
{
"$ref": "MenuIconPath"
},
{
"$ref": "MenuIconDictionary"
}
],
"optional": "omit-key-if-missing"
},
"title": {
"type": "string",
"optional": true
},
"checked": {
"type": "boolean",
"optional": true
},
"contexts": {
"type": "array",
"items": {
"$ref": "ContextType"
},
"minItems": 1,
"optional": true
},
"viewTypes": {
"type": "array",
"items": {
"$ref": "extension.ViewType"
},
"minItems": 1,
"optional": true
},
"visible": {
"type": "boolean",
"optional": true,
"description": "Whether the item is visible in the menu."
},
"onclick": {
"type": "function",
"optional": "omit-key-if-missing",
"parameters": [
{
"name": "info",
"$ref": "OnClickData"
},
{
"name": "tab",
"$ref": "tabs.Tab",
"description": "The details of the tab where the click took place. **Note:** this parameter only present for extensions."
}
]
},
"parentId": {
"choices": [
{
"type": "integer"
},
{
"type": "string"
}
],
"optional": true,
"description": "**Note:** You cannot change an item to be a child of one of its own descendants."
},
"documentUrlPatterns": {
"type": "array",
"items": {
"type": "string"
},
"optional": true
},
"targetUrlPatterns": {
"type": "array",
"items": {
"type": "string"
},
"optional": true
},
"enabled": {
"type": "boolean",
"optional": true
}
}
},
{
"type": "function",
"name": "callback",
"optional": true,
"parameters": [],
"description": "Called when the context menu has been updated."
}
]
},
{
"name": "remove",
"type": "function",
"description": "Removes a context menu item.",
"async": "callback",
"parameters": [
{
"choices": [
{
"type": "integer"
},
{
"type": "string"
}
],
"name": "menuItemId",
"description": "The ID of the context menu item to remove."
},
{
"type": "function",
"name": "callback",
"optional": true,
"parameters": [],
"description": "Called when the context menu has been removed."
}
]
},
{
"name": "removeAll",
"type": "function",
"description": "Removes all context menu items added by this extension.",
"async": "callback",
"parameters": [
{
"type": "function",
"name": "callback",
"optional": true,
"parameters": [],
"description": "Called when removal is complete."
}
]
},
{
"name": "overrideContext",
"permissions": ["menus.overrideContext"],
"type": "function",
"description": "Show the matching menu items from this extension instead of the default menu. This should be called during a <a href='url-contextmenu-event'>contextmenu</a> event handler, and only applies to the menu that opens after this event.",
"parameters": [
{
"name": "contextOptions",
"type": "object",
"properties": {
"showDefaults": {
"type": "boolean",
"optional": true,
"default": false,
"description": "Whether to also include default menu items in the menu."
},
"context": {
"type": "string",
"enum": ["tab"],
"optional": true,
"description": "ContextType to override, to allow menu items from other extensions in the menu. Currently only <var>tab</var> is supported. <var>contextOptions.showDefaults</var> cannot be used with this option."
},
"tabId": {
"type": "integer",
"minimum": 0,
"optional": true,
"description": "Required when context is <var>tab</var>. Requires the <permission>tabs</permission> permission."
}
}
}
]
},
{
"name": "refresh",
"type": "function",
"description": "Updates the extension items in the shown menu, including changes that have been made since the menu was shown. Has no effect if the menu is hidden. Rebuilding a shown menu is an expensive operation, only invoke this method when necessary.",
"async": true,
"parameters": []
}
],
"events": [
{
"name": "onClicked",
"type": "function",
"description": "Fired when a context menu item is clicked. This is a user input event handler. For asynchronous listeners some <a href='url-user-input-restrictions'>restrictions</a> apply.",
"parameters": [
{
"name": "info",
"$ref": "OnClickData",
"description": "Information about the item clicked and the context where the click happened."
},
{
"name": "tab",
"$ref": "tabs.Tab",
"description": "The details of the tab where the click took place. If the click did not take place in a tab, this parameter will be missing.",
"optional": true
}
]
},
{
"name": "onShown",
"type": "function",
"description": "Fired when a menu is shown. The extension can add, modify or remove menu items and call $(ref:menus.refresh) to update the menu.",
"parameters": [
{
"name": "info",
"$ref": "OnShowData",
"description": "Information about the context of the menu action and the created menu items."
},
{
"name": "tab",
"$ref": "tabs.Tab",
"description": "The details of the tab where the menu was opened."
}
]
},
{
"name": "onHidden",
"type": "function",
"description": "Fired when a menu is hidden. This event is only fired if onShown has fired before.",
"parameters": []
}
]
}
]