Merge remote-tracking branch 'origin/master' into renaesop_master

docs/api/app.md

@@ -667,6 +667,8 @@ app.setJumpList([
   * `argv` String[] - An array of the second instance's command line arguments
   * `workingDirectory` String - The second instance's working directory
 
+Returns `Boolean`.
+
 This method makes your application a Single Instance Application - instead of
 allowing multiple instances of your app to run, this will ensure that only a
 single instance of your app is running, and other instances signal this

docs/api/browser-view.md

@@ -44,31 +44,31 @@ Objects created with `new BrowserView` have the following properties:
 
 #### `view.webContents` _Experimental_
 
-A [`webContents`](web-contents.md) object owned by this view.
+A [`WebContents`](web-contents.md) object owned by this view.
 
-#### `win.id` _Experimental_
+#### `view.id` _Experimental_
 
 A `Integer` representing the unique ID of the view.
 
 ### Instance Methods
 
-Objects created with `new BrowserWindow` have the following instance methods:
+Objects created with `new BrowserView` have the following instance methods:
 
-#### `win.setAutoResize(options)` _Experimental_
+#### `view.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.
+  * `width` Boolean - If `true`, the view's width will grow and shrink together
+    with the window. `false` by default.
+  * `height` Boolean - If `true`, the view's height will grow and shrink
+    together with the window. `false` by default.
 
-#### `win.setBounds(bounds)` _Experimental_
+#### `view.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_
+#### `view.setBackgroundColor(color)` _Experimental_
 
 * `color` String - Color in `#aarrggbb` or `#argb` form. The alpha channel is
   optional.

docs/api/browser-window.md

@@ -307,6 +307,7 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       'Electron Isolated Context' entry in the combo box at the top of the
       Console tab. **Note:** This option is currently experimental and may
       change or be removed in future Electron releases.
+    * `nativeWindowOpen` Boolean (optional) - Whether to use native `window.open()`. Defaults to `false`.
 
 When setting minimum or maximum window size with `minWidth`/`maxWidth`/
 `minHeight`/`maxHeight`, it only constrains the users. It won't prevent you from
@@ -1027,7 +1028,7 @@ Same as `webContents.capturePage([rect, ]callback)`.
   * `httpReferrer` String (optional) - A HTTP Referrer url.
   * `userAgent` String (optional) - A user agent originating the request.
   * `extraHeaders` String (optional) - Extra headers separated by "\n"
-  * `postData` ([UploadRawData](structures/upload-raw-data.md) | [UploadFile](structures/upload-file.md) | [UploadFileSystem](structures/upload-file-system.md) | [UploadBlob](structures/upload-blob.md))[] - (optional)
+  * `postData` ([UploadRawData[]](structures/upload-raw-data.md) | [UploadFile[]](structures/upload-file.md) | [UploadFileSystem[]](structures/upload-file-system.md) | [UploadBlob[]](structures/upload-blob.md)) - (optional)
   * `baseURLForDataURL` String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified `url` is a data url and needs to load other files.
 
 Same as `webContents.loadURL(url[, options])`.

docs/api/chrome-command-line-switches.md

@@ -28,7 +28,7 @@ Disables the disk cache for HTTP requests.
 
 Disable HTTP/2 and SPDY/3.1 protocols.
 
-## --debug=`port` and --debug-brk=`port`
+## --inspect=`port` and --inspect-brk=`port`
 
 Debug-related flags, see the [Debugging the Main Process][debugging-main-process] guide for details.
 
@@ -36,6 +36,10 @@ Debug-related flags, see the [Debugging the Main Process][debugging-main-process
 
 Enables remote debugging over HTTP on the specified `port`.
 
+## --disk-cache-size=`size`
+
+Forces the maximum disk space to be used by the disk cache, in bytes.
+
 ## --js-flags=`flags`
 
 Specifies the flags passed to the Node JS engine. It has to be passed when starting

docs/api/desktop-capturer.md

@@ -1,7 +1,7 @@
 # desktopCapturer
 
 > Access information about media sources that can be used to capture audio and
-> video from the desktop using the [`navigator.webkitGetUserMedia`] API.
+> video from the desktop using the [`navigator.mediaDevices.getUserMedia`] API.
 
 Process: [Renderer](../glossary.md#renderer-process)
 
@@ -16,7 +16,7 @@ desktopCapturer.getSources({types: ['window', 'screen']}, (error, sources) => {
   if (error) throw error
   for (let i = 0; i < sources.length; ++i) {
     if (sources[i].name === 'Electron') {
-      navigator.webkitGetUserMedia({
+      navigator.mediaDevices.getUserMedia({
         audio: false,
         video: {
           mandatory: {
@@ -44,12 +44,27 @@ function handleError (e) {
 ```
 
 To capture video from a source provided by `desktopCapturer` the constraints
-passed to [`navigator.webkitGetUserMedia`] must include
+passed to [`navigator.mediaDevices.getUserMedia`] must include
 `chromeMediaSource: 'desktop'`, and `audio: false`.
 
 To capture both audio and video from the entire desktop the constraints passed
-to [`navigator.webkitGetUserMedia`] must include `chromeMediaSource: 'screen'`,
-and `audio: true`, but should not include a `chromeMediaSourceId` constraint.
+to [`navigator.mediaDevices.getUserMedia`] must include `chromeMediaSource: 'desktop'`,
+for both `audio` and `video`, but should not include a `chromeMediaSourceId` constraint.
+
+```javascript
+const constraints = {
+  audio: {
+    mandatory: {
+      chromeMediaSource: 'desktop'
+    }
+  },
+  video: {
+    mandatory: {
+      chromeMediaSource: 'desktop'
+    }
+  }
+}
+```
 
 ## Methods
 
@@ -60,7 +75,7 @@ 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` [Size](structures/size.md) (optional) - The size that the media source thumbnail 
+  * `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
@@ -73,4 +88,4 @@ and calls `callback(error, sources)` when finished.
 objects, each `DesktopCapturerSource` represents a screen or an individual window that can be
 captured.
 
-[`navigator.webkitGetUserMedia`]: https://developer.mozilla.org/en/docs/Web/API/Navigator/getUserMedia
+[`navigator.mediaDevices.getUserMedia`]: https://developer.mozilla.org/en/docs/Web/API/MediaDevices/getUserMedia

docs/api/dialog.md

@@ -161,8 +161,8 @@ It returns the index of the clicked button.
 
 The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
 
-If a `callback` is passed, the API call will be asynchronous and the result
-will be passed via `callback(response)`.
+If a `callback` is passed, the dialog will not block the process. The API call
+will be asynchronous and the result will be passed via `callback(response)`.
 
 ### `dialog.showErrorBox(title, content)`
 

docs/api/native-image.md

@@ -153,6 +153,8 @@ Creates a new `NativeImage` instance from `buffer`.
 
 * `dataURL` String
 
+Returns `NativeImage`
+
 Creates a new `NativeImage` instance from `dataURL`.
 
 ## Class: NativeImage

docs/api/structures/memory-info.md

@@ -1,6 +1,6 @@
 # MemoryInfo Object
 
-* `workingSetSize` Integer - Process id of the process.
+* `pid` Integer - Process id of the process.
 * `workingSetSize` Integer - The amount of memory currently pinned to actual physical RAM.
 * `peakWorkingSetSize` Integer - The maximum amount of memory that has ever been pinned
   to actual physical RAM.
@@ -9,4 +9,4 @@
 * `sharedBytes` Integer - The amount of memory shared between processes, typically
   memory consumed by the Electron code itself
 
-Note that all statistics are reported in Kilobytes.
+Note that all statistics are reported in Kilobytes.

docs/api/web-contents.md

@@ -218,6 +218,36 @@ When in-page navigation happens, the page URL changes but does not cause
 navigation outside of the page. Examples of this occurring are when anchor links
 are clicked or when the DOM `hashchange` event is triggered.
 
+#### Event: 'will-prevent-unload'
+
+Returns:
+
+* `event` Event
+
+Emitted when a `beforeunload` event handler is attempting to cancel a page unload.
+
+Calling `event.preventDefault()` will ignore the `beforeunload` event handler
+and allow the page to be unloaded.
+
+```javascript
+const {BrowserWindow, dialog} = require('electron')
+const win = new BrowserWindow({width: 800, height: 600})
+win.webContents.on('will-prevent-unload', (event) => {
+  const choice = dialog.showMessageBox(win, {
+    type: 'question',
+    buttons: ['Leave', 'Stay'],
+    title: 'Do you want to leave this site?',
+    message: 'Changes you made may not be saved.',
+    defaultId: 0,
+    cancelId: 1
+  })
+  const leave = (choice === 0)
+  if (leave) {
+    event.preventDefault()
+  }
+})
+```
+
 #### Event: 'crashed'
 
 Returns:
@@ -537,7 +567,7 @@ that can't be set via `<webview>` attributes.
   * `httpReferrer` String (optional) - A HTTP Referrer url.
   * `userAgent` String (optional) - A user agent originating the request.
   * `extraHeaders` String (optional) - Extra headers separated by "\n"
-  * `postData` ([UploadRawData](structures/upload-raw-data.md) | [UploadFile](structures/upload-file.md) | [UploadFileSystem](structures/upload-file-system.md) | [UploadBlob](structures/upload-blob.md))[] - (optional)
+  * `postData` ([UploadRawData[]](structures/upload-raw-data.md) | [UploadFile[]](structures/upload-file.md) | [UploadFileSystem[]](structures/upload-file-system.md) | [UploadBlob[]](structures/upload-blob.md)) - (optional)
   * `baseURLForDataURL` String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified `url` is a data url and needs to load other files.
 
 Loads the `url` in the window. The `url` must contain the protocol prefix,
@@ -1295,6 +1325,10 @@ Setting the WebRTC IP handling policy allows you to control which IPs are
 exposed via WebRTC.  See [BrowserLeaks](https://browserleaks.com/webrtc) for
 more details.
 
+#### `contents.getOSProcessId()`
+
+Returns `Integer` - The `pid` of the associated renderer process.
+
 ### Instance Properties
 
 #### `contents.id`

docs/api/webview-tag.md

@@ -312,8 +312,8 @@ webview.addEventListener('dom-ready', () => {
   * `httpReferrer` String (optional) - A HTTP Referrer url.
   * `userAgent` String (optional) - A user agent originating the request.
   * `extraHeaders` String (optional) - Extra headers separated by "\n"
-  * `postData` ([UploadRawData](structures/upload-raw-data.md) | [UploadFile](structures/upload-file.md) | [UploadFileSystem](structures/upload-file-system.md) | [UploadBlob](structures/upload-blob.md))[] - (optional)
-  * `baseURLForDataURL` String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified `url` is a data url and needs to load other files. 
+  * `postData` ([UploadRawData[]](structures/upload-raw-data.md) | [UploadFile[]](structures/upload-file.md) | [UploadFileSystem[]](structures/upload-file-system.md) | [UploadBlob[]](structures/upload-blob.md)) - (optional)
+  * `baseURLForDataURL` String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified `url` is a data url and needs to load other files.
 
 Loads the `url` in the webview, the `url` must contain the protocol prefix,
 e.g. the `http://` or `file://`.
@@ -511,14 +511,14 @@ Inserts `text` to the focused element.
 
 * `text` String - Content to be searched, must not be empty.
 * `options` Object (optional)
-  * `forward` Boolean - Whether to search forward or backward, defaults to `true`.
-  * `findNext` Boolean - Whether the operation is first request or a follow up,
+  * `forward` Boolean - (optional) Whether to search forward or backward, defaults to `true`.
+  * `findNext` Boolean - (optional) Whether the operation is first request or a follow up,
     defaults to `false`.
-  * `matchCase` Boolean - Whether search should be case-sensitive,
+  * `matchCase` Boolean - (optional) Whether search should be case-sensitive,
     defaults to `false`.
-  * `wordStart` Boolean - Whether to look only at the start of words.
+  * `wordStart` Boolean - (optional) Whether to look only at the start of words.
     defaults to `false`.
-  * `medialCapitalAsWordStart` Boolean - When combined with `wordStart`,
+  * `medialCapitalAsWordStart` Boolean - (optional) When combined with `wordStart`,
     accepts a match in the middle of a word if the match begins with an
     uppercase letter followed by a lowercase or non-letter.
     Accepts several other intra-word matches, defaults to `false`.

docs/api/window-open.md

@@ -45,3 +45,40 @@ has to be a field of `BrowserWindow`'s options.
 
 Sends a message to the parent window with the specified origin or `*` for no
 origin preference.
+
+### Use Native `window.open()`
+
+If you want to use native `window.open()` implementation, pass `useNativeWindowOpen: true` in `webPreferences` option.
+Native `window.open()` allows synchronous access to opened windows so it is convenient choice if you need to open a dialog or a preferences window.
+
+The creation of the `BrowserWindow` is customizable in `WebContents`'s `new-window` event.
+
+```javascript
+// main process
+const mainWindow = new BrowserWindow({
+  width: 800,
+  height: 600,
+  webPreferences: {
+    nativeWindowOpen: true
+  }
+})
+mainWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures) => {
+  if (frameName === 'modal') {
+    // open window as modal
+    event.preventDefault()
+    Object.assign(options, {
+      modal: true,
+      parent: mainWindow,
+      width: 100,
+      height: 100
+    })
+    event.newGuest = new BrowserWindow(options)
+  }
+})
+```
+
+```javascript
+// renderer process (mainWindow)
+let modal = window.open('', 'modal')
+modal.document.write('<h1>Hello</h1>')
+```