From d24a48a1f5afd353a14098175ef08f9f9a22da44 Mon Sep 17 00:00:00 2001 From: amrbashir Date: Tue, 29 Aug 2023 18:44:10 +0300 Subject: [PATCH] docs --- core/tauri/src/menu/check.rs | 4 +- core/tauri/src/menu/icon.rs | 3 +- tooling/api/src/menu.ts | 228 ++++++++++++++++++++++++++++++++--- 3 files changed, 217 insertions(+), 18 deletions(-) diff --git a/core/tauri/src/menu/check.rs b/core/tauri/src/menu/check.rs index 7898214f72cd..97fa639601e3 100644 --- a/core/tauri/src/menu/check.rs +++ b/core/tauri/src/menu/check.rs @@ -4,7 +4,9 @@ use crate::{menu::MenuId, resources::Resource, run_main_thread, AppHandle, Manager, Runtime}; -/// A menu item inside a [`Menu`] or [`Submenu`] and contains only text. +/// A menu item inside a [`Menu`] or [`Submenu`] +/// and usually contains a text and a check mark or a similar toggle +/// that corresponds to a checked and unchecked states. /// /// [`Menu`]: super::Menu /// [`Submenu`]: super::Submenu diff --git a/core/tauri/src/menu/icon.rs b/core/tauri/src/menu/icon.rs index 82ceec09e88b..e2dd547e095c 100644 --- a/core/tauri/src/menu/icon.rs +++ b/core/tauri/src/menu/icon.rs @@ -7,7 +7,8 @@ use crate::{ menu::MenuId, resources::Resource, run_main_thread, AppHandle, Icon, Manager, Runtime, }; -/// A menu item inside a [`Menu`] or [`Submenu`] and contains only text. +/// A menu item inside a [`Menu`] or [`Submenu`] +/// and usually contains an icon and a text. /// /// [`Menu`]: super::Menu /// [`Submenu`]: super::Submenu diff --git a/tooling/api/src/menu.ts b/tooling/api/src/menu.ts index 6ca2cce74042..a7df24ef4401 100644 --- a/tooling/api/src/menu.ts +++ b/tooling/api/src/menu.ts @@ -6,8 +6,6 @@ import { TauriEvent, listen } from './event' import { Resource, applyMixins } from './internal' import { invoke } from './tauri' -// TODO menu builders - /** * Menu types and utilities. * @@ -15,7 +13,9 @@ import { invoke } from './tauri' * @module */ +/** Describes a menu event emitted when a menu item is activated */ interface MenuEvent { + /** Id of the menu item that triggered this event */ id: string } @@ -61,6 +61,13 @@ async function addEventListener( window.__TAURI_MENU__.handlers[id].push(handler) } +/** + * A native Icon to be used for the menu item + * + * #### Platform-specific: + * + * - **Windows / Linux**: Unsupported. + */ enum NativeIcon { /** An add item template image. */ Add = 'Add', @@ -236,10 +243,12 @@ class MenuItemBase extends Resource { #id: string #kind: ItemKind + /// The id of this item. get id(): string { return this.#id } + /** @ignore */ get kind(): string { return this.#kind } @@ -252,6 +261,13 @@ class MenuItemBase extends Resource { } class MenuBase extends MenuItemBase { + /** + * Add a menu item to the end of this menu. + * + * ## Platform-spcific: + * + * - **macOS:** Only {@linkcode Submenu}s can be added to a {@linkcode Menu}. + */ async append< T extends | Submenu @@ -270,6 +286,13 @@ class MenuBase extends MenuItemBase { }) } + /** + * Add a menu item to the beginning of this menu. + * + * ## Platform-spcific: + * + * - **macOS:** Only {@linkcode Submenu}s can be added to a {@linkcode Menu}. + */ async prepend< T extends | Submenu @@ -288,6 +311,13 @@ class MenuBase extends MenuItemBase { }) } + /** + * Add a menu item to the specified position in this menu. + * + * ## Platform-spcific: + * + * - **macOS:** Only {@linkcode Submenu}s can be added to a {@linkcode Menu}. + */ async insert< T extends | Submenu @@ -307,6 +337,7 @@ class MenuBase extends MenuItemBase { }) } + /** Remove a menu item from this menu. */ async remove( item: Submenu | MenuItem | PredefinedMenuItem | CheckMenuItem | IconMenuItem ): Promise { @@ -317,6 +348,7 @@ class MenuBase extends MenuItemBase { }) } + /** Remove a menu item from this menu at the specified position. */ async removeAt( position: number ): Promise< @@ -334,6 +366,7 @@ class MenuBase extends MenuItemBase { }).then(itemFromKind) } + /** Returns a list of menu items that has been added to this menu. */ async items(): Promise< Array< Submenu | MenuItem | PredefinedMenuItem | CheckMenuItem | IconMenuItem @@ -345,6 +378,7 @@ class MenuBase extends MenuItemBase { }).then((i) => i.map(itemFromKind)) } + /** Retrieves the menu item matching the given identifier. */ async get( id: string ): Promise< @@ -364,6 +398,11 @@ class MenuBase extends MenuItemBase { // TODO change to logical position // TODO use window type after migrating window back to core + /** + * Popup this menu as a context menu on the specified window. + * + * If the position, is provided, it is relative to the window's top-left corner. + */ async popup(window: string, position?: [number, number]): Promise { return invoke('plugin:menu|popup', { rid: this.rid, @@ -374,28 +413,42 @@ class MenuBase extends MenuItemBase { } } +/** Options for creating a new menu. */ interface MenuOptions { + /** Specify an id to use for the new menu. */ id?: string + /** List of items to add to the new menu. */ items?: Array< Submenu | MenuItem | PredefinedMenuItem | CheckMenuItem | IconMenuItem > } +/** A type that is either a menu bar on the window + * on Windows and Linux or as a global menu in the menubar on macOS. + */ class Menu extends MenuBase { constructor(rid: number, id: string) { super(rid, id, 'Menu') } + /** Create a new menu. */ static async new(opts?: MenuOptions): Promise { return newMenu('Menu', opts).then(([rid, id]) => new Menu(rid, id)) } + /** Create a default menu. */ static async default(): Promise { return invoke<[number, string]>('plugin:menu|default').then( ([rid, id]) => new Menu(rid, id) ) } + /** + * Sets the app-wide menu and returns the previous one. + * + * If a window was not created with an explicit menu or had one set explicitly, + * this menu will be assigned to it. + */ async setAsAppMenu(): Promise { return invoke<[number, string] | null>('plugin:menu|set_as_app_menu', { rid: this.rid @@ -403,6 +456,14 @@ class Menu extends MenuBase { } // TODO use window type after migrating window back to core + /** + * Sets the window menu and returns the previous one. + * + * #### Platform-specific: + * + * - **macOS:** Unsupported. The menu on macOS is app-wide and not specific to one + * window, if you need to set it, use {@linkcode Menu.setAsAppMenu} instead. + */ async setAsWindowMenu(window: string): Promise { return invoke<[number, string] | null>('plugin:menu|set_as_window_menu', { rid: this.rid, @@ -412,10 +473,12 @@ class Menu extends MenuBase { } class MenuItemBase2 extends MenuItemBase { + /** Returns the text of this item. */ async text(): Promise { return invoke('plugin:menu|text', { rid: this.rid, kind: this.kind }) } + /** Sets the text for this item. */ async setText(text: string): Promise { return invoke('plugin:menu|set_text', { rid: this.rid, @@ -426,10 +489,12 @@ class MenuItemBase2 extends MenuItemBase { } class MenuItemBase3 extends MenuItemBase2 { + /** Returns whether this item is enabled or not. */ async isEnabled(): Promise { return invoke('plugin:menu|is_enabled', { rid: this.rid, kind: this.kind }) } + /** Sets whether this item is enabled or not. */ async setEnabled(enabled: boolean): Promise { return invoke('plugin:menu|set_enabled', { rid: this.rid, @@ -440,6 +505,7 @@ class MenuItemBase3 extends MenuItemBase2 { } class MenuItemBase4 extends MenuItemBase3 { + /** Sets the accelerator for this menu item. */ async setAccelerator(accelerator: string | null): Promise { return invoke('plugin:menu|set_accelerator', { rid: this.rid, @@ -449,19 +515,27 @@ class MenuItemBase4 extends MenuItemBase3 { } } +/** Options for creating a new menu item. */ interface MenuItemOptions { + /** Specify an id to use for the new menu item. */ id?: string + /** The text of the new menu item. */ text: string + /** Whether the new menu item is enabled or not. */ enabled?: boolean + /** Specify an accelerator for the new menu item. */ accelerator?: string + /** Specify a handler to be called when this menu item is activated. */ action?: () => void } +/** A menu item inside a {@linkcode Menu} or {@linkcode Submenu} and contains only text. */ class MenuItem extends MenuItemBase4 { constructor(rid: number, id: string) { super(rid, id, 'MenuItem') } + /** Create a new menu item. */ static async new(opts: MenuItemOptions): Promise { return newMenu('MenuItem', opts).then(([rid, id]) => new MenuItem(rid, id)) } @@ -471,21 +545,46 @@ type SubmenuOptions = Omit & MenuOptions interface Submenu extends MenuItemBase3 {} + +/** A type that is a submenu inside a {@linkcode Menu} or {@linkcode Submenu}. */ class Submenu extends MenuBase { constructor(rid: number, id: string) { super(rid, id, 'Submenu') } + /** Create a new submenu. */ static async new(opts: SubmenuOptions): Promise { return newMenu('Submenu', opts).then(([rid, id]) => new Submenu(rid, id)) } + /** + * Set this submenu as the Window menu for the application on macOS. + * + * This will cause macOS to automatically add window-switching items and + * certain other items to the menu. + * + * #### Platform-specific: + * + * - **Windows / Linux**: Unsupported. + */ async setAsWindowsMenuForNSApp(): Promise { return invoke('plugin:menu|set_as_windows_menu_for_nsapp', { rid: this.rid }) } + /** + * Set this submenu as the Help menu for the application on macOS. + * + * This will cause macOS to automatically add a search box to the menu. + * + * If no menu is set as the Help menu, macOS will automatically use any menu + * which has a title matching the localized word "Help". + * + * #### Platform-specific: + * + * - **Windows / Linux**: Unsupported. + */ async setAsHelpMenuForNSApp(): Promise { return invoke('plugin:menu|set_as_help_menu_for_nsapp', { rid: this.rid @@ -495,8 +594,85 @@ class Submenu extends MenuBase { applyMixins(Submenu, MenuItemBase3) +/** A metadata for the about predefined menu item. */ +interface AboutMetadata { + /** Sets the application name. */ + name?: string + /** The application version. */ + version?: string + /** + * The short version, e.g. "1.0". + * + * #### Platform-specific + * + * - **Windows / Linux:** Appended to the end of `version` in parentheses. + */ + short_version?: string + /** + * The authors of the application. + * + * #### Platform-specific + * + * - **macOS:** Unsupported. + */ + authors?: string[] + /** + * Application comments. + * + * #### Platform-specific + * + * - **macOS:** Unsupported. + */ + comments?: string + /** The copyright of the application. */ + copyright?: string + /** + * The license of the application. + * + * #### Platform-specific + * + * - **macOS:** Unsupported. + */ + license?: string + /** + * The application website. + * + * #### Platform-specific + * + * - **macOS:** Unsupported. + */ + website?: string + /** + * The website label. + * + * #### Platform-specific + * + * - **macOS:** Unsupported. + */ + website_label?: string + /** + * The credits. + * + * #### Platform-specific + * + * - **Windows / Linux:** Unsupported. + */ + credits?: string + /** + * The application icon. + * + * #### Platform-specific + * + * - **Windows:** Unsupported. + */ + icon?: string | Uint8Array +} + +/** Options for creating a new predefined menu item. */ interface PredefinedMenuItemOptions { + /** The text of the new predefined menu item. */ text?: string + /** The predefined item type */ item: | 'Separator' | 'Copy' @@ -515,27 +691,17 @@ interface PredefinedMenuItemOptions { | 'Quit' | 'Services' | { - About: { - name?: string - version?: string - short_version?: string - authors?: string[] - comments?: string - copyright?: string - license?: string - website?: string - website_label?: string - credits?: string - icon?: string | Uint8Array - } + About: AboutMetadata | null } } +/** A predefined (native) menu item which has a predfined behavior by the OS or by tauri. */ class PredefinedMenuItem extends MenuItemBase2 { constructor(rid: number, id: string) { super(rid, id, 'MenuItem') } + /** Create a new predefined menu item. */ static async new( opts?: PredefinedMenuItemOptions ): Promise { @@ -545,25 +711,35 @@ class PredefinedMenuItem extends MenuItemBase2 { } } +/** Options for creating a new check menu item. */ interface CheckMenuItemOptions extends MenuItemOptions { + /** Whether the new check menu item is enabled or not. */ checked?: boolean } +/** + * A chcek menu item inside a {@linkcode Menu} or {@linkcode Submenu} + * and usually contains a text and a check mark or a similar toggle + * that corresponds to a checked and unchecked states. + */ class CheckMenuItem extends MenuItemBase4 { constructor(rid: number, id: string) { super(rid, id, 'Check') } + /** Create a new check menu item. */ static async new(opts: MenuItemOptions): Promise { return newMenu('Check', opts).then( ([rid, id]) => new CheckMenuItem(rid, id) ) } + /** Returns whether this item is checked or not. */ async isChecked(): Promise { return invoke('plugin:menu|is_checked', { rid: this.rid }) } + /** Sets whether this item is checked or not. */ async setChecked(checked: boolean): Promise { return invoke('plugin:menu|set_checked', { rid: this.rid, @@ -572,23 +748,42 @@ class CheckMenuItem extends MenuItemBase4 { } } +/** Options for creating a new icon menu item. */ interface IconMenuItemOptions extends MenuItemOptions { + /** + * Icon to be used for the new icon menu item. + * + * if both {@linkcode IconMenuItemOptions.icon|icon} and {@linkcode IconMenuItemOptions.nativeIcon|nativeIcon} are specified, only {@linkcode IconMenuItemOptions.icon|icon} is used. + */ icon?: string | Uint8Array + /** + * NativeIcon to be used for the new icon menu item. + * + * if both {@linkcode IconMenuItemOptions.icon|icon} and {@linkcode IconMenuItemOptions.nativeIcon|nativeIcon} are specified, only {@linkcode IconMenuItemOptions.icon|icon} is used. + */ nativeIcon?: NativeIcon } + +/** + * An icon menu item inside a {@linkcode Menu} or {@linkcode Submenu} + * and usually contains an icon and a text. + */ class IconMenuItem extends MenuItemBase4 { constructor(rid: number, id: string) { super(rid, id, 'Icon') } + /** Create a new icon menu item. */ static async new(opts: IconMenuItemOptions): Promise { return newMenu('Icon', opts).then(([rid, id]) => new IconMenuItem(rid, id)) } + /** Sets an icon for this icon menu item */ async setIcon(icon: string | Uint8Array | null): Promise { return invoke('plugin:menu|set_icon', { rid: this.rid, icon }) } + /** Sets a native icon for this icon menu item */ async setNativeIcon(icon: NativeIcon | null): Promise { return invoke('plugin:menu|set_native_icon', { rid: this.rid, icon }) } @@ -601,7 +796,8 @@ export type { SubmenuOptions, PredefinedMenuItemOptions, CheckMenuItemOptions, - IconMenuItemOptions + IconMenuItemOptions, + AboutMetadata } export { NativeIcon,