3b74837020
* Event = Base event type (with preventDefault) * IpcMainEvent = Event that ipcMain emits (with sender, reply, etc.) * IpcRendererEvent = Event that ipcRenderer emits (with sender, senderId, etc.) * KeyboardEvent = Event that we emit with keyboard flags (ctrlKey, altKey, etc.) This will dramatically improve peoples TS experience with IPC events
151 lines
6.8 KiB
Markdown
151 lines
6.8 KiB
Markdown
## Class: MenuItem
|
|
|
|
> Add items to native application menus and context menus.
|
|
|
|
Process: [Main](../glossary.md#main-process)
|
|
|
|
See [`Menu`](menu.md) for examples.
|
|
|
|
### `new MenuItem(options)`
|
|
|
|
* `options` Object
|
|
* `click` Function (optional) - Will be called with
|
|
`click(menuItem, browserWindow, event)` when the menu item is clicked.
|
|
* `menuItem` MenuItem
|
|
* `browserWindow` [BrowserWindow](browser-window.md)
|
|
* `event` [KeyboardEvent](structures/keyboard-event.md)
|
|
* `role` String (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteandmatchstyle`, `delete`, `selectall`, `reload`, `forcereload`, `toggledevtools`, `resetzoom`, `zoomin`, `zoomout`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideothers`, `unhide`, `quit`, `startspeaking`, `stopspeaking`, `close`, `minimize`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu` or `windowMenu` - Define the action of the menu item, when specified the
|
|
`click` property will be ignored. See [roles](#roles).
|
|
* `type` String (optional) - Can be `normal`, `separator`, `submenu`, `checkbox` or
|
|
`radio`.
|
|
* `label` String (optional)
|
|
* `sublabel` String (optional)
|
|
* `accelerator` [Accelerator](accelerator.md) (optional)
|
|
* `icon` ([NativeImage](native-image.md) | String) (optional)
|
|
* `enabled` Boolean (optional) - If false, the menu item will be greyed out and
|
|
unclickable.
|
|
* `visible` Boolean (optional) - If false, the menu item will be entirely hidden.
|
|
* `checked` Boolean (optional) - Should only be specified for `checkbox` or `radio` type
|
|
menu items.
|
|
* `registerAccelerator` Boolean (optional) - If false, the accelerator won't be registered
|
|
with the system, but it will still be displayed. Defaults to true.
|
|
* `submenu` (MenuItemConstructorOptions[] | [Menu](menu.md)) (optional) - Should be specified
|
|
for `submenu` type menu items. If `submenu` is specified, the `type: 'submenu'` can be omitted.
|
|
If the value is not a [`Menu`](menu.md) then it will be automatically converted to one using
|
|
`Menu.buildFromTemplate`.
|
|
* `id` String (optional) - Unique within a single menu. If defined then it can be used
|
|
as a reference to this item by the position attribute.
|
|
* `before` String[] (optional) - Inserts this item before the item with the specified label. If
|
|
the referenced item doesn't exist the item will be inserted at the end of the menu. Also implies
|
|
that the menu item in question should be placed in the same “group” as the item.
|
|
* `after` String[] (optional) - Inserts this item after the item with the specified label. If the
|
|
referenced item doesn't exist the item will be inserted at the end of
|
|
the menu.
|
|
* `beforeGroupContaining` String[] (optional) - Provides a means for a single context menu to declare
|
|
the placement of their containing group before the containing group of the item
|
|
with the specified label.
|
|
* `afterGroupContaining` String[] (optional) - Provides a means for a single context menu to declare
|
|
the placement of their containing group after the containing group of the item
|
|
with the specified label.
|
|
|
|
### Roles
|
|
|
|
Roles allow menu items to have predefined behaviors.
|
|
|
|
It is best to specify `role` for any menu item that matches a standard role,
|
|
rather than trying to manually implement the behavior in a `click` function.
|
|
The built-in `role` behavior will give the best native experience.
|
|
|
|
The `label` and `accelerator` values are optional when using a `role` and will
|
|
default to appropriate values for each platform.
|
|
|
|
Every menu item must have either a `role`, `label`, or in the case of a separator
|
|
a `type`.
|
|
|
|
The `role` property can have following values:
|
|
|
|
* `undo`
|
|
* `redo`
|
|
* `cut`
|
|
* `copy`
|
|
* `paste`
|
|
* `pasteAndMatchStyle`
|
|
* `selectAll`
|
|
* `delete`
|
|
* `minimize` - Minimize current window.
|
|
* `close` - Close current window.
|
|
* `quit` - Quit the application.
|
|
* `reload` - Reload the current window.
|
|
* `forceReload` - Reload the current window ignoring the cache.
|
|
* `toggleDevTools` - Toggle developer tools in the current window.
|
|
* `toggleFullScreen` - Toggle full screen mode on the current window.
|
|
* `resetZoom` - Reset the focused page's zoom level to the original size.
|
|
* `zoomIn` - Zoom in the focused page by 10%.
|
|
* `zoomOut` - Zoom out the focused page by 10%.
|
|
* `fileMenu` - Whole default "File" menu (Close / Quit)
|
|
* `editMenu` - Whole default "Edit" menu (Undo, Copy, etc.).
|
|
* `viewMenu` - Whole default "View" menu (Reload, Toggle Developer Tools, etc.)
|
|
* `windowMenu` - Whole default "Window" menu (Minimize, Close, etc.).
|
|
|
|
The following additional roles are available on _macOS_:
|
|
|
|
* `appMenu` - Whole default "App" menu (About, Services, etc.)
|
|
* `about` - Map to the `orderFrontStandardAboutPanel` action.
|
|
* `hide` - Map to the `hide` action.
|
|
* `hideOthers` - Map to the `hideOtherApplications` action.
|
|
* `unhide` - Map to the `unhideAllApplications` action.
|
|
* `startSpeaking` - Map to the `startSpeaking` action.
|
|
* `stopSpeaking` - Map to the `stopSpeaking` action.
|
|
* `front` - Map to the `arrangeInFront` action.
|
|
* `zoom` - Map to the `performZoom` action.
|
|
* `toggleTabBar` - Map to the `toggleTabBar` action.
|
|
* `selectNextTab` - Map to the `selectNextTab` action.
|
|
* `selectPreviousTab` - Map to the `selectPreviousTab` action.
|
|
* `mergeAllWindows` - Map to the `mergeAllWindows` action.
|
|
* `moveTabToNewWindow` - Map to the `moveTabToNewWindow` action.
|
|
* `window` - The submenu is a "Window" menu.
|
|
* `help` - The submenu is a "Help" menu.
|
|
* `services` - The submenu is a "Services" menu.
|
|
* `recentDocuments` - The submenu is an "Open Recent" menu.
|
|
* `clearRecentDocuments` - Map to the `clearRecentDocuments` action.
|
|
|
|
When specifying a `role` on macOS, `label` and `accelerator` are the only
|
|
options that will affect the menu item. All other options will be ignored.
|
|
Lowercase `role`, e.g. `toggledevtools`, is still supported.
|
|
|
|
**Nota Bene:** The `enabled` and `visibility` properties are not available for top-level menu items in the tray on MacOS.
|
|
|
|
### Instance Properties
|
|
|
|
The following properties are available on instances of `MenuItem`:
|
|
|
|
#### `menuItem.enabled`
|
|
|
|
A `Boolean` indicating whether the item is enabled, this property can be
|
|
dynamically changed.
|
|
|
|
#### `menuItem.visible`
|
|
|
|
A `Boolean` indicating whether the item is visible, this property can be
|
|
dynamically changed.
|
|
|
|
#### `menuItem.checked`
|
|
|
|
A `Boolean` indicating whether the item is checked, this property can be
|
|
dynamically changed.
|
|
|
|
A `checkbox` menu item will toggle the `checked` property on and off when
|
|
selected.
|
|
|
|
A `radio` menu item will turn on its `checked` property when clicked, and
|
|
will turn off that property for all adjacent items in the same menu.
|
|
|
|
You can add a `click` function for additional behavior.
|
|
|
|
#### `menuItem.label`
|
|
|
|
A `String` representing the menu items visible label.
|
|
|
|
#### `menuItem.click`
|
|
|
|
A `Function` that is fired when the MenuItem receives a click event.
|