electron/docs/api/menu.md

374 lines
9 KiB
Markdown
Raw Normal View History

2015-08-28 23:35:22 +00:00
# Menu
2013-08-14 22:43:35 +00:00
2015-08-28 23:19:28 +00:00
The `menu` class is used to create native menus that can be used as
application menus and
[context menus](https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL/PopupGuide/ContextMenus).
This module is a main process module which can be used in a render process via
the `remote` module.
2013-08-14 22:43:35 +00:00
2015-08-28 23:19:28 +00:00
Each menu consists of multiple [menu items](menu-item.md) and each menu item can
have a submenu.
Below is an example of creating a menu dynamically in a web page
(render process) by using the [remote](remote.md) module, and showing it when
the user right clicks the page:
2013-08-14 22:43:35 +00:00
```html
<!-- index.html -->
<script>
const remote = require('electron').remote;
const Menu = remote.Menu;
const MenuItem = remote.MenuItem;
2013-08-14 22:43:35 +00:00
var menu = new Menu();
2013-12-13 06:31:19 +00:00
menu.append(new MenuItem({ label: 'MenuItem1', click: function() { console.log('item 1 clicked'); } }));
2013-08-14 22:43:35 +00:00
menu.append(new MenuItem({ type: 'separator' }));
2014-05-24 02:41:54 +00:00
menu.append(new MenuItem({ label: 'MenuItem2', type: 'checkbox', checked: true }));
2013-08-14 22:43:35 +00:00
window.addEventListener('contextmenu', function (e) {
e.preventDefault();
menu.popup(remote.getCurrentWindow());
2013-08-14 22:43:35 +00:00
}, false);
</script>
2013-08-14 22:43:35 +00:00
```
2015-08-28 23:19:28 +00:00
An example of creating the application menu in the render process with the
simple template API:
2013-08-14 22:43:35 +00:00
2015-09-02 01:19:18 +00:00
```javascript
2013-08-14 22:43:35 +00:00
var template = [
{
label: 'Edit',
submenu: [
{
label: 'Undo',
accelerator: 'CmdOrCtrl+Z',
2015-09-02 01:19:18 +00:00
role: 'undo'
2013-08-14 22:43:35 +00:00
},
{
label: 'Redo',
accelerator: 'Shift+CmdOrCtrl+Z',
2015-09-02 01:19:18 +00:00
role: 'redo'
2013-08-14 22:43:35 +00:00
},
{
type: 'separator'
},
{
label: 'Cut',
accelerator: 'CmdOrCtrl+X',
2015-09-02 01:19:18 +00:00
role: 'cut'
2013-08-14 22:43:35 +00:00
},
{
label: 'Copy',
accelerator: 'CmdOrCtrl+C',
2015-09-02 01:19:18 +00:00
role: 'copy'
2013-08-14 22:43:35 +00:00
},
{
label: 'Paste',
accelerator: 'CmdOrCtrl+V',
2015-09-02 01:19:18 +00:00
role: 'paste'
2013-08-14 22:43:35 +00:00
},
{
label: 'Select All',
accelerator: 'CmdOrCtrl+A',
2015-09-02 01:19:18 +00:00
role: 'selectall'
},
2013-08-14 22:43:35 +00:00
]
},
{
label: 'View',
submenu: [
{
label: 'Reload',
accelerator: 'CmdOrCtrl+R',
2015-09-02 01:19:18 +00:00
click: function(item, focusedWindow) {
if (focusedWindow)
focusedWindow.reload();
}
2013-08-14 22:43:35 +00:00
},
{
2015-09-02 01:19:18 +00:00
label: 'Toggle Full Screen',
accelerator: (function() {
if (process.platform == 'darwin')
return 'Ctrl+Command+F';
else
return 'F11';
})(),
click: function(item, focusedWindow) {
if (focusedWindow)
focusedWindow.setFullScreen(!focusedWindow.isFullScreen());
}
},
{
label: 'Toggle Developer Tools',
accelerator: (function() {
if (process.platform == 'darwin')
return 'Alt+Command+I';
else
return 'Ctrl+Shift+I';
})(),
click: function(item, focusedWindow) {
if (focusedWindow)
focusedWindow.toggleDevTools();
}
2013-08-14 22:43:35 +00:00
},
]
},
{
label: 'Window',
2015-09-02 01:19:18 +00:00
role: 'window',
2013-08-14 22:43:35 +00:00
submenu: [
{
label: 'Minimize',
accelerator: 'CmdOrCtrl+M',
2015-09-02 01:19:18 +00:00
role: 'minimize'
2013-08-14 22:43:35 +00:00
},
{
label: 'Close',
accelerator: 'CmdOrCtrl+W',
2015-09-02 01:19:18 +00:00
role: 'close'
2013-08-14 22:43:35 +00:00
},
]
},
{
label: 'Help',
2015-09-02 01:19:18 +00:00
role: 'help',
submenu: [
{
label: 'Learn More',
click: function() { require('electron').shell.openExternal('http://electron.atom.io') }
2015-09-02 01:19:18 +00:00
},
]
},
2013-08-14 22:43:35 +00:00
];
2015-09-02 01:19:18 +00:00
if (process.platform == 'darwin') {
var name = require('electron').app.getName();
2015-09-02 01:19:18 +00:00
template.unshift({
label: name,
submenu: [
{
label: 'About ' + name,
role: 'about'
},
{
type: 'separator'
},
{
label: 'Services',
role: 'services',
submenu: []
},
{
type: 'separator'
},
{
label: 'Hide ' + name,
accelerator: 'Command+H',
role: 'hide'
},
{
label: 'Hide Others',
accelerator: 'Command+Alt+H',
2015-09-11 12:26:48 +00:00
role: 'hideothers'
2015-09-02 01:19:18 +00:00
},
{
label: 'Show All',
2015-09-11 12:26:48 +00:00
role: 'unhide'
2015-09-02 01:19:18 +00:00
},
{
type: 'separator'
},
{
label: 'Quit',
accelerator: 'Command+Q',
click: function() { app.quit(); }
},
]
});
// Window menu.
template[3].submenu.push(
{
type: 'separator'
},
{
label: 'Bring All to Front',
role: 'front'
}
);
}
var menu = Menu.buildFromTemplate(template);
2015-06-09 21:08:34 +00:00
Menu.setApplicationMenu(menu);
2013-08-14 22:43:35 +00:00
```
## Class: Menu
2015-08-28 23:19:28 +00:00
### `new Menu()`
2013-08-14 22:43:35 +00:00
Creates a new menu.
2015-08-28 23:19:28 +00:00
## Methods
The `menu` class has the following methods:
### `Menu.setApplicationMenu(menu)`
2013-08-14 22:43:35 +00:00
* `menu` Menu
Sets `menu` as the application menu on OS X. On Windows and Linux, the `menu`
will be set as each window's top menu.
2013-08-14 22:43:35 +00:00
2015-08-28 23:19:28 +00:00
### `Menu.sendActionToFirstResponder(action)` _OS X_
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
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
2015-08-28 23:19:28 +00:00
### `Menu.buildFromTemplate(template)`
2013-08-14 22:43:35 +00:00
* `template` Array
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
### `Menu.popup([browserWindow, x, y, positioningItem])`
2013-08-14 22:43:35 +00:00
2016-01-22 18:29:26 +00:00
* `browserWindow` BrowserWindow (optional) - Default is `null`.
* `x` Number (optional) - Default is -1.
* `y` Number (**required** if `x` is used) - Default is -1.
2016-01-22 18:32:14 +00:00
* `positioningItem` Number (optional) _OS X_ - The index of the menu item to
be positioned under the mouse cursor at the specified coordinates. Default is
-1.
2016-01-22 18:29:26 +00:00
Pops up this menu as a context menu in the `browserWindow`. You can optionally
provide a `x, y` coordinate to place the menu at, otherwise it will be placed
at the current mouse cursor position.
2013-08-14 22:43:35 +00:00
2015-08-28 23:19:28 +00:00
### `Menu.append(menuItem)`
2013-08-14 22:43:35 +00:00
* `menuItem` MenuItem
Appends the `menuItem` to the menu.
2015-08-28 23:19: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.
2015-08-28 23:19:28 +00:00
### `Menu.items()`
2013-08-14 22:43:35 +00:00
2015-08-28 23:19:28 +00:00
Get an array containing the menu's items.
2015-08-28 23:19:28 +00:00
## Notes on OS X Application Menu
OS X has a completely different style of application menu from Windows and
2015-08-28 23:19:28 +00:00
Linux, here are some notes on making your app's menu more native-like.
2015-08-28 23:19:28 +00:00
### Standard Menus
On OS X 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
become standard menus:
2015-09-02 01:19:18 +00:00
* `window`
* `help`
* `services`
2015-08-28 23:19:28 +00:00
### Standard Menu Item Actions
2015-09-02 01:19:18 +00:00
OS X has provided standard actions for some menu items, like `About xxx`,
`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.
2015-08-28 23:19:28 +00:00
### Main Menu's Name
On OS X the label of application menu's first item is always your app's name,
no matter what label you set. To change it you have to change your app's name
2015-09-02 01:19:18 +00:00
by modifying your app bundle's `Info.plist` file. See [About Information
Property List Files][AboutInformationPropertyListFiles] for more information.
2015-08-28 23:19:28 +00:00
## Menu Item Position
2015-08-28 23:19:28 +00:00
You can make use of `position` and `id` to control how the item will be placed
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
placement is one of `before`, `after`, or `endof` and `id` is the unique ID of
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
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
menu items in the same location you only need to specify a position for
the first item.
### Examples
Template:
```javascript
[
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'},
{label: '3', id: '3'}
]
```
Menu:
```
- 1
- 2
- 3
- 4
- 5
```
Template:
```javascript
[
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'},
{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