Merge pull request #9065 from electron/roles

Improve docs for MenuItem Roles

docs/api/menu-item.md

@@ -15,7 +15,7 @@ See [`Menu`](menu.md) for examples.
     * `browserWindow` BrowserWindow
     * `event` Event
   * `role` String (optional) - Define the action of the menu item, when specified the
-    `click` property will be ignored.
+    `click` property will be ignored. See [roles](#roles).
   * `type` String (optional) - Can be `normal`, `separator`, `submenu`, `checkbox` or
     `radio`.
   * `label` String - (optional)
@@ -36,12 +36,16 @@ See [`Menu`](menu.md) for examples.
   * `position` String (optional) - This field allows fine-grained definition of the
     specific location within a given menu.
 
+### 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` are optional when using a `role` and will default
+The `label` and `accelerator` values are optional when using a `role` and will
-to appropriate values for each platform.
+default to appropriate values for each platform.
 
 The `role` property can have following values:
 
@@ -63,11 +67,10 @@ The `role` property can have following values:
 * `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%
-
 * `editMenu` - Whole default "Edit" menu (Undo, Copy, etc.)
 * `windowMenu` - Whole default "Window" menu (Minimize, Close, etc.)
 
-On macOS `role` can also have following additional values:
+The following additional roles are avaiable on macOS:
 
 * `about` - Map to the `orderFrontStandardAboutPanel` action
 * `hide` - Map to the `hide` action
@@ -81,8 +84,8 @@ On macOS `role` can also have following additional values:
 * `help` - The submenu is a "Help" menu
 * `services` - The submenu is a "Services" menu
 
-When specifying `role` on macOS, `label` and `accelerator` are the only options
+When specifying a `role` on macOS, `label` and `accelerator` are the only
-that will affect the MenuItem. All other options will be ignored.
+options that will affect the menu item. All other options will be ignored.
 
 ### Instance Properties
 

docs/api/menu.md

@@ -30,8 +30,8 @@ Returns `Menu` - The application menu, if set, or `null`, if not set.
 * `action` String
 
 Sends the `action` to the first responder of application. This is used for
-emulating default Cocoa menu behaviors, usually you would just use the
+emulating default macOS menu behaviors. Usually you would just use the
-`role` property of `MenuItem`.
+[`role`](menu-item.md#roles) property of a [`MenuItem`](menu-item.md).
 
 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.
@@ -115,76 +115,36 @@ const template = [
   {
     label: 'Edit',
     submenu: [
-      {
+      {role: 'undo'},
-        role: 'undo'
+      {role: 'redo'},
-      },
+      {type: 'separator'},
-      {
+      {role: 'cut'},
-        role: 'redo'
+      {role: 'copy'},
-      },
+      {role: 'paste'},
-      {
+      {role: 'pasteandmatchstyle'},
-        type: 'separator'
+      {role: 'delete'},
-      },
+      {role: 'selectall'}
-      {
-        role: 'cut'
-      },
-      {
-        role: 'copy'
-      },
-      {
-        role: 'paste'
-      },
-      {
-        role: 'pasteandmatchstyle'
-      },
-      {
-        role: 'delete'
-      },
-      {
-        role: 'selectall'
-      }
     ]
   },
   {
     label: 'View',
     submenu: [
-      {
+      {role: 'reload'},
-        role: 'reload'
+      {role: 'forcereload'},
-      },
+      {role: 'toggledevtools'},
-      {
+      {type: 'separator'},
-        role: 'forcereload'
+      {role: 'resetzoom'},
-      },
+      {role: 'zoomin'},
-      {
+      {role: 'zoomout'},
-        role: 'toggledevtools'
+      {type: 'separator'},
-      },
+      {role: 'togglefullscreen'}
-      {
-        type: 'separator'
-      },
-      {
-        role: 'resetzoom'
-      },
-      {
-        role: 'zoomin'
-      },
-      {
-        role: 'zoomout'
-      },
-      {
-        type: 'separator'
-      },
-      {
-        role: 'togglefullscreen'
-      }
     ]
   },
   {
     role: 'window',
     submenu: [
-      {
+      {role: 'minimize'},
-        role: 'minimize'
+      {role: 'close'}
-      },
-      {
-        role: 'close'
-      }
     ]
   },
   {
@@ -202,76 +162,37 @@ if (process.platform === 'darwin') {
   template.unshift({
     label: app.getName(),
     submenu: [
-      {
+      {role: 'about'},
-        role: 'about'
+      {type: 'separator'},
-      },
+      {role: 'services', submenu: []},
-      {
+      {type: 'separator'},
-        type: 'separator'
+      {role: 'hide'},
-      },
+      {role: 'hideothers'},
-      {
+      {role: 'unhide'},
-        role: 'services',
+      {type: 'separator'},
-        submenu: []
+      {role: 'quit'}
-      },
-      {
-        type: 'separator'
-      },
-      {
-        role: 'hide'
-      },
-      {
-        role: 'hideothers'
-      },
-      {
-        role: 'unhide'
-      },
-      {
-        type: 'separator'
-      },
-      {
-        role: 'quit'
-      }
     ]
   })
-  // Edit menu.
+
+  // Edit menu
   template[1].submenu.push(
-    {
+    {type: 'separator'},
-      type: 'separator'
-    },
     {
       label: 'Speech',
       submenu: [
-        {
+        {role: 'startspeaking'},
-          role: 'startspeaking'
+        {role: 'stopspeaking'}
-        },
-        {
-          role: 'stopspeaking'
-        }
       ]
     }
   )
-  // Window menu.
+
+  // Window menu
   template[3].submenu = [
-    {
+    {role: 'close'},
-      label: 'Close',
+    {role: 'minimize'},
-      accelerator: 'CmdOrCtrl+W',
+    {role: 'zoom'},
-      role: 'close'
+    {type: 'separator'},
-    },
+    {role: 'front'}
-    {
-      label: 'Minimize',
-      accelerator: 'CmdOrCtrl+M',
-      role: 'minimize'
-    },
-    {
-      label: 'Zoom',
-      role: 'zoom'
-    },
-    {
-      type: 'separator'
-    },
-    {
-      label: 'Bring All to Front',
-      role: 'front'
-    }
   ]
 }