2017-07-26 20:02:40 +00:00
## Class: Menu
2016-04-21 22:39:12 +00:00
> Create native application menus and context menus.
2016-04-21 22:35:29 +00:00
2016-11-23 19:20:56 +00:00
Process: [Main ](../glossary.md#main-process )
2016-11-03 17:26:00 +00:00
2016-11-15 00:41:15 +00:00
### `new Menu()`
Creates a new menu.
### Static Methods
The `menu` class has the following static methods:
#### `Menu.setApplicationMenu(menu)`
2017-11-19 09:41:22 +00:00
* `menu` Menu | null
2016-11-15 00:41:15 +00:00
2017-04-04 06:00:20 +00:00
Sets `menu` as the application menu on macOS. On Windows and Linux, the
`menu` will be set as each window's top menu.
2018-10-29 18:08:47 +00:00
Also on Windows and Linux, you can use a `&` in the top-level item name to
indicate which letter should get a generated accelerator. For example, using
`&File` for the file menu would result in a generated `Alt-F` accelerator that
opens the associated menu. The indicated character in the button label gets an
underline. The `&` character is not displayed on the button label.
2019-01-15 20:35:53 +00:00
Passing `null` will suppress the default menu. On Windows and Linux,
this has the additional effect of removing the menu bar from the window.
2016-11-15 00:41:15 +00:00
2019-01-15 20:35:53 +00:00
**Note:** The default menu will be created automatically if the app does not set one.
It contains standard items such as `File` , `Edit` , `View` , `Window` and `Help` .
2016-11-15 00:41:15 +00:00
#### `Menu.getApplicationMenu()`
2017-11-19 09:41:22 +00:00
Returns `Menu | null` - The application menu, if set, or `null` , if not set.
2016-11-15 00:41:15 +00:00
2017-03-23 18:55:46 +00:00
**Note:** The returned `Menu` instance doesn't support dynamic addition or
removal of menu items. [Instance properties ](#instance-properties ) can still
be dynamically modified.
2016-11-15 00:41:15 +00:00
#### `Menu.sendActionToFirstResponder(action)` _macOS_
* `action` String
Sends the `action` to the first responder of application. This is used for
2018-05-08 05:16:09 +00:00
emulating default macOS menu behaviors. Usually you would use the
2017-03-30 18:08:12 +00:00
[`role` ](menu-item.md#roles ) property of a [`MenuItem` ](menu-item.md ).
2016-11-15 00:41:15 +00:00
See the [macOS Cocoa Event Handling Guide ](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/EventOverview/EventArchitecture/EventArchitecture.html#//apple_ref/doc/uid/10000060i-CH3-SW7 )
for more information on macOS' native actions.
#### `Menu.buildFromTemplate(template)`
2019-02-06 18:04:40 +00:00
* `template` (MenuItemConstructorOptions | MenuItem)[]
2016-11-15 00:41:15 +00:00
Returns `Menu`
2018-05-07 15:46:14 +00:00
Generally, the `template` is an array of `options` for constructing a
2016-11-15 00:41:15 +00:00
[MenuItem ](menu-item.md ). The usage can be referenced above.
2019-02-06 18:04:40 +00:00
You can also attach other fields to the element of the `template` and they will become properties of the constructed menu items.
2016-11-15 00:41:15 +00:00
### Instance Methods
The `menu` object has the following instance methods:
2018-02-20 16:12:39 +00:00
#### `menu.popup(options)`
2017-02-16 16:34:39 +00:00
2018-08-08 22:38:52 +00:00
* `options` Object (optional)
2018-02-20 20:30:37 +00:00
* `window` [BrowserWindow ](browser-window.md ) (optional) - Default is the focused window.
2017-02-16 16:34:39 +00:00
* `x` Number (optional) - Default is the current mouse cursor position.
2017-06-05 15:55:42 +00:00
Must be declared if `y` is declared.
2017-06-03 04:50:10 +00:00
* `y` Number (optional) - Default is the current mouse cursor position.
2017-06-05 15:55:42 +00:00
Must be declared if `x` is declared.
2017-02-16 16:34:39 +00:00
* `positioningItem` Number (optional) _macOS_ - The index of the menu item to
be positioned under the mouse cursor at the specified coordinates. Default
is -1.
2018-02-20 16:12:39 +00:00
* `callback` Function (optional) - Called when menu is closed.
2016-11-15 00:41:15 +00:00
2017-11-29 10:38:35 +00:00
Pops up this menu as a context menu in the [`BrowserWindow` ](browser-window.md ).
2016-11-15 00:41:15 +00:00
2017-02-16 19:18:13 +00:00
#### `menu.closePopup([browserWindow])`
2017-11-29 10:38:35 +00:00
* `browserWindow` [BrowserWindow ](browser-window.md ) (optional) - Default is the focused window.
2017-02-16 19:18:13 +00:00
Closes the context menu in the `browserWindow` .
2016-11-15 00:41:15 +00:00
#### `menu.append(menuItem)`
2017-11-29 10:38:35 +00:00
* `menuItem` [MenuItem ](menu-item.md )
2016-11-15 00:41:15 +00:00
Appends the `menuItem` to the menu.
2017-09-27 01:14:16 +00:00
#### `menu.getMenuItemById(id)`
* `id` String
2017-09-27 01:30:27 +00:00
Returns `MenuItem` the item with the specified `id`
2017-09-27 01:14:16 +00:00
2016-11-15 00:41:15 +00:00
#### `menu.insert(pos, menuItem)`
* `pos` Integer
2017-11-29 10:38:35 +00:00
* `menuItem` [MenuItem ](menu-item.md )
2016-11-15 00:41:15 +00:00
Inserts the `menuItem` to the `pos` position of the menu.
2018-01-27 16:28:42 +00:00
### Instance Events
2019-02-15 18:29:33 +00:00
Objects created with `new Menu` or returned by `Menu.buildFromTemplate` emit the following events:
2018-01-27 16:28:42 +00:00
**Note:** Some events are only available on specific operating systems and are
labeled as such.
2018-01-28 23:57:44 +00:00
#### Event: 'menu-will-show'
2018-01-27 16:28:42 +00:00
Returns:
* `event` Event
Emitted when `menu.popup()` is called.
2018-01-28 23:57:44 +00:00
#### Event: 'menu-will-close'
2018-01-27 16:28:42 +00:00
Returns:
* `event` Event
2018-01-28 18:59:53 +00:00
Emitted when a popup is closed either manually or with `menu.closePopup()` .
2018-01-27 16:28:42 +00:00
2016-11-15 00:41:15 +00:00
### Instance Properties
`menu` objects also have the following properties:
#### `menu.items`
2017-07-24 08:29:03 +00:00
A `MenuItem[]` array containing the menu's items.
2016-11-15 00:41:15 +00:00
2016-08-03 07:08:54 +00:00
Each `Menu` consists of multiple [`MenuItem` ](menu-item.md )s and each `MenuItem`
can have a submenu.
2013-08-14 22:43:35 +00:00
2016-08-03 02:10:56 +00:00
## Examples
2013-08-14 22:43:35 +00:00
2016-08-03 07:08:54 +00:00
The `Menu` class is only available in the main process, but you can also use it
in the render process via the [`remote` ](remote.md ) module.
2016-08-03 02:10:56 +00:00
### Main process
2013-08-14 22:43:35 +00:00
2016-08-03 02:10:56 +00:00
An example of creating the application menu in the main process with the
2015-08-28 23:19:28 +00:00
simple template API:
2013-08-14 22:43:35 +00:00
2015-09-02 01:19:18 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { app, Menu } = require('electron')
2016-07-26 01:39:25 +00:00
2016-05-04 17:59:02 +00:00
const template = [
2019-01-10 13:32:03 +00:00
// { role: 'appMenu' }
...(process.platform === 'darwin' ? [{
2019-04-30 20:55:33 +00:00
label: app.name,
2019-01-10 13:32:03 +00:00
submenu: [
{ role: 'about' },
{ type: 'separator' },
{ role: 'services' },
{ type: 'separator' },
{ role: 'hide' },
{ role: 'hideothers' },
{ role: 'unhide' },
{ type: 'separator' },
{ role: 'quit' }
]
}] : []),
// { role: 'fileMenu' }
{
label: 'File',
submenu: [
isMac ? { role: 'close' } : { role: 'quit' }
]
},
// { role: 'editMenu' }
2013-08-14 22:43:35 +00:00
{
label: 'Edit',
submenu: [
2018-09-13 16:10:51 +00:00
{ role: 'undo' },
{ role: 'redo' },
{ type: 'separator' },
{ role: 'cut' },
{ role: 'copy' },
{ role: 'paste' },
2019-01-10 13:32:03 +00:00
...(isMac ? [
{ role: 'pasteAndMatchStyle' },
{ role: 'delete' },
{ role: 'selectAll' },
{ type: 'separator' },
{
label: 'Speech',
submenu: [
{ role: 'startspeaking' },
{ role: 'stopspeaking' }
]
}
] : [
{ role: 'delete' },
{ type: 'separator' },
{ role: 'selectAll' }
])
2013-08-14 22:43:35 +00:00
]
},
2019-01-10 13:32:03 +00:00
// { role: 'viewMenu' }
2013-08-14 22:43:35 +00:00
{
label: 'View',
submenu: [
2018-09-13 16:10:51 +00:00
{ role: 'reload' },
{ role: 'forcereload' },
{ role: 'toggledevtools' },
{ type: 'separator' },
{ role: 'resetzoom' },
{ role: 'zoomin' },
{ role: 'zoomout' },
{ type: 'separator' },
{ role: 'togglefullscreen' }
2013-08-14 22:43:35 +00:00
]
},
2019-01-10 13:32:03 +00:00
// { role: 'windowMenu' }
2013-08-14 22:43:35 +00:00
{
2019-01-10 13:32:03 +00:00
label: 'Window',
2013-08-14 22:43:35 +00:00
submenu: [
2018-09-13 16:10:51 +00:00
{ role: 'minimize' },
2019-01-10 13:32:03 +00:00
{ role: 'zoom' },
...(isMac ? [
{ type: 'separator' },
{ role: 'front' },
{ type: 'separator' },
{ role: 'window' }
] : [
{ role: 'close' }
])
2013-08-14 22:43:35 +00:00
]
},
2014-09-05 05:39:29 +00:00
{
2015-09-02 01:19:18 +00:00
role: 'help',
submenu: [
{
label: 'Learn More',
2019-05-03 20:53:45 +00:00
click: async () => {
const { shell } = require('electron')
await shell.openExternal('https://electronjs.org')
}
2016-07-26 01:39:25 +00:00
}
2015-09-02 01:19:18 +00:00
]
2016-07-26 01:39:25 +00:00
}
]
2013-08-14 22:43:35 +00:00
2016-07-26 01:39:25 +00:00
const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)
2013-08-14 22:43:35 +00:00
```
2016-08-03 02:10:56 +00:00
### Render process
Below is an example of creating a menu dynamically in a web page
2016-08-03 07:08:54 +00:00
(render process) by using the [`remote` ](remote.md ) module, and showing it when
2016-08-03 02:10:56 +00:00
the user right clicks the page:
```html
<!-- index.html -->
< script >
2018-09-13 16:10:51 +00:00
const { remote } = require('electron')
const { Menu, MenuItem } = remote
2016-08-03 02:10:56 +00:00
const menu = new Menu()
2019-02-01 16:28:28 +00:00
menu.append(new MenuItem({ label: 'MenuItem1', click() { console.log('item 1 clicked') } }))
2018-09-13 16:10:51 +00:00
menu.append(new MenuItem({ type: 'separator' }))
menu.append(new MenuItem({ label: 'MenuItem2', type: 'checkbox', checked: true }))
2016-08-03 02:10:56 +00:00
window.addEventListener('contextmenu', (e) => {
e.preventDefault()
2018-09-13 16:10:51 +00:00
menu.popup({ window: remote.getCurrentWindow() })
2016-08-03 02:10:56 +00:00
}, false)
< / script >
```
2014-09-05 05:39:29 +00:00
2016-06-18 13:26:26 +00:00
## Notes on macOS Application Menu
2014-09-05 05:39:29 +00:00
2016-06-18 13:26:26 +00:00
macOS has a completely different style of application menu from Windows and
2016-07-13 04:50:43 +00:00
Linux. Here are some notes on making your app's menu more native-like.
2014-09-05 05:39:29 +00:00
2015-08-28 23:19:28 +00:00
### Standard Menus
2014-09-05 05:39:29 +00:00
2016-07-13 04:50:43 +00:00
On macOS there are many system-defined standard menus, like the `Services` and
2015-09-02 01:19:18 +00:00
`Windows` menus. To make your menu a standard menu, you should set your menu's
2017-05-02 16:05:07 +00:00
`role` to one of the following and Electron will recognize them and make them
2014-09-05 05:39:29 +00:00
become standard menus:
2015-09-02 01:19:18 +00:00
* `window`
* `help`
* `services`
2014-09-05 05:39:29 +00:00
2015-08-28 23:19:28 +00:00
### Standard Menu Item Actions
2014-09-05 05:39:29 +00:00
2016-06-18 13:26:26 +00:00
macOS has provided standard actions for some menu items, like `About xxx` ,
2015-09-02 01:19:18 +00:00
`Hide xxx` , and `Hide Others` . To set the action of a menu item to a standard
action, you should set the `role` attribute of the menu item.
2014-09-05 05:39:29 +00:00
2015-08-28 23:19:28 +00:00
### Main Menu's Name
2014-09-05 05:39:29 +00:00
2016-07-13 04:50:43 +00:00
On macOS the label of the application menu's first item is always your app's
name, no matter what label you set. To change it, modify your app bundle's
`Info.plist` file. See
[About Information Property List Files][AboutInformationPropertyListFiles]
for more information.
2015-04-13 03:22:33 +00:00
2016-01-31 16:28:44 +00:00
## Setting Menu for Specific Browser Window (*Linux* *Windows*)
The [`setMenu` method][setMenu] of browser windows can set the menu of certain
2016-07-13 04:50:43 +00:00
browser windows.
2016-01-31 16:28:44 +00:00
2015-08-28 23:19:28 +00:00
## Menu Item Position
2015-04-13 03:22:33 +00:00
2018-05-05 16:37:29 +00:00
You can make use of `before` , `after` , `beforeGroupContaining` , `afterGroupContaining` and `id` to control how the item will be placed when building a menu with `Menu.buildFromTemplate` .
2015-04-13 03:22:33 +00:00
2018-05-05 16:37:29 +00:00
* `before` - 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` - Inserts this item after the item with the specified label. If the
2015-04-13 03:22:33 +00:00
referenced item doesn't exist the item will be inserted at the end of
2018-05-05 16:37:29 +00:00
the menu. Also implies that the menu item in question should be placed in the same “group” as the item.
* `beforeGroupContaining` - 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` - 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.
By default, items will be inserted in the order they exist in the template unless one of the specified positioning keywords is used.
2015-04-13 03:22:33 +00:00
### Examples
Template:
2016-08-16 21:50:21 +00:00
```javascript
2015-04-13 03:22:33 +00:00
[
2018-05-05 16:37:29 +00:00
{ id: '1', label: 'one' },
{ id: '2', label: 'two' },
{ id: '3', label: 'three' },
{ id: '4', label: 'four' }
2015-04-13 03:22:33 +00:00
]
```
Menu:
2017-11-20 06:18:24 +00:00
```sh
2015-04-13 03:22:33 +00:00
- 1
- 2
- 3
- 4
```
Template:
2016-08-16 21:50:21 +00:00
```javascript
2015-04-13 03:22:33 +00:00
[
2018-05-05 16:37:29 +00:00
{ id: '1', label: 'one' },
{ type: 'separator' },
{ id: '3', label: 'three', beforeGroupContaining: ['1'] },
{ id: '4', label: 'four', afterGroupContaining: ['2'] },
{ type: 'separator' },
{ id: '2', label: 'two' }
2015-04-13 03:22:33 +00:00
]
```
Menu:
2017-11-20 06:18:24 +00:00
```sh
2018-05-05 16:37:29 +00:00
- 3
- 4
2015-04-13 03:22:33 +00:00
- ---
- 1
2018-05-05 16:37:29 +00:00
- ---
2015-04-13 03:22:33 +00:00
- 2
2018-05-05 16:37:29 +00:00
```
Template:
```javascript
[
{ id: '1', label: 'one', after: ['3'] },
{ id: '2', label: 'two', before: ['1'] },
{ id: '3', label: 'three' }
]
```
Menu:
```sh
- ---
2015-04-13 03:22:33 +00:00
- 3
2018-05-05 16:37:29 +00:00
- 2
- 1
2015-04-13 03:22:33 +00:00
```
2015-09-02 01:19:18 +00:00
[AboutInformationPropertyListFiles]: https://developer.apple.com/library/ios/documentation/general/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html
2016-03-31 23:49:59 +00:00
[setMenu]: https://github.com/electron/electron/blob/master/docs/api/browser-window.md#winsetmenumenu-linux-windows