Merge branch 'master' into native-window-open

docs/api/browser-view.md

@@ -0,0 +1,74 @@
+## Class: BrowserView
+
+> Create and control views.
+
+**Note:** The BrowserView API is currently experimental and may change or be
+removed in future Electron releases.
+
+Process: [Main](../glossary.md#main-process)
+
+A `BrowserView` can be used to embed additional web content into a
+`BrowserWindow`. It is like a child window, except that it is positioned
+relative to its owning window. It is meant to be an alternative to the
+`webview` tag.
+
+## Example
+
+```javascript
+// In the main process.
+const {BrowserView, BrowserWindow} = require('electron')
+
+let win = new BrowserWindow({width: 800, height: 600})
+win.on('closed', () => {
+  win = null
+})
+
+let view = new BrowserView({
+  webPreferences: {
+    nodeIntegration: false
+  }
+})
+win.addChildView(view)
+view.setBounds(0, 0, 300, 300)
+view.webContents.loadURL('https://electron.atom.io')
+```
+
+### `new BrowserView([options])` _Experimental_
+
+* `options` Object (optional)
+  * `webPreferences` Object (optional) - See [BrowserWindow](browser-window.md).
+
+### Instance Properties
+
+Objects created with `new BrowserView` have the following properties:
+
+#### `view.webContents` _Experimental_
+
+A [`webContents`](web-contents.md) object owned by this view.
+
+#### `win.id` _Experimental_
+
+A `Integer` representing the unique ID of the view.
+
+### Instance Methods
+
+Objects created with `new BrowserWindow` have the following instance methods:
+
+#### `win.setAutoResize(options)` _Experimental_
+
+* `options` Object
+  * `width`: If `true`, the view's width will grow and shrink together with
+    the window. `false` by default.
+  * `height`: If `true`, the view's height will grow and shrink together with
+    the window. `false` by default.
+
+#### `win.setBounds(bounds)` _Experimental_
+
+* `bounds` [Rectangle](structures/rectangle.md)
+
+Resizes and moves the view to the supplied bounds relative to the window.
+
+#### `win.setBackgroundColor(color)` _Experimental_
+
+* `color` String - Color in `#aarrggbb` or `#argb` form. The alpha channel is
+  optional.

docs/api/browser-window.md

@@ -683,10 +683,8 @@ Returns `Boolean` - Whether the window is in fullscreen mode.
 
 * `aspectRatio` Float - The aspect ratio to maintain for some portion of the
 content view.
-* `extraSize` Object (optional) - The extra size not to be included while
+* `extraSize` [Size](structures/size.md) - The extra size not to be included while
 maintaining the aspect ratio.
-  * `width` Integer
-  * `height` Integer
 
 This will make a window maintain an aspect ratio. The extra size allows a
 developer to have space, specified in pixels, not included within the aspect
@@ -1292,6 +1290,13 @@ machine has a touch bar and is running on macOS 10.12.1+.
 **Note:** The TouchBar API is currently experimental and may change or be
 removed in future Electron releases.
 
+#### `win.setBrowserView(browserView)` _Experimental_
+
+* `browserView` [BrowserView](browser-view.md)
+
+**Note:** The BrowserView API is currently experimental and may change or be
+removed in future Electron releases.
+
 [blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.json5?l=62
 [quick-look]: https://en.wikipedia.org/wiki/Quick_Look
 [vibrancy-docs]: https://developer.apple.com/reference/appkit/nsvisualeffectview?language=objc

docs/api/desktop-capturer.md

@@ -60,9 +60,8 @@ The `desktopCapturer` module has the following methods:
 * `options` Object
   * `types` String[] - An array of Strings that lists the types of desktop sources
     to be captured, available types are `screen` and `window`.
-  * `thumbnailSize` Object (optional) - The size that the media source thumbnail should be scaled to.
-    * `width` Integer - Default is `150`
-    * `height` Integer - Default is `150`
+  * `thumbnailSize` [Size](structures/size.md) (optional) - The size that the media source thumbnail 
+    should be scaled to. Default is `150` x `150`.
 * `callback` Function
   * `error` Error
   * `sources` [DesktopCapturerSource[]](structures/desktop-capturer-source.md)

docs/api/dialog.md

@@ -115,8 +115,9 @@ will be passed via `callback(filename)`
 * `browserWindow` BrowserWindow (optional)
 * `options` Object
   * `type` String (optional) - Can be `"none"`, `"info"`, `"error"`, `"question"` or
-  `"warning"`. On Windows, "question" displays the same icon as "info", unless
-  you set an icon using the "icon" option.
+  `"warning"`. On Windows, `"question"` displays the same icon as `"info"`, unless
+  you set an icon using the `"icon"` option. On macOS, both `"warning"` and
+  `"error"` display the same warning icon.
   * `buttons` String[] (optional) - Array of texts for buttons. On Windows, an empty array
     will result in one button labeled "OK".
   * `defaultId` Integer (optional) - Index of the button in the buttons array which will
@@ -175,6 +176,20 @@ it is usually used to report errors in early stage of startup.  If called
 before the app `ready`event on Linux, the message will be emitted to stderr,
 and no GUI dialog will appear.
 
+### `dialog.showCertificateTrustDialog([browserWindow, ]options, callback)` _macOS_
+
+* `browserWindow` BrowserWindow (optional)
+* `options` Object
+  * `certificate` [Certificate](structures/certificate.md) - The certificate to trust/import.
+  * `message` String - The message to display to the user.
+* `callback` Function
+
+Displays a modal dialog that shows a message and certificate information, and
+gives the user the option of trusting/importing the certificate.
+
+The `browserWindow` argument allows the dialog to attach itself to a parent
+window, making it modal.
+
 ## Sheets
 
 On macOS, dialogs are presented as sheets attached to a window if you provide

docs/api/frameless-window.md

@@ -98,6 +98,8 @@ By default, the frameless window is non-draggable. Apps need to specify
 `-webkit-app-region: no-drag` to exclude the non-draggable area from the
  draggable region. Note that only rectangular shapes are currently supported.
 
+Note: `-webkit-app-region: drag` is known to have problems while the developer tools are open. See this [GitHub issue](https://github.com/electron/electron/issues/3647) for more information including a workaround.
+
 To make the whole window draggable, you can add `-webkit-app-region: drag` as
 `body`'s style:
 

docs/api/menu.md

@@ -16,8 +16,11 @@ The `menu` class has the following static methods:
 
 * `menu` Menu
 
-Sets `menu` as the application menu on macOS. On Windows and Linux, the `menu`
-will be set as each window's top menu.
+Sets `menu` as the application menu on macOS. On Windows and Linux, the
+`menu` will be set as each window's top menu.
+
+Passing `null` will remove the menu bar on Windows and Linux but has no
+effect on macOS.
 
 **Note:** This API has to be called after the `ready` event of `app` module.
 

docs/api/native-image.md

@@ -219,10 +219,7 @@ Returns `Boolean` -  Whether the image is empty.
 
 #### `image.getSize()`
 
-Returns `Object`:
-
-* `width` Integer
-* `height` Integer
+Returns [`Size`](structures/size.md)
 
 #### `image.setTemplateImage(option)`
 
@@ -236,11 +233,7 @@ Returns `Boolean` - Whether the image is a template image.
 
 #### `image.crop(rect)`
 
-* `rect` Object - The area of the image to crop
-  * `x` Integer
-  * `y` Integer
-  * `width` Integer
-  * `height` Integer
+* `rect` [Rectangle](structures/rectangle.md) - The area of the image to crop
 
 Returns `NativeImage` - The cropped image.
 

docs/api/screen.md

@@ -91,10 +91,7 @@ The `screen` module has the following methods:
 
 ### `screen.getCursorScreenPoint()`
 
-Returns `Object`:
-
-* `x` Integer
-* `y` Integer
+Returns [`Point`](structures/point.md)
 
 The current absolute position of the mouse pointer.
 
@@ -108,9 +105,7 @@ Returns [`Display[]`](structures/display.md) - An array of displays that are cur
 
 ### `screen.getDisplayNearestPoint(point)`
 
-* `point` Object
-  * `x` Integer
-  * `y` Integer
+* `point` [Point](structures/point.md)
 
 Returns [`Display`](structures/display.md) - The display nearest the specified point.
 

docs/api/session.md

@@ -287,7 +287,7 @@ win.webContents.session.setCertificateVerifyProc((request, callback) => {
 #### `ses.setPermissionRequestHandler(handler)`
 
 * `handler` Function
-  * `webContents` Object - [WebContents](web-contents.md) requesting the permission.
+  * `webContents` [WebContents](web-contents.md) - WebContents requesting the permission.
   * `permission` String - Enum of 'media', 'geolocation', 'notifications', 'midiSysex',
     'pointerLock', 'fullscreen', 'openExternal'.
   * `callback` Function
@@ -388,15 +388,15 @@ The following properties are available on instances of `Session`:
 
 #### `ses.cookies`
 
-A Cookies object for this session.
+A [Cookies](cookies.md) object for this session.
 
 #### `ses.webRequest`
 
-A WebRequest object for this session.
+A [WebRequest](web-request.md) object for this session.
 
 #### `ses.protocol`
 
-A Protocol object (an instance of [protocol](protocol.md) module) for this session.
+A [Protocol](protocol.md) object for this session.
 
 ```javascript
 const {app, session} = require('electron')

docs/api/structures/display.md

@@ -6,13 +6,9 @@
 * `scaleFactor` Number - Output device's pixel scale factor.
 * `touchSupport` String - Can be `available`, `unavailable`, `unknown`.
 * `bounds` [Rectangle](rectangle.md)
-* `size` Object
-  * `height` Number
-  * `width` Number
+* `size` [Size](size.md)
 * `workArea` [Rectangle](rectangle.md)
-* `workAreaSize` Object
-  * `height` Number
-  * `width` Number
+* `workAreaSize` [Size](size.md)
 
 The `Display` object represents a physical display connected to the system. A
 fake `Display` may exist on a headless system, or a `Display` may correspond to

docs/api/structures/mime-typed-buffer.md

@@ -1,4 +1,4 @@
 # MimeTypedBuffer Object
 
 * `mimeType` String - The mimeType of the Buffer that you are sending
-* `buffer` Buffer - The actual Buffer content
+* `data` Buffer - The actual Buffer content

docs/api/structures/point.md

@@ -0,0 +1,4 @@
+# Point Object
+
+* `x` Number
+* `y` Number

docs/api/structures/size.md

@@ -0,0 +1,4 @@
+# Size Object
+
+* `width` Number
+* `height` Number

docs/api/touch-bar.md

@@ -4,9 +4,11 @@
 
 Process: [Main](../tutorial/quick-start.md#main-process)
 
-### `new TouchBar(items)` _Experimental_
+### `new TouchBar(options)` _Experimental_
 
-* `items` ([TouchBarButton](touch-bar-button.md) | [TouchBarColorPicker](touch-bar-color-picker.md) | [TouchBarGroup](touch-bar-group.md) | [TouchBarLabel](touch-bar-label.md) | [TouchBarPopover](touch-bar-popover.md) | [TouchBarSlider](touch-bar-slider.md) | [TouchBarSpacer](touch-bar-spacer.md))[]
+* `options` - Object
+  * `items` ([TouchBarButton](touch-bar-button.md) | [TouchBarColorPicker](touch-bar-color-picker.md) | [TouchBarGroup](touch-bar-group.md) | [TouchBarLabel](touch-bar-label.md) | [TouchBarPopover](touch-bar-popover.md) | [TouchBarScrubber](touch-bar-scrubber.md) | [TouchBarSegmentedControl](touch-bar-segmented-control.md) | [TouchBarSlider](touch-bar-slider.md) | [TouchBarSpacer](touch-bar-spacer.md))[]
+  * `escapeItem` ([TouchBarButton](touch-bar-button.md) | [TouchBarColorPicker](touch-bar-color-picker.md) | [TouchBarGroup](touch-bar-group.md) | [TouchBarLabel](touch-bar-label.md) | [TouchBarPopover](touch-bar-popover.md) | [TouchBarScrubber](touch-bar-scrubber.md) | [TouchBarSegmentedControl](touch-bar-segmented-control.md) | [TouchBarSlider](touch-bar-slider.md) | [TouchBarSpacer](touch-bar-spacer.md)) (optional)
 
 Creates a new touch bar with the specified items. Use
 `BrowserWindow.setTouchBar` to add the `TouchBar` to a window.
@@ -14,6 +16,16 @@ Creates a new touch bar with the specified items. Use
 **Note:** The TouchBar API is currently experimental and may change or be
 removed in future Electron releases.
 
+### Instance Properties
+
+The following properties are available on instances of `TouchBar`:
+
+#### `touchBar.escapeItem`
+
+The `TouchBarItem` that will replace the "esc" button on the touch bar when set.
+Setting to `null` restores the default "esc" button. Changing this value
+immediately updates the escape item in the touch bar.
+
 ## Examples
 
 Below is an example of a simple slot machine touch bar game with a button

docs/api/tray.md

@@ -219,9 +219,7 @@ Displays a tray balloon.
 #### `tray.popUpContextMenu([menu, position])` _macOS_ _Windows_
 
 * `menu` Menu (optional)
-* `position` Object (optional) - The pop up position.
-  * `x` Integer
-  * `y` Integer
+* `position` [Point](structures/point.md) (optional) - The pop up position.
 
 Pops up the context menu of the tray icon. When `menu` is passed, the `menu` will
 be shown instead of the tray icon's context menu.

docs/api/web-contents.md

@@ -375,12 +375,8 @@ Returns:
 * `type` String
 * `image` NativeImage (optional)
 * `scale` Float (optional) - scaling factor for the custom cursor
-* `size` Object (optional) - the size of the `image`
-  * `width` Integer
-  * `height` Integer
-* `hotspot` Object (optional) - coordinates of the custom cursor's hotspot
-  * `x` Integer - x coordinate
-  * `y` Integer - y coordinate
+* `size` [Size](structures/size.md) (optional) - the size of the `image`
+* `hotspot` [Point](structures/point.md) (optional) - coordinates of the custom cursor's hotspot
 
 Emitted when the cursor's type changes. The `type` parameter can be `default`,
 `crosshair`, `pointer`, `text`, `wait`, `help`, `e-resize`, `n-resize`,
@@ -1067,24 +1063,16 @@ app.on('ready', () => {
       (default: `desktop`)
     * `desktop` - Desktop screen type
     * `mobile` - Mobile screen type
-  * `screenSize` Object - Set the emulated screen size (screenPosition == mobile)
-    * `width` Integer - Set the emulated screen width
-    * `height` Integer - Set the emulated screen height
-  * `viewPosition` Object - Position the view on the screen
+  * `screenSize` [Size](structures/size.md) - Set the emulated screen size (screenPosition == mobile)
+  * `viewPosition` [Point](structures/point.md) - Position the view on the screen
       (screenPosition == mobile) (default: `{x: 0, y: 0}`)
-    * `x` Integer - Set the x axis offset from top left corner
-    * `y` Integer - Set the y axis offset from top left corner
   * `deviceScaleFactor` Integer - Set the device scale factor (if zero defaults to
       original device scale factor) (default: `0`)
-  * `viewSize` Object - Set the emulated view size (empty means no override)
-    * `width` Integer - Set the emulated view width
-    * `height` Integer - Set the emulated view height
+  * `viewSize` [Size](structures/size.md) - Set the emulated view size (empty means no override)
   * `fitToView` Boolean - Whether emulated view should be scaled down if
       necessary to fit into available space (default: `false`)
-  * `offset` Object - Offset of the emulated view inside available space (not in
-      fit to view mode) (default: `{x: 0, y: 0}`)
-    * `x` Float - Set the x axis offset from top left corner
-    * `y` Float - Set the y axis offset from top left corner
+  * `offset` [Point](structures/point.md) - Offset of the emulated view inside available space
+      (not in fit to view mode) (default: `{x: 0, y: 0}`)
   * `scale` Float - Scale of emulated view inside available space (not in fit to
       view mode) (default: `1`)
 

docs/api/web-request.md

@@ -42,6 +42,8 @@ The following methods are available on instances of `WebRequest`:
 #### `webRequest.onBeforeRequest([filter, ]listener)`
 
 * `filter` Object
+  * `urls` String[] - Array of URL patterns that will be used to filter out the 
+        requests that do not match the URL patterns.
 * `listener` Function
   * `details` Object
     * `id` Integer
@@ -66,6 +68,8 @@ The `callback` has to be called with an `response` object.
 #### `webRequest.onBeforeSendHeaders([filter, ]listener)`
 
 * `filter` Object
+  * `urls` String[] - Array of URL patterns that will be used to filter out the 
+        requests that do not match the URL patterns.
 * `listener` Function
 
 The `listener` will be called with `listener(details, callback)` before sending
@@ -90,6 +94,8 @@ The `callback` has to be called with an `response` object.
 #### `webRequest.onSendHeaders([filter, ]listener)`
 
 * `filter` Object
+  * `urls` String[] - Array of URL patterns that will be used to filter out the 
+        requests that do not match the URL patterns.
 * `listener` Function
   * `details` Object
     * `id` Integer
@@ -106,6 +112,8 @@ response are visible by the time this listener is fired.
 #### `webRequest.onHeadersReceived([filter, ]listener)`
 
 * `filter` Object
+  * `urls` String[] - Array of URL patterns that will be used to filter out the 
+        requests that do not match the URL patterns.
 * `listener` Function
 
 The `listener` will be called with `listener(details, callback)` when HTTP
@@ -134,6 +142,8 @@ The `callback` has to be called with an `response` object.
 #### `webRequest.onResponseStarted([filter, ]listener)`
 
 * `filter` Object
+  * `urls` String[] - Array of URL patterns that will be used to filter out the 
+        requests that do not match the URL patterns.
 * `listener` Function
   * `details` Object
     * `id` Integer
@@ -154,6 +164,8 @@ and response headers are available.
 #### `webRequest.onBeforeRedirect([filter, ]listener)`
 
 * `filter` Object
+  * `urls` String[] - Array of URL patterns that will be used to filter out the 
+        requests that do not match the URL patterns.
 * `listener` Function
   * `details` Object
     * `id` String
@@ -174,6 +186,8 @@ redirect is about to occur.
 #### `webRequest.onCompleted([filter, ]listener)`
 
 * `filter` Object
+  * `urls` String[] - Array of URL patterns that will be used to filter out the 
+        requests that do not match the URL patterns.
 * `listener` Function
   * `details` Object
     * `id` Integer
@@ -192,6 +206,8 @@ completed.
 #### `webRequest.onErrorOccurred([filter, ]listener)`
 
 * `filter` Object
+  * `urls` String[] - Array of URL patterns that will be used to filter out the 
+        requests that do not match the URL patterns.
 * `listener` Function
   * `details` Object
     * `id` Integer