electron/docs/api/menu-item.md

83 lines
3 KiB
Markdown
Raw Normal View History

2015-08-28 23:35:22 +00:00
# MenuItem
2015-08-28 23:19:28 +00:00
2015-10-02 13:53:55 +00:00
The `menu-item` module allows you to add items to an application or context
2015-08-28 23:19:28 +00:00
[`menu`](menu.md).
See [`menu`](menu.md) for examples.
2013-09-09 07:35:57 +00:00
2013-08-14 22:43:35 +00:00
## Class: MenuItem
2015-08-28 23:19:28 +00:00
Create a new `MenuItem` with the following method:
2013-08-14 22:43:35 +00:00
### new MenuItem(options)
* `options` Object
2015-09-02 01:19:18 +00:00
* `click` Function - Will be called with `click(menuItem, browserWindow)` when
the menu item is clicked
* `role` String - Define the action of the menu item; when specified the
2015-09-02 01:19:18 +00:00
`click` property will be ignored
* `type` String - Can be `normal`, `separator`, `submenu`, `checkbox` or
`radio`
2013-08-14 22:43:35 +00:00
* `label` String
* `sublabel` String
* `accelerator` [Accelerator](accelerator.md)
2015-02-13 04:12:40 +00:00
* `icon` [NativeImage](native-image.md)
* `enabled` Boolean - If false, the menu item will be greyed out and unclickable.
* `visible` Boolean - If false, the menu item will be entirely hidden.
* `checked` Boolean - Should only be specified for `checkbox` or `radio` type
menu items.
* `submenu` Menu - 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` then it will be automatically converted to one using
`Menu.buildFromTemplate`.
* `id` String - Unique within a single menu. If defined then it can be used
as a reference to this item by the position attribute.
* `position` String - This field allows fine-grained definition of the
specific location within a given menu.
2015-09-02 01:19:18 +00:00
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.
2015-09-02 01:19:18 +00:00
The `role` property can have following values:
* `undo`
* `redo`
* `cut`
* `copy`
* `paste`
* `selectall`
* `minimize` - Minimize current window
* `close` - Close current window
On OS X `role` can also have following additional values:
* `about` - Map to the `orderFrontStandardAboutPanel` action
* `hide` - Map to the `hide` action
* `hideothers` - Map to the `hideOtherApplications` action
* `unhide` - Map to the `unhideAllApplications` action
* `front` - Map to the `arrangeInFront` action
* `window` - The submenu is a "Window" menu
* `help` - The submenu is a "Help" menu
* `services` - The submenu is a "Services" menu
When specifying `role` on OS X, `label` and `accelerator` are the only options that will affect the MenuItem. All other options will be ignored.
## Instance Properties
The following properties (and no others) can be updated on an existing `MenuItem`:
* `enabled` Boolean
* `visible` Boolean
* `checked` Boolean
Their meanings are as described above.
A `checkbox` menu item will toggle its `checked` property on and off when
selected. You can add a `click` function to do additional work.
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. Again,
you can add a `click` function for additional behavior.