@theia/core/lib/common/menu/menu-types.d.ts

Theia is a cloud & desktop IDE framework implemented in TypeScript.

import { Disposable } from '../disposable';
export declare type MenuPath = string[];
export declare const MAIN_MENU_BAR: MenuPath;
export declare const SETTINGS_MENU: MenuPath;
export declare const ACCOUNTS_MENU: MenuPath;
export declare const ACCOUNTS_SUBMENU: string[];
/**
 * @internal For most use cases, refer to {@link MenuAction} or {@link MenuNode}
 */
export interface MenuNodeMetadata {
    /**
     * technical identifier.
     */
    readonly id: string;
    /**
     * Menu nodes are sorted in ascending order based on their `sortString`.
     */
    readonly sortString: string;
    /**
     * Condition under which the menu node should be rendered.
     * See https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts
     */
    readonly when?: string;
    /**
     * A reference to the parent node - useful for determining the menu path by which the node can be accessed.
     */
    readonly parent?: MenuNode;
}
/**
 * Metadata for the visual presentation of a node.
 * @internal For most uses cases, refer to {@link MenuNode}, {@link CommandMenuNode}, or {@link CompoundMenuNode}
 */
export interface MenuNodeRenderingData {
    /**
     * Optional label. Will be rendered as text of the menu item.
     */
    readonly label?: string;
    /**
     * Icon classes for the menu node. If present, these will produce an icon to the left of the label in browser-style menus.
     */
    readonly icon?: string;
}
/** @internal For most use cases refer to {@link MenuNode}, {@link CommandMenuNode}, or {@link CompoundMenuNode} */
export interface MenuNodeBase extends MenuNodeMetadata, MenuNodeRenderingData {
}
/**
 * A menu entry representing an action, e.g. "New File".
 */
export interface MenuAction extends MenuNodeRenderingData, Pick<MenuNodeMetadata, 'when'> {
    /**
     * The command to execute.
     */
    commandId: string;
    /**
     * In addition to the mandatory command property, an alternative command can be defined.
     * It will be shown and invoked when pressing Alt while opening a menu.
     */
    alt?: string;
    /**
     * Menu entries are sorted in ascending order based on their `order` strings. If omitted the determined
     * label will be used instead.
     */
    order?: string;
}
export declare namespace MenuAction {
    function is(arg: unknown): arg is MenuAction;
}
/**
 * Additional options when creating a new submenu.
 */
export interface SubMenuOptions extends Pick<MenuAction, 'order'>, Pick<MenuNodeMetadata, 'when'>, Partial<Pick<CompoundMenuNode, 'role' | 'label' | 'icon'>> {
    /**
     * The class to use for the submenu icon.
     * @deprecated use `icon` instead;
     */
    iconClass?: string;
}
export declare const enum CompoundMenuNodeRole {
    /** Indicates that the node should be rendered as submenu that opens a new menu on hover */
    Submenu = 0,
    /** Indicates that the node's children should be rendered as group separated from other items by a separator */
    Group = 1,
    /** Indicates that the node's children should be treated as though they were direct children of the node's parent */
    Flat = 2
}
export interface CompoundMenuNode extends MenuNodeBase {
    /**
     * Items that are grouped under this menu.
     */
    readonly children: ReadonlyArray<MenuNode>;
    /**
     * @deprecated @since 1.28 use `role` instead.
     * Whether the item should be rendered as a submenu.
     */
    readonly isSubmenu: boolean;
    /**
     * How the node and its children should be rendered. See {@link CompoundMenuNodeRole}.
     */
    readonly role: CompoundMenuNodeRole;
}
export interface MutableCompoundMenuNode extends CompoundMenuNode {
    /**
     * Inserts the given node at the position indicated by `sortString`.
     *
     * @returns a disposable which, when called, will remove the given node again.
     */
    addNode(node: MenuNode): Disposable;
    /**
     * Removes the first node with the given id.
     *
     * @param id node id.
     */
    removeNode(id: string): void;
    /**
     * Fills any `undefined` fields with the values from the {@link options}.
     */
    updateOptions(options: SubMenuOptions): void;
}
export declare namespace CompoundMenuNode {
    function is(node?: MenuNode): node is CompoundMenuNode;
    function getRole(node: MenuNode): CompoundMenuNodeRole | undefined;
    function sortChildren(m1: MenuNode, m2: MenuNode): number;
    /** Collapses the children of any subemenus with role {@link CompoundMenuNodeRole Flat} and sorts */
    function getFlatChildren(children: ReadonlyArray<MenuNode>): MenuNode[];
    /**
     * Indicates whether the given node is the special `navigation` menu.
     *
     * @param node the menu node to check.
     * @returns `true` when the given node is a {@link CompoundMenuNode} with id `navigation`,
     * `false` otherwise.
     */
    function isNavigationGroup(node: MenuNode): node is CompoundMenuNode;
    function isMutable(node?: MenuNode): node is MutableCompoundMenuNode;
}
export interface CommandMenuNode extends MenuNodeBase {
    command: string;
}
export declare namespace CommandMenuNode {
    function is(candidate?: MenuNode): candidate is CommandMenuNode;
    function hasAltHandler(candidate?: MenuNode): candidate is AlternativeHandlerMenuNode;
}
export interface AlternativeHandlerMenuNode extends CommandMenuNode {
    altNode: CommandMenuNode;
}
/**
 * Base interface of the nodes used in the menu tree structure.
 */
export declare type MenuNode = MenuNodeMetadata & MenuNodeRenderingData & Partial<CompoundMenuNode> & Partial<CommandMenuNode> & Partial<AlternativeHandlerMenuNode>;
//# sourceMappingURL=menu-types.d.ts.map