2016-11-15 00:24:48 +00:00
## Class: Menu
2013-08-14 22:43:35 +00:00
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-03 17:26:00 +00:00
Process: [Main ](../tutorial/quick-start.md#main-process )
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
2016-10-11 06:01:35 +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 = [
2013-08-14 22:43:35 +00:00
{
label: 'Edit',
submenu: [
{
2015-09-02 01:19:18 +00:00
role: 'undo'
2013-08-14 22:43:35 +00:00
},
{
2015-09-02 01:19:18 +00:00
role: 'redo'
2013-08-14 22:43:35 +00:00
},
{
type: 'separator'
},
{
2015-09-02 01:19:18 +00:00
role: 'cut'
2013-08-14 22:43:35 +00:00
},
{
2015-09-02 01:19:18 +00:00
role: 'copy'
2013-08-14 22:43:35 +00:00
},
{
2015-09-02 01:19:18 +00:00
role: 'paste'
2013-08-14 22:43:35 +00:00
},
2016-06-07 08:42:46 +00:00
{
role: 'pasteandmatchstyle'
},
{
role: 'delete'
},
2013-08-14 22:43:35 +00:00
{
2015-09-02 01:19:18 +00:00
role: 'selectall'
2016-07-26 01:39:25 +00:00
}
2013-08-14 22:43:35 +00:00
]
},
{
label: 'View',
submenu: [
{
label: 'Reload',
2015-07-23 22:04:43 +00:00
accelerator: 'CmdOrCtrl+R',
2016-07-26 01:39:25 +00:00
click (item, focusedWindow) {
if (focusedWindow) focusedWindow.reload()
2015-09-02 01:19:18 +00:00
}
2013-08-14 22:43:35 +00:00
},
2015-09-02 01:19:18 +00:00
{
label: 'Toggle Developer Tools',
2016-05-10 16:34:51 +00:00
accelerator: process.platform === 'darwin' ? 'Alt+Command+I' : 'Ctrl+Shift+I',
2016-07-26 01:39:25 +00:00
click (item, focusedWindow) {
if (focusedWindow) focusedWindow.webContents.toggleDevTools()
2015-09-02 01:19:18 +00:00
}
2016-08-01 13:44:25 +00:00
},
{
type: 'separator'
},
2016-08-08 18:09:24 +00:00
{
role: 'resetzoom'
},
{
role: 'zoomin'
},
{
role: 'zoomout'
},
{
type: 'separator'
},
2016-08-01 13:44:25 +00:00
{
role: 'togglefullscreen'
2016-07-26 01:39:25 +00:00
}
2013-08-14 22:43:35 +00:00
]
},
{
2015-09-02 01:19:18 +00:00
role: 'window',
2013-08-14 22:43:35 +00:00
submenu: [
{
2015-09-02 01:19:18 +00:00
role: 'minimize'
2013-08-14 22:43:35 +00:00
},
{
2015-09-02 01:19:18 +00:00
role: 'close'
2016-07-26 01:39:25 +00:00
}
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',
2016-07-26 01:39:25 +00:00
click () { require('electron').shell.openExternal('http://electron.atom.io') }
}
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-05-04 17:59:02 +00:00
if (process.platform === 'darwin') {
2015-09-02 01:19:18 +00:00
template.unshift({
2016-10-11 06:01:35 +00:00
label: app.getName(),
2015-09-02 01:19:18 +00:00
submenu: [
{
role: 'about'
},
{
type: 'separator'
},
{
role: 'services',
submenu: []
},
{
type: 'separator'
},
{
role: 'hide'
},
{
2015-09-11 12:26:48 +00:00
role: 'hideothers'
2015-09-02 01:19:18 +00:00
},
{
2015-09-11 12:26:48 +00:00
role: 'unhide'
2015-09-02 01:19:18 +00:00
},
{
type: 'separator'
},
{
2016-06-22 21:37:16 +00:00
role: 'quit'
2016-07-26 01:39:25 +00:00
}
2015-09-02 01:19:18 +00:00
]
2016-07-26 01:39:25 +00:00
})
2016-08-07 22:02:32 +00:00
// Edit menu.
template[1].submenu.push(
{
type: 'separator'
},
{
label: 'Speech',
submenu: [
{
role: 'startspeaking'
},
{
role: 'stopspeaking'
}
]
}
)
2015-09-02 01:19:18 +00:00
// Window menu.
2016-06-07 08:42:46 +00:00
template[3].submenu = [
{
label: 'Close',
accelerator: 'CmdOrCtrl+W',
role: 'close'
},
{
label: 'Minimize',
accelerator: 'CmdOrCtrl+M',
role: 'minimize'
},
{
label: 'Zoom',
role: 'zoom'
},
2015-09-02 01:19:18 +00:00
{
type: 'separator'
},
{
label: 'Bring All to Front',
role: 'front'
}
2016-07-26 01:39:25 +00:00
]
2015-09-02 01:19:18 +00:00
}
2014-12-17 02:50:40 +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 >
const {remote} = require('electron')
2016-08-03 07:08:54 +00:00
const {Menu, MenuItem} = remote
2016-08-03 02:10:56 +00:00
const menu = new Menu()
menu.append(new MenuItem({label: 'MenuItem1', click() { console.log('item 1 clicked') }}))
menu.append(new MenuItem({type: 'separator'}))
menu.append(new MenuItem({label: 'MenuItem2', type: 'checkbox', checked: true}))
window.addEventListener('contextmenu', (e) => {
e.preventDefault()
menu.popup(remote.getCurrentWindow())
}, false)
< / script >
```
2015-08-28 23:19:28 +00:00
### `new Menu()`
2013-08-14 22:43:35 +00:00
Creates a new menu.
2016-07-13 04:47:28 +00:00
### Static Methods
2015-08-28 23:19:28 +00:00
2016-07-13 04:47:28 +00:00
The `menu` class has the following static methods:
2015-08-28 23:19:28 +00:00
2016-07-13 04:47:28 +00:00
#### `Menu.setApplicationMenu(menu)`
2013-08-14 22:43:35 +00:00
* `menu` Menu
2016-06-18 13:26:26 +00:00
Sets `menu` as the application menu on macOS. On Windows and Linux, the `menu`
2014-05-30 01:02:21 +00:00
will be set as each window's top menu.
2013-08-14 22:43:35 +00:00
2016-06-13 01:52:12 +00:00
**Note:** This API has to be called after the `ready` event of `app` module.
2016-06-11 05:09:53 +00:00
2016-07-13 04:47:28 +00:00
#### `Menu.getApplicationMenu()`
2016-06-16 19:43:01 +00:00
2016-11-11 05:37:19 +00:00
Returns `Menu` - The application menu, if set, or `null` , if not set.
2016-06-16 19:43:01 +00:00
2016-07-13 04:47:28 +00:00
#### `Menu.sendActionToFirstResponder(action)` _macOS_
2013-08-14 22:43:35 +00:00
* `action` String
2015-08-28 23:19:28 +00:00
Sends the `action` to the first responder of application. This is used for
2013-08-29 14:37:51 +00:00
emulating default Cocoa menu behaviors, usually you would just use the
2015-11-23 05:40:23 +00:00
`role` property of `MenuItem` .
2013-08-14 22:43:35 +00:00
2016-06-18 13:26:26 +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 )
2016-06-18 13:28:22 +00:00
for more information on macOS' native actions.
2016-03-08 00:11:58 +00:00
2016-07-13 04:47:28 +00:00
#### `Menu.buildFromTemplate(template)`
2013-08-14 22:43:35 +00:00
2016-11-07 06:43:55 +00:00
* `template` MenuItemConstructorOptions[]
Returns `Menu`
2013-08-14 22:43:35 +00:00
2015-08-28 23:19:28 +00:00
Generally, the `template` is just an array of `options` for constructing a
[MenuItem ](menu-item.md ). The usage can be referenced above.
2013-08-14 22:43:35 +00:00
2015-08-28 23:19:28 +00:00
You can also attach other fields to the element of the `template` and they
will become properties of the constructed menu items.
2013-08-14 22:43:35 +00:00
2016-07-13 04:47:28 +00:00
### Instance Methods
2016-03-20 17:58:25 +00:00
The `menu` object has the following instance methods:
2016-07-13 04:47:28 +00:00
#### `menu.popup([browserWindow, x, y, positioningItem])`
2013-08-14 22:43:35 +00:00
2016-07-25 11:57:38 +00:00
* `browserWindow` BrowserWindow (optional) - Default is `BrowserWindow.getFocusedWindow()` .
* `x` Number (optional) - Default is the current mouse cursor position.
* `y` Number (**required** if `x` is used) - Default is the current mouse cursor position.
2016-06-18 13:26:26 +00:00
* `positioningItem` Number (optional) _macOS_ - The index of the menu item to
2016-01-22 18:32:14 +00:00
be positioned under the mouse cursor at the specified coordinates. Default is
-1.
2016-01-22 18:29:26 +00:00
2016-07-25 11:57:38 +00:00
Pops up this menu as a context menu in the `browserWindow` .
2013-08-14 22:43:35 +00:00
2016-07-13 04:47:28 +00:00
#### `menu.append(menuItem)`
2013-08-14 22:43:35 +00:00
* `menuItem` MenuItem
Appends the `menuItem` to the menu.
2016-07-13 04:47:28 +00:00
#### `menu.insert(pos, menuItem)`
2013-08-14 22:43:35 +00:00
* `pos` Integer
* `menuItem` MenuItem
Inserts the `menuItem` to the `pos` position of the menu.
2016-07-13 04:47:28 +00:00
### Instance Properties
2016-03-20 17:58:25 +00:00
`menu` objects also have the following properties:
2016-07-13 04:47:28 +00:00
#### `menu.items`
2013-08-14 22:43:35 +00:00
2016-09-24 23:59:30 +00:00
A MenuItem[] array containing the menu's items.
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
`role` to one of 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
2015-08-28 23:19:28 +00:00
You can make use of `position` and `id` to control how the item will be placed
2015-04-13 03:22:33 +00:00
when building a menu with `Menu.buildFromTemplate` .
2015-08-28 23:19:28 +00:00
The `position` attribute of `MenuItem` has the form `[placement]=[id]` , where
2016-01-24 10:47:12 +00:00
`placement` is one of `before` , `after` , or `endof` and `id` is the unique ID of
2015-04-13 03:22:33 +00:00
an existing item in the menu:
* `before` - Inserts this item before the id referenced item. If the
referenced item doesn't exist the item will be inserted at the end of
the menu.
* `after` - Inserts this item after id referenced item. If the referenced
item doesn't exist the item will be inserted at the end of the menu.
* `endof` - Inserts this item at the end of the logical group containing
2015-08-28 23:19:28 +00:00
the id referenced item (groups are created by separator items). If
the referenced item doesn't exist, a new separator group is created with
2015-04-13 03:22:33 +00:00
the given id and this item is inserted after that separator.
2015-08-28 23:19:28 +00:00
When an item is positioned, all un-positioned items are inserted after
it until a new item is positioned. So if you want to position a group of
2015-04-13 03:22:33 +00:00
menu items in the same location you only need to specify a position for
the first item.
### Examples
Template:
2016-08-16 21:50:21 +00:00
```javascript
2015-04-13 03:22:33 +00:00
[
2015-06-09 16:08:27 +00:00
{label: '4', id: '4'},
{label: '5', id: '5'},
{label: '1', id: '1', position: 'before=4'},
{label: '2', id: '2'},
2015-04-13 03:22:33 +00:00
{label: '3', id: '3'}
]
```
Menu:
```
- 1
- 2
- 3
- 4
- 5
```
Template:
2016-08-16 21:50:21 +00:00
```javascript
2015-04-13 03:22:33 +00:00
[
2015-06-09 16:08:27 +00:00
{label: 'a', position: 'endof=letters'},
{label: '1', position: 'endof=numbers'},
{label: 'b', position: 'endof=letters'},
{label: '2', position: 'endof=numbers'},
{label: 'c', position: 'endof=letters'},
2015-04-13 03:22:33 +00:00
{label: '3', position: 'endof=numbers'}
]
```
Menu:
```
- ---
- a
- b
- c
- ---
- 1
- 2
- 3
```
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