mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 2

Merge branch 'master' into native-window-open

Browse source
This commit is contained in:
Ryohei Ikegami 2017-04-04 20:54:37 +09:00
commit 61fa8693d2
105 changed files with 2439 additions and 907 deletions
Download patch file Download diff file Expand all files Collapse all files

3
docs/README.md
View file

@ -103,3 +103,6 @@ an issue:
* [Debug Instructions (Windows)](development/debug-instructions-windows.md)
* [Setting Up Symbol Server in debugger](development/setting-up-symbol-server.md)
* [Documentation Styleguide](styleguide.md)
* [Updating Chrome](development/updating-chrome.md)
* [Chromium Development](development/chromium-development.md)
* [V8 Development](development/v8-development.md)

11
docs/api/browser-window.md
View file

@ -211,6 +211,9 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
width of the web page when zoomed, `false` will cause it to zoom to the
width of the screen. This will also affect the behavior when calling
`maximize()` directly. Default is `false`.
* `tabbingIdentifier` String (optional) - Tab group name, allows opening the
window as a native tab on macOS 10.12+. Windows with the same tabbing
identifier will be grouped together.
* `webPreferences` Object (optional) - Settings of web page's features.
* `devTools` Boolean (optional) - Whether to enable DevTools. If it is set to `false`, can not use `BrowserWindow.webContents.openDevTools()` to open DevTools. Default is `true`.
* `nodeIntegration` Boolean (optional) - Whether node integration is enabled. Default
@ -225,6 +228,13 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
When node integration is turned off, the preload script can reintroduce
Node global symbols back to the global scope. See example
[here](process.md#event-loaded).
* `sandbox` Boolean (optional) - If set, this will sandbox the renderer
associated with the window, making it compatible with the Chromium
OS-level sandbox and disabling the Node.js engine. This is not the same as
the `nodeIntegration` option and the APIs available to the preload script
are more limited. Read more about the option [here](sandbox-option.md).
**Note:** This option is currently experimental and may change or be
removed in future Electron releases.
* `session` [Session](session.md#class-session) (optional) - Sets the session used by the
page. Instead of passing the Session object directly, you can also choose to
use the `partition` option instead, which accepts a partition string. When
@ -282,7 +292,6 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
window. Defaults to `false`. See the
[offscreen rendering tutorial](../tutorial/offscreen-rendering.md) for
more details.
* `sandbox` Boolean (optional) - Whether to enable Chromium OS-level sandbox.
* `contextIsolation` Boolean (optional) - Whether to run Electron APIs and
the specified `preload` script in a separate JavaScript context. Defaults
to `false`. The context that the `preload` script runs in will still

31
docs/api/client-request.md
View file

@ -29,6 +29,11 @@ the hostname and the port number 'hostname:port'
* `hostname` String (optional) - The server host name.
* `port` Integer (optional) - The server's listening port number.
* `path` String (optional) - The path part of the request URL.
* `redirect` String (optional) - The redirect mode for this request. Should be
one of `follow`, `error` or `manual`. Defaults to `follow`. When mode is `error`,
any redirection will be aborted. When mode is `manual` the redirection will be
deferred until [`request.followRedirect`](#requestfollowRedirect) is invoked. Listen for the [`redirect`](#event-redirect) event in
this mode to get more details about the redirect request.
`options` properties such as `protocol`, `host`, `hostname`, `port` and `path`
strictly follow the Node.js model as described in the
@ -65,6 +70,8 @@ Returns:
* `port` Integer
* `realm` String
* `callback` Function
* `username` String
* `password` String
Emitted when an authenticating proxy is asking for user credentials.
@ -119,6 +126,19 @@ Emitted as the last event in the HTTP request-response transaction. The `close`
event indicates that no more events will be emitted on either the `request` or
`response` objects.
#### Event: 'redirect'
Returns:
* `statusCode` Integer
* `method` String
* `redirectUrl` String
* `responseHeaders` Object
Emitted when there is redirection and the mode is `manual`. Calling
[`request.followRedirect`](#requestfollowRedirect) will continue with the redirection.
### Instance Properties
#### `request.chunkedEncoding`
@ -138,17 +158,18 @@ internally buffered inside Electron process memory.
#### `request.setHeader(name, value)`
* `name` String - An extra HTTP header name.
* `value` String - An extra HTTP header value.
* `value` Object - An extra HTTP header value.
Adds an extra HTTP header. The header name will issued as it is without
lowercasing. It can be called only before first write. Calling this method after
the first write will throw an error.
the first write will throw an error. If the passed value is not a `String`, its
`toString()` method will be called to obtain the final value.
#### `request.getHeader(name)`
* `name` String - Specify an extra header name.
Returns String - The value of a previously set extra header name.
Returns Object - The value of a previously set extra header name.
#### `request.removeHeader(name)`
@ -190,3 +211,7 @@ Cancels an ongoing HTTP transaction. If the request has already emitted the
`close` event, the abort operation will have no effect. Otherwise an ongoing
event will emit `abort` and `close` events. Additionally, if there is an ongoing
response object,it will emit the `aborted` event.
#### `request.followRedirect()`
Continues any deferred redirection request when the redirection mode is `manual`.

2
docs/api/crash-reporter.md
View file

@ -40,7 +40,7 @@ The `crashReporter` module has the following methods:
* `companyName` String (optional)
* `submitURL` String - URL that crash reports will be sent to as POST.
* `productName` String (optional) - Defaults to `app.getName()`.
* `uploadToServer` Boolean (optional) _Linux_ _macOS_ - Whether crash reports should be sent to the server
* `uploadToServer` Boolean (optional) - Whether crash reports should be sent to the server
Default is `true`.
* `ignoreSystemCrashHandler` Boolean (optional) - Default is `false`.
* `extra` Object (optional) - An object you can define that will be sent along with the

5
docs/api/desktop-capturer.md
View file

@ -60,8 +60,9 @@ 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 suggested size that the media source
thumbnail should be scaled to, defaults to `{width: 150, height: 150}`.
* `thumbnailSize` Object (optional) - The size that the media source thumbnail should be scaled to.
* `width` Integer - Default is `150`
* `height` Integer - Default is `150`
* `callback` Function
* `error` Error
* `sources` [DesktopCapturerSource[]](structures/desktop-capturer-source.md)

20
docs/api/dialog.md
View file

@ -46,16 +46,8 @@ The `dialog` module has the following methods:
* `noResolveAliases` - Disable the automatic alias (symlink) path
resolution. Selected aliases will now return the alias path instead of
their target path. _macOS_
* `normalizeAccessKeys` Boolean (optional) - Normalize the keyboard access keys
across platforms. Default is `false`. Enabling this assumes `&` is used in
the button labels for the placement of the keyboard shortcut access key
and labels will be converted so they work correctly on each platform, `&`
characters are removed on macOS, converted to `_` on Linux, and left
untouched on Windows. For example, a button label of `Vie&w` will be
converted to `Vie_w` on Linux and `View` on macOS and can be selected
via `Alt-W` on Windows and Linux.
* `message` String (optional) _macOS_ - Message to display above input
boxes.
* `message` String (optional) _macOS_ - Message to display above input
boxes.
* `callback` Function (optional)
* `filePaths` String[] - An array of file paths chosen by the user
@ -147,6 +139,14 @@ will be passed via `callback(filename)`
others as command links in the dialog. This can make the dialog appear in
the style of modern Windows apps. If you don't like this behavior, you can
set `noLink` to `true`.
* `normalizeAccessKeys` Boolean (optional) - Normalize the keyboard access keys
across platforms. Default is `false`. Enabling this assumes `&` is used in
the button labels for the placement of the keyboard shortcut access key
and labels will be converted so they work correctly on each platform, `&`
characters are removed on macOS, converted to `_` on Linux, and left
untouched on Windows. For example, a button label of `Vie&w` will be
converted to `Vie_w` on Linux and `View` on macOS and can be selected
via `Alt-W` on Windows and Linux.
* `callback` Function (optional)
* `response` Number - The index of the button that was clicked
* `checkboxChecked` Boolean - The checked state of the checkbox if

18
docs/api/menu-item.md
View file

@ -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
to appropriate values for each platform.
The `label` and `accelerator` values are optional when using a `role` and will
default to appropriate values for each platform.
The `role` property can have following values:
@ -63,8 +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
@ -78,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
that will affect the MenuItem. All other options will be ignored.
When specifying a `role` on macOS, `label` and `accelerator` are the only
options that will affect the menu item. All other options will be ignored.
### Instance Properties

165
docs/api/menu.md
View file

@ -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
`role` property of `MenuItem`.
emulating default macOS menu behaviors. Usually you would just use the
[`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: 'redo'
},
{
type: 'separator'
},
{
role: 'cut'
},
{
role: 'copy'
},
{
role: 'paste'
},
{
role: 'pasteandmatchstyle'
},
{
role: 'delete'
},
{
role: 'selectall'
}
{role: 'undo'},
{role: 'redo'},
{type: 'separator'},
{role: 'cut'},
{role: 'copy'},
{role: 'paste'},
{role: 'pasteandmatchstyle'},
{role: 'delete'},
{role: 'selectall'}
]
},
{
label: 'View',
submenu: [
{
role: 'reload'
},
{
role: 'forcereload'
},
{
role: 'toggledevtools'
},
{
type: 'separator'
},
{
role: 'resetzoom'
},
{
role: 'zoomin'
},
{
role: 'zoomout'
},
{
type: 'separator'
},
{
role: 'togglefullscreen'
}
{role: 'reload'},
{role: 'forcereload'},
{role: 'toggledevtools'},
{type: 'separator'},
{role: 'resetzoom'},
{role: 'zoomin'},
{role: 'zoomout'},
{type: 'separator'},
{role: 'togglefullscreen'}
]
},
{
role: 'window',
submenu: [
{
role: 'minimize'
},
{
role: 'close'
}
{role: 'minimize'},
{role: 'close'}
]
},
{
@ -202,76 +162,37 @@ if (process.platform === 'darwin') {
template.unshift({
label: app.getName(),
submenu: [
{
role: 'about'
},
{
type: 'separator'
},
{
role: 'services',
submenu: []
},
{
type: 'separator'
},
{
role: 'hide'
},
{
role: 'hideothers'
},
{
role: 'unhide'
},
{
type: 'separator'
},
{
role: 'quit'
}
{role: 'about'},
{type: 'separator'},
{role: 'services', submenu: []},
{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: 'stopspeaking'
}
{role: 'startspeaking'},
{role: 'stopspeaking'}
]
}
)
// Window menu.
// Window menu
template[3].submenu = [
{
label: 'Close',
accelerator: 'CmdOrCtrl+W',
role: 'close'
},
{
label: 'Minimize',
accelerator: 'CmdOrCtrl+M',
role: 'minimize'
},
{
label: 'Zoom',
role: 'zoom'
},
{
type: 'separator'
},
{
label: 'Bring All to Front',
role: 'front'
}
{role: 'close'},
{role: 'minimize'},
{role: 'zoom'},
{type: 'separator'},
{role: 'front'}
]
}

18
docs/api/process.md
View file

@ -32,38 +32,38 @@ process.once('loaded', () => {
### `process.noAsar`
Setting this to `true` can disable the support for `asar` archives in Node's
built-in modules.
A `Boolean` that controls ASAR support inside your application. Setting this to `true`
will disable the support for `asar` archives in Node's built-in modules.
### `process.type`
Current process's type, can be `"browser"` (i.e. main process) or `"renderer"`.
A `String` representing the current process's type, can be `"browser"` (i.e. main process) or `"renderer"`.
### `process.versions.electron`
Electron's version string.
A `String` representing Electron's version string.
### `process.versions.chrome`
Chrome's version string.
A `String` representing Chrome's version string.
### `process.resourcesPath`
Path to the resources directory.
A `String` representing the path to the resources directory.
### `process.mas`
For Mac App Store build, this property is `true`, for other builds it is
A `Boolean`. For Mac App Store build, this property is `true`, for other builds it is
`undefined`.
### `process.windowsStore`
If the app is running as a Windows Store app (appx), this property is `true`,
A `Boolean`. If the app is running as a Windows Store app (appx), this property is `true`,
for otherwise it is `undefined`.
### `process.defaultApp`
When app is started by being passed as parameter to the default app, this
A `Boolean`. When app is started by being passed as parameter to the default app, this
property is `true` in the main process, otherwise it is `undefined`.
## Methods

30
docs/api/remote.md
View file

@ -141,6 +141,36 @@ The `remote` module has the following methods:
* `module` String
Returns `any` - The object returned by `require(module)` in the main process.
Modules specified by their relative path will resolve relative to the entrypoint
of the main process.
e.g.
```
project/
├── main
│   ├── foo.js
│   └── index.js
├── package.json
└── renderer
└── index.js
```
```js
// main process: main/index.js
const {app} = require('electron')
app.on('ready', () => { /* ... */ })
```
```js
// some relative module: main/foo.js
module.exports = 'bar'
```
```js
// renderer process: renderer/index.js
const foo = require('electron').remote.require('./foo') // bar
```
### `remote.getCurrentWindow()`

195
docs/api/sandbox-option.md Normal file
View file

@ -0,0 +1,195 @@
# `sandbox` Option
> Create a browser window with a renderer that can run inside Chromium OS sandbox. With this
option enabled, the renderer must communicate via IPC to the main process in order to access node APIs.
However, in order to enable the Chromium OS sandbox, electron must be run with the `--enable-sandbox`
command line argument.
One of the key security features of Chromium is that all blink rendering/JavaScript
code is executed within a sandbox. This sandbox uses OS-specific features to ensure
that exploits in the renderer process cannot harm the system.
In other words, when the sandbox is enabled, the renderers can only make changes
to the system by delegating tasks to the main process via IPC.
[Here's](https://www.chromium.org/developers/design-documents/sandbox) more
information about the sandbox.
Since a major feature in electron is the ability to run node.js in the
renderer process (making it easier to develop desktop applications using web
technologies), the sandbox is disabled by electron. This is because
most node.js APIs require system access. `require()` for example, is not
possible without file system permissions, which are not available in a sandboxed
environment.
Usually this is not a problem for desktop applications since the code is always
trusted, but it makes electron less secure than chromium for displaying
untrusted web content. For applications that require more security, the
`sandbox` flag will force electron to spawn a classic chromium renderer that is
compatible with the sandbox.
A sandboxed renderer doesn't have a node.js environment running and doesn't
expose node.js JavaScript APIs to client code. The only exception is the preload script,
which has access to a subset of the electron renderer API.
Another difference is that sandboxed renderers don't modify any of the default
JavaScript APIs. Consequently, some APIs such as `window.open` will work as they
do in chromium (i.e. they do not return a `BrowserWindowProxy`).
## Example
To create a sandboxed window, simply pass `sandbox: true` to `webPreferences`:
```js
let win
app.on('ready', () => {
win = new BrowserWindow({
webPreferences: {
sandbox: true
}
})
w.loadURL('http://google.com')
})
```
In the above code the `BrowserWindow` that was created has node.js disabled and can communicate
only via IPC. The use of this option stops electron from creating a node.js runtime in the renderer. Also,
within this new window `window.open` follows the native behaviour (by default electron creates a `BrowserWindow`
and returns a proxy to this via `window.open`).
It is important to note that this option alone won't enable the OS-enforced sandbox. To enable this feature, the
`--enable-sandbox` command-line argument must be passed to electron, which will
force `sandbox: true` for all `BrowserWindow` instances.
```js
let win
app.on('ready', () => {
// no need to pass `sandbox: true` since `--enable-sandbox` was enabled.
win = new BrowserWindow()
w.loadURL('http://google.com')
})
```
Note that it is not enough to call
`app.commandLine.appendSwitch('--enable-sandbox')`, as electron/node startup
code runs after it is possible to make changes to chromium sandbox settings. The
switch must be passed to electron on the command-line:
```
electron --enable-sandbox app.js
```
It is not possible to have the OS sandbox active only for some renderers, if
`--enable-sandbox` is enabled, normal electron windows cannot be created.
If you need to mix sandboxed and non-sandboxed renderers in one application,
simply omit the `--enable-sandbox` argument. Without this argument, windows
created with `sandbox: true` will still have node.js disabled and communicate
only via IPC, which by itself is already a gain from security POV.
## Preload
An app can make customizations to sandboxed renderers using a preload script.
Here's an example:
```js
let win
app.on('ready', () => {
win = new BrowserWindow({
webPreferences: {
sandbox: true,
preload: 'preload.js'
}
})
w.loadURL('http://google.com')
})
```
and preload.js:
```js
// This file is loaded whenever a javascript context is created. It runs in a
// private scope that can access a subset of electron renderer APIs. We must be
// careful to not leak any objects into the global scope!
const fs = require('fs')
const {ipcRenderer} = require('electron')
// read a configuration file using the `fs` module
const buf = fs.readFileSync('allowed-popup-urls.json')
const allowedUrls = JSON.parse(buf.toString('utf8'))
const defaultWindowOpen = window.open
function customWindowOpen (url, ...args) {
if (allowedUrls.indexOf(url) === -1) {
ipcRenderer.sendSync('blocked-popup-notification', location.origin, url)
return null
}
return defaultWindowOpen(url, ...args)
}
window.open = customWindowOpen
```
Important things to notice in the preload script:
- Even though the sandboxed renderer doesn't have node.js running, it still has
access to a limited node-like environment: `Buffer`, `process`, `setImmediate`
and `require` are available.
- The preload script can indirectly access all APIs from the main process through the
`remote` and `ipcRenderer` modules. This is how `fs` (used above) and other
modules are implemented: They are proxies to remote counterparts in the main
process.
- The preload script must be contained in a single script, but it is possible to have
complex preload code composed with multiple modules by using a tool like
browserify, as explained below. In fact, browserify is already used by
electron to provide a node-like environment to the preload script.
To create a browserify bundle and use it as a preload script, something like
the following should be used:
browserify preload/index.js \
-x electron \
-x fs \
--insert-global-vars=__filename,__dirname -o preload.js
The `-x` flag should be used with any required module that is already exposed in
the preload scope, and tells browserify to use the enclosing `require` function
for it. `--insert-global-vars` will ensure that `process`, `Buffer` and
`setImmediate` are also taken from the enclosing scope(normally browserify
injects code for those).
Currently the `require` function provided in the preload scope exposes the
following modules:
- `child_process`
- `electron` (crashReporter, remote and ipcRenderer)
- `fs`
- `os`
- `timers`
- `url`
More may be added as needed to expose more electron APIs in the sandbox, but any
module in the main process can already be used through
`electron.remote.require`.
## Status
Please use the `sandbox` option with care, as it is still an experimental
feature. We are still not aware of the security implications of exposing some
electron renderer APIs to the preload script, but here are some things to
consider before rendering untrusted content:
- A preload script can accidentaly leak privileged APIs to untrusted code.
- Some bug in V8 engine may allow malicious code to access the renderer preload
APIs, effectively granting full access to the system through the `remote`
module.
Since rendering untrusted content in electron is still uncharted territory,
the APIs exposed to the sandbox preload script should be considered more
unstable than the rest of electron APIs, and may have breaking changes to fix
security issues.
One planned enhancement that should greatly increase security is to block IPC
messages from sandboxed renderers by default, allowing the main process to
explicitly define a set of messages the renderer is allowed to send.

4
docs/api/touch-bar-scrubber.md
View file

@ -9,9 +9,9 @@ Process: [Main](../tutorial/quick-start.md#main-process)
* `options` Object
* `items` [ScrubberItem[]](structures/scrubber-item.md) - An array of items to place in this scrubber
* `select` Function - Called when the user taps an item that was not the last tapped item
* `selectedIndex` - The index of the item the user selected
* `selectedIndex` Integer - The index of the item the user selected
* `highlight` Function - Called when the user taps any item
* `highlightedIndex` - The index of the item the user touched
* `highlightedIndex` Integer - The index of the item the user touched
* `selectedStyle` String - Selected item style. Defaults to `null`.
* `overlayStyle` String - Selected overlay item style. Defaults to `null`.
* `showArrowButtons` Boolean - Defaults to `false`.

23
docs/api/touch-bar-segmented-control.md
View file

@ -8,18 +8,23 @@ Process: [Main](../tutorial/quick-start.md#main-process)
* `options` Object
* `segmentStyle` String - (Optional) Style of the segments:
* `automatic` - Default
* `rounded`
* `textured-rounded`
* `round-rect`
* `textured-square`
* `capsule`
* `small-square`
* `separated`
* `automatic` - Default. The appearance of the segmented control is
automatically determined based on the type of window in which the control
is displayed and the position within the window.
* `rounded` - The control is displayed using the rounded style.
* `textured-rounded` - The control is displayed using the textured rounded
style.
* `round-rect` - The control is displayed using the round rect style.
* `textured-square` - The control is displayed using the textured square
style.
* `capsule` - The control is displayed using the capsule style
* `small-square` - The control is displayed using the small square style.
* `separated` - The segments in the control are displayed very close to each
other but not touching.
* `segments` [SegmentedControlSegment[]](structures/segmented-control-segment.md) - An array of segments to place in this control
* `selectedIndex` Integer (Optional) - The index of the currently selected segment, will update automatically with user interaction
* `change` Function - Called when the user selects a new segment
* `selectedIndex` - The index of the segment the user selected
* `selectedIndex` Integer - The index of the segment the user selected
### Instance Properties

3
docs/api/web-contents.md
View file

@ -336,6 +336,7 @@ Returns:
* `activeMatchOrdinal` Integer - Position of the active match.
* `matches` Integer - Number of Matches.
* `selectionArea` Object - Coordinates of first match region.
* `finalUpdate` Boolean
Emitted when a result is available for
[`webContents.findInPage`] request.
@ -1247,7 +1248,7 @@ one through the `'paint'` event.
#### `contents.getWebRTCIPHandlingPolicy()`
* Returns `String` - Returns the WebRTC IP Handling Policy.
Returns `String` - Returns the WebRTC IP Handling Policy.
#### `contents.setWebRTCIPHandlingPolicy(policy)`

3
docs/api/web-frame.md
View file

@ -136,6 +136,9 @@ Inserts `text` to the focused element.
* `callback` Function (optional) - Called after script has been executed.
* `result` Any
Returns `Promise` - A promise that resolves with the result of the executed code
or is rejected if the result of the code is a rejected promise.
Evaluates `code` in page.
In the browser window some HTML APIs like `requestFullScreen` can only be

1
docs/api/webview-tag.md
View file

@ -749,6 +749,7 @@ Returns:
* `activeMatchOrdinal` Integer - Position of the active match.
* `matches` Integer - Number of Matches.
* `selectionArea` Object - Coordinates of first match region.
* `finalUpdate` Boolean
Fired when a result is available for
[`webview.findInPage`](webview-tag.md#webviewtagfindinpage) request.

14
docs/development/chromium-development.md Normal file
View file

@ -0,0 +1,14 @@
# Chromium Development
> A collection of resources for learning about Chromium and tracking its development
- [chromiumdev](https://chromiumdev-slack.herokuapp.com) on Slack
- [@ChromiumDev](https://twitter.com/ChromiumDev) on Twitter
- [@googlechrome](https://twitter.com/googlechrome) on Twitter
- [Blog](https://blog.chromium.org)
- [Code Search](https://cs.chromium.org/)
- [Source Code](https://cs.chromium.org/chromium/src/)
- [Development Calendar and Release Info](https://www.chromium.org/developers/calendar)
- [Discussion Groups](http://www.chromium.org/developers/discussion-groups)
See also [V8 Development](v8-development.md)

40
docs/development/upgrading-chrome.md
View file

@ -45,6 +45,46 @@ Chrome/Node API changes.
- 64-bit Linux
- ARM Linux
## Verify ffmpeg Support
Electron ships with a version of `ffmpeg` that includes proprietary codecs by
default. A version without these codecs is built and distributed with each
release as well. Each Chrome upgrade should verify that switching this version is
still supported.
You can verify Electron's support for multiple `ffmpeg` builds by loading the
following page. It should work with the default `ffmpeg` library distributed
with Electron and not work with the `ffmpeg` library built without proprietary
codecs.
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Proprietary Codec Check</title>
</head>
<body>
<p>Checking if Electron is using proprietary codecs by loading video from http://www.quirksmode.org/html5/videos/big_buck_bunny.mp4</p>
<p id="outcome"></p>
<video style="display:none" src="http://www.quirksmode.org/html5/videos/big_buck_bunny.mp4" autoplay></video>
<script>
const video = document.querySelector('video')
video.addEventListener('error', ({target}) => {
if (target.error.code === target.error.MEDIA_ERR_SRC_NOT_SUPPORTED) {
document.querySelector('#outcome').textContent = 'Not using proprietary codecs, video emitted source not supported error event.'
} else {
document.querySelector('#outcome').textContent = `Unexpected error: ${target.error.code}`
}
})
video.addEventListener('playing', () => {
document.querySelector('#outcome').textContent = 'Using proprietary codecs, video started playing.'
})
</script>
</body>
</html>
```
## Links
- [Chrome Release Schedule](https://www.chromium.org/developers/calendar)

11
docs/development/v8-development.md Normal file
View file

@ -0,0 +1,11 @@
# V8 Development
> A collection of resources for learning and using V8
* [V8 Tracing](https://github.com/v8/v8/wiki/Tracing-V8)
* [V8 Profiler](https://github.com/v8/v8/wiki/V8-Profiler) - Profiler combinations which are useful for profiling: `--prof`, `--trace-ic`, `--trace-opt`, `--trace-deopt`, `--print-bytecode`, `--print-opt-code`
* [V8 Interpreter Design](https://docs.google.com/document/d/11T2CRex9hXxoJwbYqVQ32yIPMh0uouUZLdyrtmMoL44/edit?ts=56f27d9d#heading=h.6jz9dj3bnr8t)
* [Optimizing compiler](https://github.com/v8/v8/wiki/TurboFan)
* [V8 GDB Debugging](https://github.com/v8/v8/wiki/GDB-JIT-Interface)
See also [Chromium Development](chromium-development.md)

64
docs/tutorial/electron-versioning.md
View file

@ -1,21 +1,55 @@
# Electron Versioning
If you are a seasoned Node developer, you are surely aware of `semver` - and
might be used to giving your dependency management systems only rough guidelines
rather than fixed version numbers. Due to the hard dependency on Node and
Chromium, Electron is in a slightly more difficult position and does not follow
semver. You should therefore always reference a specific version of Electron.
If you've been using Node and npm for a while, you are probably aware of [Semantic Versioning], or SemVer for short. It's a convention for specifying version numbers for software that helps communicate intentions to the users of your software.
Version numbers are bumped using the following rules:
## Overview of Semantic Versioning
* Major: For breaking changes in Electron's API - if you upgrade from `0.37.0`
to `1.0.0`, you will have to update your app.
* Minor: For major Chrome and minor Node upgrades; or significant Electron
changes - if you upgrade from `1.0.0` to `1.1.0`, your app is supposed to
Semantic versions are always made up of three numbers:
```
major.minor.patch
```
Semantic version numbers are bumped (incremented) using the following rules:
* **Major** is for changes that break backwards compatibility.
* **Minor** is for new features that don't break backwards compatibility.
* **Patch** is for bug fixes and other minor changes.
A simple mnemonic for remembering this scheme is as follows:
```
breaking.feature.fix
```
## Electron Versioning
Due to its dependency on Node and Chromium, it is not possible for the Electron
project to adhere to a SemVer policy. **You should therefore always
reference a specific version of Electron.**
Electron version numbers are bumped using the following rules:
* **Major** is for breaking changes in Electron's API. If you upgrade from `0.37.0`
to `1.0.0`, you will have to make changes to your app.
* **Minor** is for major Chrome and minor Node upgrades, or significant Electron
changes. If you upgrade from `1.5.0` to `1.6.0`, your app is supposed to
still work, but you might have to work around small changes.
* Patch: For new features and bug fixes - if you upgrade from `1.0.0` to
`1.0.1`, your app will continue to work as-is.
* **Patch** is for new features and bug fixes. If you upgrade from `1.6.2` to
`1.6.3`, your app will continue to work as-is.
If you are using `electron` or `electron-prebuilt`, we recommend that you set a fixed version
number (`1.1.0` instead of `^1.1.0`) to ensure that all upgrades of Electron are
a manual operation made by you, the developer.
We recommend that you set a fixed version when installing Electron from npm:
```sh
npm install electron --save-exact --save-dev
```
The `--save-exact` flag will add `electron` to your `package.json` file without
using a `^` or `~`, e.g. `1.6.2` instead of `^1.6.2`. This practice ensures that
all upgrades of Electron are a manual operation made by you, the developer.
Alternatively, you can use the `~` prefix in your SemVer range, like `~1.6.2`.
This will lock your major and minor version, but allow new patch versions to
be installed.
[Semantic Versioning]: http://semver.org