516 lines
16 KiB
TypeScript
516 lines
16 KiB
TypeScript
|
/**
|
||
|
|
* Namespace: browser.menus
|
||
|
|
* Generated from Mozilla sources. Do not manually edit!
|
||
|
|
*
|
||
|
|
* Use the browser.menus API to add items to the browser's menus. You can choose what types of objects your context menu
|
||
|
|
* additions apply to, such as images, hyperlinks, and pages.
|
||
|
|
* Permissions: "menus"
|
||
|
|
*
|
||
|
|
* Comments found in source JSON schema files:
|
||
|
|
* 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.
|
||
|
|
*/
|
||
|
|
import { Extension } from "./extension";
|
||
|
|
import { Tabs } from "./tabs";
|
||
|
|
import { Events } from "./events";
|
||
|
|
|
||
|
|
export namespace Menus {
|
||
|
|
/**
|
||
|
|
* The different contexts a menu can appear in. Specifying 'all' is equivalent to the combination of all other contexts
|
||
|
|
* except for 'tab' and 'tools_menu'.
|
||
|
|
*/
|
||
|
|
type ContextType =
|
||
|
|
| "all"
|
||
|
|
| "page"
|
||
|
|
| "frame"
|
||
|
|
| "selection"
|
||
|
|
| "link"
|
||
|
|
| "editable"
|
||
|
|
| "password"
|
||
|
|
| "image"
|
||
|
|
| "video"
|
||
|
|
| "audio"
|
||
|
|
| "launcher"
|
||
|
|
| "bookmark"
|
||
|
|
| "tab"
|
||
|
|
| "tools_menu"
|
||
|
|
| "browser_action"
|
||
|
|
| "page_action"
|
||
|
|
| "action";
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The type of menu item.
|
||
|
|
*/
|
||
|
|
type ItemType = "normal" | "checkbox" | "radio" | "separator";
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Information sent when a context menu item is clicked.
|
||
|
|
*/
|
||
|
|
interface OnClickData {
|
||
|
|
/**
|
||
|
|
* The ID of the menu item that was clicked.
|
||
|
|
*/
|
||
|
|
menuItemId: number | string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The parent ID, if any, for the item clicked.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
parentMenuItemId?: number | string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The type of view where the menu is clicked. May be unset if the menu is not associated with a view.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
viewType?: Extension.ViewType;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* One of 'image', 'video', or 'audio' if the context menu was activated on one of these types of elements.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
mediaType?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* If the element is a link, the text of that link.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
linkText?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* If the element is a link, the URL it points to.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
linkUrl?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Will be present for elements with a 'src' URL.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
srcUrl?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The URL of the page where the menu item was clicked. This property is not set if the click occured in a context where
|
||
|
|
* there is no current page, such as in a launcher context menu.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
pageUrl?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The id of the frame of the element where the context menu was clicked.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
frameId?: number;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The URL of the frame of the element where the context menu was clicked, if it was in a frame.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
frameUrl?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The text for the context selection, if any.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
selectionText?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A flag indicating whether the element is editable (text input, textarea, etc.).
|
||
|
|
*/
|
||
|
|
editable: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A flag indicating the state of a checkbox or radio item before it was clicked.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
wasChecked?: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A flag indicating the state of a checkbox or radio item after it is clicked.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
checked?: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The id of the bookmark where the context menu was clicked, if it was on a bookmark.
|
||
|
|
*/
|
||
|
|
bookmarkId: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* An array of keyboard modifiers that were held while the menu item was clicked.
|
||
|
|
*/
|
||
|
|
modifiers: OnClickDataModifiersItemEnum[];
|
||
|
|
|
||
|
|
/**
|
||
|
|
* An integer value of button by which menu item was clicked.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
button?: number;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* An identifier of the clicked element, if any. Use menus.getTargetElement in the page to find the corresponding element.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
targetElementId?: number;
|
||
|
|
}
|
||
|
|
|
||
|
|
interface CreateCreatePropertiesType {
|
||
|
|
/**
|
||
|
|
* The type of menu item. Defaults to 'normal' if not specified.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
type?: ItemType;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The unique ID to assign to this item. Mandatory for event pages. Cannot be the same as another ID for this extension.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
id?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
icons?: Record<string, string>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The text to be displayed in the item; this is <em>required</em> unless <code>type</code> is 'separator'.
|
||
|
|
* When the context is 'selection', you can use <code>%s</code> within the string to show the selected text. For example,
|
||
|
|
* if this parameter's value is "Translate '%s' to Pig Latin" and the user selects the word "cool",
|
||
|
|
* the context menu item for the selection is "Translate 'cool' to Pig Latin".
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
title?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The initial state of a checkbox or radio item: true for selected and false for unselected.
|
||
|
|
* Only one radio item can be selected at a time in a given group of radio items.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
checked?: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* List of contexts this menu item will appear in. Defaults to ['page'] if not specified.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
contexts?: ContextType[];
|
||
|
|
|
||
|
|
/**
|
||
|
|
* List of view types where the menu item will be shown. Defaults to any view, including those without a viewType.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
viewTypes?: Extension.ViewType[];
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Whether the item is visible in the menu.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
visible?: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A function that will be called back when the menu item is clicked. Event pages cannot use this; instead,
|
||
|
|
* they should register a listener for $(ref:contextMenus.onClicked).
|
||
|
|
*
|
||
|
|
* @param info Information about the item clicked and the context where the click happened.
|
||
|
|
* @param tab The details of the tab where the click took place. Note: this parameter only present for extensions.
|
||
|
|
*/
|
||
|
|
onclick?(info: OnClickData, tab: Tabs.Tab): void;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The ID of a parent menu item; this makes the item a child of a previously added item.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
parentId?: number | string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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 $(topic:match_patterns)[Match Patterns].
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
documentUrlPatterns?: string[];
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Similar to documentUrlPatterns, but lets you filter based on the src attribute of img/audio/video tags and the href of
|
||
|
|
* anchor tags.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
targetUrlPatterns?: string[];
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Whether this context menu item is enabled or disabled. Defaults to true.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
enabled?: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Specifies a command to issue for the context click.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
command?:
|
||
|
|
| string
|
||
|
|
| "_execute_browser_action"
|
||
|
|
| "_execute_page_action"
|
||
|
|
| "_execute_sidebar_action"
|
||
|
|
| "_execute_action"
|
||
|
|
| "_execute_page_action"
|
||
|
|
| "_execute_sidebar_action";
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The properties to update. Accepts the same values as the create function.
|
||
|
|
*/
|
||
|
|
interface UpdateUpdatePropertiesType {
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
type?: ItemType;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
icons?: Record<string, string>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
title?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
checked?: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
contexts?: ContextType[];
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
viewTypes?: Extension.ViewType[];
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Whether the item is visible in the menu.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
visible?: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @param info
|
||
|
|
* @param tab The details of the tab where the click took place. Note: this parameter only present for extensions.
|
||
|
|
*/
|
||
|
|
onclick?(info: OnClickData, tab: Tabs.Tab): void;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Note: You cannot change an item to be a child of one of its own descendants.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
parentId?: number | string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
documentUrlPatterns?: string[];
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
targetUrlPatterns?: string[];
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
enabled?: boolean;
|
||
|
|
}
|
||
|
|
|
||
|
|
interface OverrideContextContextOptionsType {
|
||
|
|
/**
|
||
|
|
* Whether to also include default menu items in the menu.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
showDefaults?: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* ContextType to override, to allow menu items from other extensions in the menu. Currently only 'bookmark' and 'tab' are
|
||
|
|
* supported. showDefaults cannot be used with this option.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
context?: OverrideContextContextOptionsTypeContextEnum;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Required when context is 'bookmark'. Requires 'bookmark' permission.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
bookmarkId?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Required when context is 'tab'. Requires 'tabs' permission.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
tabId?: number;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Information about the context of the menu action and the created menu items. For more information about each property,
|
||
|
|
* see OnClickData. The following properties are only set if the extension has host permissions for the given context:
|
||
|
|
* linkUrl, linkText, srcUrl, pageUrl, frameUrl, selectionText.
|
||
|
|
*/
|
||
|
|
interface OnShownInfoType {
|
||
|
|
/**
|
||
|
|
* A list of IDs of the menu items that were shown.
|
||
|
|
*/
|
||
|
|
menuIds: Array<number | string>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A list of all contexts that apply to the menu.
|
||
|
|
*/
|
||
|
|
contexts: ContextType[];
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
viewType?: Extension.ViewType;
|
||
|
|
|
||
|
|
editable: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
mediaType?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
linkUrl?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
linkText?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
srcUrl?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
pageUrl?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
frameUrl?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
selectionText?: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
targetElementId?: number;
|
||
|
|
}
|
||
|
|
|
||
|
|
type OnClickDataModifiersItemEnum = "Shift" | "Alt" | "Command" | "Ctrl" | "MacCtrl";
|
||
|
|
|
||
|
|
/**
|
||
|
|
* ContextType to override, to allow menu items from other extensions in the menu. Currently only 'bookmark' and 'tab' are
|
||
|
|
* supported. showDefaults cannot be used with this option.
|
||
|
|
*/
|
||
|
|
type OverrideContextContextOptionsTypeContextEnum = "bookmark" | "tab";
|
||
|
|
|
||
|
|
interface Static {
|
||
|
|
/**
|
||
|
|
* 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 $(ref:runtime.lastError)).
|
||
|
|
*
|
||
|
|
* @param createProperties
|
||
|
|
* @param callback Optional. Called when the item has been created in the browser. If there were any problems creating the
|
||
|
|
* item, details will be available in $(ref:runtime.lastError).
|
||
|
|
* @returns The ID of the newly created item.
|
||
|
|
*/
|
||
|
|
create(createProperties: CreateCreatePropertiesType, callback?: () => void): number | string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Updates a previously created context menu item.
|
||
|
|
*
|
||
|
|
* @param id The ID of the item to update.
|
||
|
|
* @param updateProperties The properties to update. Accepts the same values as the create function.
|
||
|
|
* @returns Called when the context menu has been updated.
|
||
|
|
*/
|
||
|
|
update(id: number | string, updateProperties: UpdateUpdatePropertiesType): Promise<void>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Removes a context menu item.
|
||
|
|
*
|
||
|
|
* @param menuItemId The ID of the context menu item to remove.
|
||
|
|
* @returns Called when the context menu has been removed.
|
||
|
|
*/
|
||
|
|
remove(menuItemId: number | string): Promise<void>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Removes all context menu items added by this extension.
|
||
|
|
*
|
||
|
|
* @returns Called when removal is complete.
|
||
|
|
*/
|
||
|
|
removeAll(): Promise<void>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Show the matching menu items from this extension instead of the default menu. This should be called during a
|
||
|
|
* 'contextmenu' DOM event handler, and only applies to the menu that opens after this event.
|
||
|
|
*
|
||
|
|
* @param contextOptions
|
||
|
|
*/
|
||
|
|
overrideContext(contextOptions: OverrideContextContextOptionsType): void;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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.
|
||
|
|
*/
|
||
|
|
refresh(): Promise<void>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Retrieve the element that was associated with a recent contextmenu event.
|
||
|
|
*
|
||
|
|
* @param targetElementId The identifier of the clicked element, available as info.targetElementId in the menus.onShown,
|
||
|
|
* onClicked or onclick event.
|
||
|
|
*/
|
||
|
|
getTargetElement(targetElementId: number): Element;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Fired when a context menu item is clicked.
|
||
|
|
*
|
||
|
|
* @param info Information about the item clicked and the context where the click happened.
|
||
|
|
* @param tab Optional. 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.
|
||
|
|
*/
|
||
|
|
onClicked: Events.Event<(info: OnClickData, tab: Tabs.Tab | undefined) => void>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Fired when a menu is shown. The extension can add, modify or remove menu items and call menus.refresh()
|
||
|
|
* to update the menu.
|
||
|
|
*
|
||
|
|
* @param info Information about the context of the menu action and the created menu items.
|
||
|
|
* For more information about each property, see OnClickData. The following properties are only set if the extension has
|
||
|
|
* host permissions for the given context: linkUrl, linkText, srcUrl, pageUrl, frameUrl, selectionText.
|
||
|
|
* @param tab The details of the tab where the menu was opened.
|
||
|
|
*/
|
||
|
|
onShown: Events.Event<(info: OnShownInfoType, tab: Tabs.Tab) => void>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Fired when a menu is hidden. This event is only fired if onShown has fired before.
|
||
|
|
*/
|
||
|
|
onHidden: Events.Event<() => void>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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.
|
||
|
|
*/
|
||
|
|
ACTION_MENU_TOP_LEVEL_LIMIT: 6;
|
||
|
|
}
|
||
|
|
}
|