path: root/comm/mail/components/extensions/schemas/menus.json

// 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 <value>all</value> is equivalent to the combination of all other contexts excluding <value>tab</value> and <value>tools_menu</value>. More information about each context can be found in the `Supported UI Elements <|link-ui-elements|>`__ 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` for content tabs, :permission:`compose` for compose tabs and :permission:`messagesRead` 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 <value>image</value>, <value>video</value>, or <value>audio</value> 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 messages, if the context menu was opened in the message list. The <permission>messagesRead</permission> permission is required."
          },
          "displayedFolder": {
            "$ref": "folders.MailFolder",
            "optional": true,
            "description": "The displayed folder, if the context menu was opened in the message list. The <permission>accountsRead</permission> permission is required."
          },
          "selectedFolder": {
            "$ref": "folders.MailFolder",
            "optional": true,
            "description": "The selected folder, if the context menu was opened in the folder pane. The <permission>accountsRead</permission> permission is required."
          },
          "selectedAccount": {
            "$ref": "accounts.MailAccount",
            "optional": true,
            "description": "The selected account, if the context menu was opened on an account entry in the folder pane. 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 <value>image</value>, <value>video</value>, or <value>audio</value> 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 messages, if the context menu was opened in the message list. The <permission>messagesRead</permission> permission is required."
          },
          "displayedFolder": {
            "$ref": "folders.MailFolder",
            "optional": true,
            "description": "The displayed folder, if the context menu was opened in the message list. The <permission>accountsRead</permission> permission is required."
          },
          "selectedFolder": {
            "$ref": "folders.MailFolder",
            "optional": true,
            "description": "The selected folder, if the context menu was opened in the folder pane. The <permission>accountsRead</permission> permission is required."
          },
          "selectedAccount": {
            "$ref": "accounts.MailAccount",
            "optional": true,
            "description": "The selected account, if the context menu was opened on an account entry in the folder pane. 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"
                }
              ]
            }
          }
        }
      }
    ],
    "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 `runtime.lastError <|link-runtime-last-error|>`__).",
        "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 <value>normal</value> 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": {
                "$ref": "manifest.IconPath",
                "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 ``type`` is <value>separator</value>. When the context is <value>selection</value>, you can use <value>%s</value> within the string to show the selected text. For example, if this parameter's value is <value>Translate '%s' to Latin</value> and the user selects the word <value>cool</value>, the context menu item for the selection is <value>Translate 'cool' to Latin</value>. To specify an access key for the new menu entry, include a <value>&</value> before the desired letter in the title. For example <value>&Help</value>."
              },
              "checked": {
                "type": "boolean",
                "optional": true,
                "description": "The initial state of a checkbox or radio item: <value>true</value> for selected and <value>false</value> 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 <value>['page']</value> 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 `Match Patterns <|link-match-patterns|>`__."
              },
              "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",
                    "max_manifest_version": 2,
                    "description": "Specifies a command to issue for the context click. Currently supports internal commands <value>_execute_browser_action</value>, <value>_execute_compose_action</value> and <value>_execute_message_display_action</value>."
                  },
                  {
                    "type": "string",
                    "min_manifest_version": 3,
                    "description": "Specifies a command to issue for the context click. Currently supports internal commands <value>_execute_action</value>, <value>_execute_compose_action</value> and <value>_execute_message_display_action</value>."
                  }
                ]
              }
            }
          },
          {
            "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 `runtime.lastError <|link-runtime-last-error|>`__.",
            "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": {
                "$ref": "manifest.IconPath",
                "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 `contextmenu <|link-contextmenu-event|>`__ 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 <value>tab</value> is supported. ``contextOptions.showDefaults`` cannot be used with this option."
              },
              "tabId": {
                "type": "integer",
                "minimum": 0,
                "optional": true,
                "description": "Required when context is <value>tab</value>. 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 `restrictions <|link-user-input-restrictions|>`__ 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": []
      }
    ]
  }
]