Merge remote-tracking branch 'ups/master'

This commit is contained in:
renaesop 2017-05-09 09:44:24 +08:00
commit cba5e96496
485 changed files with 17051 additions and 3798 deletions

View file

@ -125,8 +125,10 @@ Returns:
* `event` Event
* `hasVisibleWindows` Boolean
Emitted when the application is activated, which usually happens when the user
clicks on the application's dock icon.
Emitted when the application is activated. Various actions can trigger
this event, such as launching the application for the first time, attempting
to re-launch the application when it's already running, or clicking on the
application's dock or taskbar icon.
### Event: 'continue-activity' _macOS_
@ -401,6 +403,28 @@ You can request the following paths by the name:
* `videos` Directory for a user's videos.
* `pepperFlashSystemPlugin` Full path to the system version of the Pepper Flash plugin.
### `app.getFileIcon(path[, options], callback)`
* `path` String
* `options` Object (optional)
* `size` String
* `small` - 16x16
* `normal` - 32x32
* `large` - 48x48 on _Linux_, 32x32 on _Windows_, unsupported on _macOS_.
* `callback` Function
* `error` Error
* `icon` [NativeImage](native-image.md)
Fetches a path's associated icon.
On _Windows_, there a 2 kinds of icons:
- Icons associated with certain file extensions, like `.mp3`, `.png`, etc.
- Icons inside the file itself, like `.exe`, `.dll`, `.ico`.
On _Linux_ and _macOS_, icons depend on the application associated with file
mime type.
### `app.setPath(name, path)`
* `name` String
@ -736,6 +760,10 @@ Disables hardware acceleration for current app.
This method can only be called before app is ready.
### `app.getAppMemoryInfo()`
Returns [ProcessMemoryInfo[]](structures/process-memory-info.md): Array of `ProcessMemoryInfo` objects that correspond to memory usage statistics of all the processes associated with the app.
### `app.setBadgeCount(count)` _Linux_ _macOS_
* `count` Integer
@ -796,11 +824,11 @@ Returns `Object`:
`app.getLoginItemStatus().wasOpenedAsHidden` should be checked when the app
is opened to know the current value. This setting is only supported on
macOS.
* `path` String (optional) _Windows_ - The executable to launch at login.
Defaults to `process.execPath`.
* `args` String[] (optional) _Windows_ - The command-line arguments to pass to
the executable. Defaults to an empty array. Take care to wrap paths in
quotes.
* `path` String (optional) _Windows_ - The executable to launch at login.
Defaults to `process.execPath`.
* `args` String[] (optional) _Windows_ - The command-line arguments to pass to
the executable. Defaults to an empty array. Take care to wrap paths in
quotes.
Set the app's login item settings.

74
docs/api/browser-view.md Normal file
View file

@ -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.

View file

@ -35,9 +35,9 @@ without visual flash, there are two solutions for different situations.
### Using `ready-to-show` event
While loading the page, the `ready-to-show` event will be emitted when renderer
process has done drawing for the first time, showing window after this event
will have no visual flash:
While loading the page, the `ready-to-show` event will be emitted when the renderer
process has rendered the page for the first time if the window has not been shown yet. Showing
the window after this event will have no visual flash:
```javascript
const {BrowserWindow} = require('electron')
@ -47,7 +47,7 @@ win.once('ready-to-show', () => {
})
```
This is event is usually emitted after the `did-finish-load` event, but for
This event is usually emitted after the `did-finish-load` event, but for
pages with many remote resources, it may be emitted before the `did-finish-load`
event.
@ -211,10 +211,16 @@ 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
is `true`.
* `nodeIntegrationInWorker` Boolean (optional) - Whether node integration is
enabled in web workers. Default is `false`. More about this can be found
in [Multithreading](../tutorial/multithreading.md).
* `preload` String (optional) - Specifies a script that will be loaded before other
scripts run in the page. This script will always have access to node APIs
no matter whether node integration is turned on or off. The value should
@ -222,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
@ -256,12 +269,12 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
macOS. Default is `false`.
* `blinkFeatures` String (optional) - A list of feature strings separated by `,`, like
`CSSVariables,KeyboardEventKey` to enable. The full list of supported feature
strings can be found in the [RuntimeEnabledFeatures.in][blink-feature-string]
strings can be found in the [RuntimeEnabledFeatures.json5][blink-feature-string]
file.
* `disableBlinkFeatures` String (optional) - A list of feature strings separated by `,`,
like `CSSVariables,KeyboardEventKey` to disable. The full list of supported
feature strings can be found in the
[RuntimeEnabledFeatures.in][blink-feature-string] file.
[RuntimeEnabledFeatures.json5][blink-feature-string] file.
* `defaultFontFamily` Object (optional) - Sets the default font for the font-family.
* `standard` String (optional) - Defaults to `Times New Roman`.
* `serif` String (optional) - Defaults to `Times New Roman`.
@ -279,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
@ -364,6 +376,11 @@ window.onbeforeunload = (e) => {
Emitted when the window is closed. After you have received this event you should
remove the reference to the window and avoid using it any more.
#### Event: 'session-end' _Windows_
Emitted when window session is going to end due to force shutdown or machine restart
or session log off.
#### Event: 'unresponsive'
Emitted when the web page becomes unresponsive.
@ -390,7 +407,7 @@ Emitted when the window is hidden.
#### Event: 'ready-to-show'
Emitted when the web page has been rendered and window can be displayed without
Emitted when the web page has been rendered (while not being shown) and window can be displayed without
a visual flash.
#### Event: 'maximize'
@ -486,6 +503,14 @@ Returns:
Emitted on 3-finger swipe. Possible directions are `up`, `right`, `down`, `left`.
#### Event: 'sheet-begin' _macOS_
Emitted when the window opens a sheet.
#### Event: 'sheet-end' _macOS_
Emitted when the window has closed a sheet.
### Static Methods
The `BrowserWindow` class has the following static methods:
@ -632,7 +657,8 @@ Returns `Boolean` - Whether current window is a modal window.
#### `win.maximize()`
Maximizes the window.
Maximizes the window. This will also show (but not focus) the window if it
isn't being displayed already.
#### `win.unmaximize()`
@ -669,10 +695,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
@ -853,7 +877,7 @@ On Linux always returns `true`.
[macOS docs][window-levels] for more details.
* `relativeLevel` Integer (optional) _macOS_ - The number of layers higher to set
this window relative to the given `level`. The default is `0`. Note that Apple
discourages setting levels higher than 1 above `screen-saver`.
discourages setting levels higher than 1 above `screen-saver`.
Sets whether the window should show always on top of other windows. After
setting this, the window is still a normal window, not a toolbox window which
@ -1004,6 +1028,7 @@ Same as `webContents.capturePage([rect, ]callback)`.
* `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.
Same as `webContents.loadURL(url[, options])`.
@ -1266,7 +1291,25 @@ Controls whether to hide cursor when typing.
Adds a vibrancy effect to the browser window. Passing `null` or an empty string
will remove the vibrancy effect on the window.
[blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.in
#### `win.setTouchBar(touchBar)` _macOS_ _Experimental_
* `touchBar` TouchBar
Sets the touchBar layout for the current window. Specifying `null` or
`undefined` clears the touch bar. This method only has an effect if the
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
[window-levels]: https://developer.apple.com/reference/appkit/nswindow/1664726-window_levels

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`.

View file

@ -103,7 +103,7 @@ clipboard.
```js
clipboard.write({
text: 'http://electron.atom.io',
text: 'https://electron.atom.io',
bookmark: 'Electron Homepage'
})
```
@ -133,24 +133,29 @@ Clears the clipboard content.
Returns `String[]` - An array of supported formats for the clipboard `type`.
### `clipboard.has(data[, type])` _Experimental_
### `clipboard.has(format[, type])` _Experimental_
* `data` String
* `format` String
* `type` String (optional)
Returns `Boolean` - Whether the clipboard supports the format of specified `data`.
Returns `Boolean` - Whether the clipboard supports the specified `format`.
```javascript
const {clipboard} = require('electron')
console.log(clipboard.has('<p>selection</p>'))
```
### `clipboard.read(data[, type])` _Experimental_
### `clipboard.read(format)` _Experimental_
* `data` String
* `type` String (optional)
* `format` String
Returns `String` - Reads `data` from the clipboard.
Returns `String` - Reads `format` type from the clipboard.
### `clipboard.readBuffer(format)` _Experimental_
* `format` String
Returns `Buffer` - Reads `format` type from the clipboard.
### `clipboard.write(data[, type])`

View file

@ -104,3 +104,9 @@ on complete.
Removes the cookies matching `url` and `name`, `callback` will called with
`callback()` on complete.
#### `cookies.flushStore(callback)`
* `callback` Function
Writes any unwritten cookies data to disk.

View file

@ -40,18 +40,18 @@ 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) _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
report. Only string properties are sent correctly, Nested objects are not
report. Only string properties are sent correctly. Nested objects are not
supported.
You are required to call this method before using any other `crashReporter` APIs
and in each process (main/renderer) from which you want to collect crash reports.
You can pass different options to `crashReporter.start` when calling from different processes.
**Note** Child processes created via the `child_process` module will not have access to the Electron modules.
**Note** Child processes created via the `child_process` module will not have access to the Electron modules.
Therefore, to collect crash reports from them, use `process.crashReporter.start` instead. Pass the same options as above
along with an additional one called `crashesDirectory` that should point to a directory to store the crash
reports temporarily. You can test this out by calling `process.crash()` to crash the child process.
@ -60,6 +60,10 @@ reports temporarily. You can test this out by calling `process.crash()` to crash
This will start the process that will monitor and send the crash reports. Replace `submitURL`, `productName`
and `crashesDirectory` with appropriate values.
**Note:** If you need send additional/updated `extra` parameters after your
first call `start` you can call `setExtraParameter` on macOS or call `start`
again with the new/updated `extra` parameters on Linux and Windows.
```js
const args = [
`--reporter-url=${submitURL}`,
@ -95,14 +99,14 @@ Returns [`CrashReport[]`](structures/crash-report.md):
Returns all uploaded crash reports. Each report contains the date and uploaded
ID.
### `crashReporter.getUploadToServer()` _macOS_
### `crashReporter.getUploadToServer()` _Linux_ _macOS_
Returns `Boolean` - Whether reports should be submitted to the server. Set through
the `start` method or `setUploadToServer`.
**Note:** This API can only be called from the main process.
### `crashReporter.setUploadToServer(uploadToServer)` _macOS_
### `crashReporter.setUploadToServer(uploadToServer)` _Linux_ _macOS_
* `uploadToServer` Boolean _macOS_ - Whether reports should be submitted to the server
@ -111,6 +115,18 @@ called before `start` is called.
**Note:** This API can only be called from the main process.
### `crashReporter.setExtraParameter(key, value)` _macOS_
* `key` String - Parameter key.
* `value` String - Parameter value. Specifying `null` or `undefined` will
remove the key from the extra parameters.
Set an extra parameter to set be sent with the crash report. The values
specified here will be sent in addition to any values set via the `extra` option
when `start` was called. This API is only available on macOS, if you need to
add/update extra parameters on Linux and Windows after your first call to
`start` you can call `start` again with the updated `extra` options.
## Crash Report Payload
The crash reporter will send the following data to the `submitURL` as

View file

@ -60,8 +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 suggested size that the media source
thumbnail should be scaled to, defaults to `{width: 150, height: 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)

View file

@ -38,19 +38,16 @@ The `dialog` module has the following methods:
* `openDirectory` - Allow directories to be selected.
* `multiSelections` - Allow multiple paths to be selected.
* `showHiddenFiles` - Show hidden files in dialog.
* `createDirectory` _macOS_ - Allow creating new directories from dialog.
* `promptToCreate` _Windows_ - Prompt for creation if the file path entered
* `createDirectory` - Allow creating new directories from dialog. _macOS_
* `promptToCreate` - Prompt for creation if the file path entered
in the dialog does not exist. This does not actually create the file at
the path but allows non-existent paths to be returned that should be
created by the application.
* `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.
created by the application. _Windows_
* `noResolveAliases` - Disable the automatic alias (symlink) path
resolution. Selected aliases will now return the alias path instead of
their target path. _macOS_
* `message` String (optional) _macOS_ - Message to display above input
boxes.
* `callback` Function (optional)
* `filePaths` String[] - An array of file paths chosen by the user
@ -94,6 +91,11 @@ shown.
* `buttonLabel` String (optional) - Custom label for the confirmation button, when
left empty the default label will be used.
* `filters` [FileFilter[]](structures/file-filter.md) (optional)
* `message` String (optional) _macOS_ - Message to display above text fields.
* `nameFieldLabel` String (optional) _macOS_ - Custom label for the text
displayed in front of the filename text field.
* `showsTagField` Boolean (optional) _macOS_ - Show the tags input box,
defaults to `true`.
* `callback` Function (optional)
* `filename` String
@ -113,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
@ -122,19 +125,33 @@ will be passed via `callback(filename)`
* `title` String (optional) - Title of the message box, some platforms will not show it.
* `message` String - Content of the message box.
* `detail` String (optional) - Extra information of the message.
* `checkboxLabel` String (optional) - If provided, the message box will
include a checkbox with the given label. The checkbox state can be
inspected only when using `callback`.
* `checkboxChecked` Boolean (optional) - Initial checked state of the
checkbox. `false` by default.
* `icon` [NativeImage](native-image.md) (optional)
* `cancelId` Integer (optional) - The value will be returned when user cancels the dialog
instead of clicking the buttons of the dialog. By default it is the index
of the buttons that have "cancel" or "no" as label, or 0 if there is no such
buttons. On macOS and Windows the index of the "Cancel" button will always
be used as `cancelId` even if it is specified.
* `cancelId` Integer (optional) - The index of the button to be used to cancel the dialog, via
the `Esc` key. By default this is assigned to the first button with "cancel" or "no" as the
label. If no such labeled buttons exist and this option is not set, `0` will be used as the
return value or callback response. This option is ignored on Windows.
* `noLink` Boolean (optional) - On Windows Electron will try to figure out which one of
the `buttons` are common buttons (like "Cancel" or "Yes"), and show the
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
`checkboxLabel` was set. Otherwise `false`.
Returns `Integer`, the index of the clicked button, if a callback is provided
it returns undefined.
@ -159,6 +176,26 @@ 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_ _Windows_
* `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
On macOS, this displays a modal dialog that shows a message and certificate
information, and gives the user the option of trusting/importing the
certificate. If you provide a `browserWindow` argument the dialog will be
attached to the parent window, making it modal.
On Windows the options are more limited, due to the Win32 APIs used:
- The `message` argument is not used, as the OS provides its own confirmation
dialog.
- The `browserWindow` argument is ignored since it is not possible to make
this confirmation dialog modal.
## Sheets
On macOS, dialogs are presented as sheets attached to a window if you provide

View file

@ -100,6 +100,8 @@ Returns `Boolean` - Whether the download is paused.
Resumes the download that has been paused.
**Note:** To enable resumable downloads the server you are downloading from must support range requests and provide both `Last-Modified` and `ETag` header values. Otherwise `resume()` will dismiss previously received bytes and restart the download from the beginning.
#### `downloadItem.canResume()`
Resumes `Boolean` - Whether the download can resume.

View file

@ -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:

View file

@ -16,8 +16,8 @@ It is also possible to send messages from the main process to the renderer
process, see [webContents.send][web-contents-send] for more information.
* When sending a message, the event name is the `channel`.
* To reply a synchronous message, you need to set `event.returnValue`.
* To send an asynchronous back to the sender, you can use
* To reply to a synchronous message, you need to set `event.returnValue`.
* To send an asynchronous message back to the sender, you can use
`event.sender.send(...)`.
An example of sending and handling messages between the render and main

View file

@ -8,132 +8,135 @@ values are listed below:
| Language Code | Language Name |
|---------------|---------------|
| af | Afrikaans |
| an | Aragonese |
| ar-AE | Arabic (U.A.E.) |
| ar-IQ | Arabic (Iraq) |
| ar | Arabic (Standard) |
| ar-BH | Arabic (Bahrain) |
| ar-DZ | Arabic (Algeria) |
| ar-EG | Arabic (Egypt) |
| ar-JO | Arabic (Jordan) |
| ar-KW | Arabic (Kuwait) |
| ar-LB | Arabic (Lebanon) |
| ar-LY | Arabic (Libya) |
| ar-MA | Arabic (Morocco) |
| ar-OM | Arabic (Oman) |
| ar-QA | Arabic (Qatar) |
| ar-SA | Arabic (Saudi Arabia) |
| ar-SY | Arabic (Syria) |
| ar-TN | Arabic (Tunisia) |
| ar-YE | Arabic (Yemen) |
| as | Assamese |
| ast | Asturian |
| am | Amharic |
| ar | Arabic |
| az | Azerbaijani |
| be | Belarusian |
| bg | Bulgarian |
| bg | Bulgarian |
| bh | Bihari |
| bn | Bengali |
| br | Breton |
| bs | Bosnian |
| ca | Catalan |
| ce | Chechen |
| ch | Chamorro |
| co | Corsican |
| cr | Cree |
| cs | Czech |
| cv | Chuvash |
| cy | Welsh |
| da | Danish |
| de | German (Standard) |
| de | German |
| de-AT | German (Austria) |
| de-CH | German (Switzerland) |
| de-DE | German (Germany) |
| de-LI | German (Liechtenstein) |
| de-LU | German (Luxembourg) |
| el | Greek |
| en-AU | English (Australia) |
| en-BZ | English (Belize) |
| en | English |
| en-AU | English (Australia) |
| en-CA | English (Canada) |
| en-GB | English (United Kingdom) |
| en-IE | English (Ireland) |
| en-JM | English (Jamaica) |
| en-GB | English (UK) |
| en-NZ | English (New Zealand) |
| en-PH | English (Philippines) |
| en-TT | English (Trinidad & Tobago) |
| en-US | English (United States) |
| en-US | English (US) |
| en-ZA | English (South Africa) |
| en-ZW | English (Zimbabwe) |
| eo | Esperanto |
| es | Spanish |
| es-419 | Spanish (Latin America) |
| et | Estonian |
| eu | Basque |
| fa | Persian |
| fa | Farsi |
| fa-IR | Persian/Iran |
| fi | Finnish |
| fj | Fijian |
| fo | Faeroese |
| fil | Filipino |
| fo | Faroese |
| fr | French |
| fr-CA | French (Canada) |
| fr-CH | French (Switzerland) |
| fr-FR | French (France) |
| fr-LU | French (Luxembourg) |
| fr-MC | French (Monaco) |
| fr | French (Standard) |
| fr-BE | French (Belgium) |
| fr-CA | French (Canada) |
| fur | Friulian |
| fy | Frisian |
| ga | Irish |
| gd-IE | Gaelic (Irish) |
| gd | Gaelic (Scots) |
| gl | Galacian |
| gu | Gujurati |
| gd | Scots Gaelic |
| gl | Galician |
| gn | Guarani |
| gu | Gujarati |
| ha | Hausa |
| haw | Hawaiian |
| he | Hebrew |
| hi | Hindi |
| hr | Croatian |
| ht | Haitian |
| hu | Hungarian |
| hy | Armenian |
| ia | Interlingua |
| id | Indonesian |
| is | Icelandic |
| it | Italian |
| it-CH | Italian (Switzerland) |
| it | Italian (Standard) |
| iu | Inuktitut |
| it-IT | Italian (Italy) |
| ja | Japanese |
| jw | Javanese |
| ka | Georgian |
| kk | Kazakh |
| km | Khmer |
| km | Cambodian |
| kn | Kannada |
| ko | Korean |
| ko-KP | Korean (North Korea) |
| ko-KR | Korean (South Korea) |
| ks | Kashmiri |
| ky | Kirghiz |
| ku | Kurdish |
| ky | Kyrgyz |
| la | Latin |
| lb | Luxembourgish |
| ln | Lingala |
| lo | Laothian |
| lt | Lithuanian |
| lv | Latvian |
| mi | Maori |
| mk | FYRO Macedonian |
| mk | Macedonian |
| ml | Malayalam |
| mn | Mongolian |
| mo | Moldavian |
| mr | Marathi |
| ms | Malay |
| mt | Maltese |
| my | Burmese |
| nb | Norwegian (Bokmal) |
| ne | Nepali |
| ng | Ndonga |
| nl | Dutch (Standard) |
| nl-BE | Dutch (Belgian) |
| nl | Dutch |
| nn | Norwegian (Nynorsk) |
| no | Norwegian |
| nv | Navajo |
| oc | Occitan |
| om | Oromo |
| or | Oriya |
| pa | Punjabi |
| pl | Polish |
| ps | Pashto |
| pt | Portuguese |
| pt-BR | Portuguese (Brazil) |
| pt-PT | Portuguese (Portugal) |
| qu | Quechua |
| rm | Romansh |
| ro | Romanian |
| ru | Russian |
| sd | Sindhi |
| sh | Serbo-Croatian |
| si | Sinhalese |
| sk | Slovak |
| sl | Slovenian |
| sn | Shona |
| so | Somali |
| sq | Albanian |
| tlh | Klingon |
| zh-TW | Chinese (Taiwan) |
| sr | Serbian |
| st | Sesotho |
| su | Sundanese |
| sv | Swedish |
| sw | Swahili |
| ta | Tamil |
| te | Telugu |
| tg | Tajik |
| th | Thai |
| ti | Tigrinya |
| tk | Turkmen |
| to | Tonga |
| tr | Turkish |
| tt | Tatar |
| tw | Twi |
| ug | Uighur |
| uk | Ukrainian |
| ur | Urdu |
| uz | Uzbek |
| vi | Vietnamese |
| xh | Xhosa |
| yi | Yiddish |
| yo | Yoruba |
| zh | Chinese |
| zh-CN | Chinese (PRC) |
| zh-HK | Chinese (Hong Kong) |
| zh-SG | Chinese (Singapore) |
| zh-CN | Chinese (Simplified) |
| zh-TW | Chinese (Traditional) |
| zu | Zulu |

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 available 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
@ -114,4 +120,4 @@ A String representing the menu items visible label
#### `menuItem.click`
A Function that is fired when the MenuItem recieves a click event
A Function that is fired when the MenuItem receives a click event

View file

@ -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.
@ -25,13 +28,17 @@ will be set as each window's top menu.
Returns `Menu` - The application menu, if set, or `null`, if not set.
**Note:** The returned `Menu` instance doesn't support dynamic addition or
removal of menu items. [Instance properties](#instance-properties) can still
be dynamically modified.
#### `Menu.sendActionToFirstResponder(action)` _macOS_
* `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.
@ -52,17 +59,28 @@ will become properties of the constructed menu items.
The `menu` object has the following instance methods:
#### `menu.popup([browserWindow, x, y, positioningItem])`
#### `menu.popup([browserWindow, options])`
* `browserWindow` BrowserWindow (optional) - Default is `BrowserWindow.getFocusedWindow()`.
* `x` Number (optional) - Default is the current mouse cursor position.
* `y` Number (**required** if `x` is used) - Default is the current mouse cursor position.
* `positioningItem` Number (optional) _macOS_ - The index of the menu item to
be positioned under the mouse cursor at the specified coordinates. Default is
-1.
* `browserWindow` BrowserWindow (optional) - Default is the focused window.
* `options` Object (optional)
* `x` Number (optional) - Default is the current mouse cursor position.
* `y` Number (**required** if `x` is used) - Default is the current mouse
cursor position.
* `async` Boolean (optional) - Set to `true` to have this method return
immediately called, `false` to return after the menu has been selected
or closed. Defaults to `false`.
* `positioningItem` Number (optional) _macOS_ - The index of the menu item to
be positioned under the mouse cursor at the specified coordinates. Default
is -1.
Pops up this menu as a context menu in the `browserWindow`.
#### `menu.closePopup([browserWindow])`
* `browserWindow` BrowserWindow (optional) - Default is the focused window.
Closes the context menu in the `browserWindow`.
#### `menu.append(menuItem)`
* `menuItem` MenuItem
@ -104,76 +122,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'}
]
},
{
@ -181,7 +159,7 @@ const template = [
submenu: [
{
label: 'Learn More',
click () { require('electron').shell.openExternal('http://electron.atom.io') }
click () { require('electron').shell.openExternal('https://electron.atom.io') }
}
]
}
@ -191,76 +169,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'}
]
}
@ -302,7 +241,7 @@ Linux. Here are some notes on making your app's menu more native-like.
On macOS there are many system-defined standard menus, like the `Services` and
`Windows` menus. To make your menu a standard menu, you should set your menu's
`role` to one of following and Electron will recognize them and make them
`role` to one of the following and Electron will recognize them and make them
become standard menus:
* `window`

View file

@ -165,7 +165,10 @@ Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer
The following methods are available on instances of the `NativeImage` class:
#### `image.toPNG()`
#### `image.toPNG([options])`
* `options` Object (optional)
* `scaleFactor` Double (optional) - Defaults to 1.0.
Returns `Buffer` - A [Buffer][buffer] that contains the image's `PNG` encoded data.
@ -175,16 +178,25 @@ Returns `Buffer` - A [Buffer][buffer] that contains the image's `PNG` encoded da
Returns `Buffer` - A [Buffer][buffer] that contains the image's `JPEG` encoded data.
#### `image.toBitmap()`
#### `image.toBitmap([options])`
* `options` Object (optional)
* `scaleFactor` Double (optional) - Defaults to 1.0.
Returns `Buffer` - A [Buffer][buffer] that contains a copy of the image's raw bitmap pixel
data.
#### `image.toDataURL()`
#### `image.toDataURL([options])`
* `options` Object (optional)
* `scaleFactor` Double (optional) - Defaults to 1.0.
Returns `String` - The data URL of the image.
#### `image.getBitmap()`
#### `image.getBitmap([options])`
* `options` Object (optional)
* `scaleFactor` Double (optional) - Defaults to 1.0.
Returns `Buffer` - A [Buffer][buffer] that contains the image's raw bitmap pixel data.
@ -207,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)`
@ -224,19 +233,15 @@ 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.
#### `image.resize(options)`
* `options` Object
* `width` Integer (optional)
* `height` Integer (optional)
* `width` Integer (optional) - Defaults to the image's width.
* `height` Integer (optional) - Defaults to the image's height
* `quality` String (optional) - The desired quality of the resize image.
Possible values are `good`, `better` or `best`. The default is `best`.
These values express a desired quality/speed tradeoff. They are translated
@ -253,4 +258,20 @@ will be preserved in the resized image.
Returns `Float` - The image's aspect ratio.
#### `image.addRepresentation(options)`
* `options` Object
* `scaleFactor` Double - The scale factor to add the image representation for.
* `width` Integer (optional) - Defaults to 0. Required if a bitmap buffer
is specified as `buffer`.
* `height` Integer (optional) - Defaults to 0. Required if a bitmap buffer
is specified as `buffer`.
* `buffer` Buffer (optional) - The buffer containing the raw image data.
* `dataURL` String (optional) - The data URL containing either a base 64
encoded PNG or JPEG image.
Add an image representation for a specific scale factor. This can be used
to explicitly add different scale factor representations to an image. This
can be called on empty images.
[buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer

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
@ -116,3 +116,15 @@ Returns `Object`:
Returns an object giving memory usage statistics about the entire system. Note
that all statistics are reported in Kilobytes.
### `process.getCPUUsage()`
Returns:
* `CPUUsage` [CPUUsage](structures/cpu-usage.md)
### `process.getIOCounters()` _Windows_ _Linux_
Returns:
* `IOCounters` [IOCounters](structures/io-counters.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.

View file

@ -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.

View file

@ -98,7 +98,7 @@ The following methods are available on instances of `Session`:
* `callback` Function
* `size` Integer - Cache size used in bytes.
Returns the session's current cache size.
Callback is invoked with the session's current cache size.
#### `ses.clearCache(callback)`
@ -204,7 +204,7 @@ The `proxyBypassRules` is a comma separated list of rules described below:
* `url` URL
* `callback` Function
* `proxy` Object
* `proxy` String
Resolves the proxy information for `url`. The `callback` will be called with
`callback(proxy)` when the request is performed.
@ -250,15 +250,22 @@ the original network configuration.
#### `ses.setCertificateVerifyProc(proc)`
* `proc` Function
* `hostname` String
* `certificate` [Certificate](structures/certificate.md)
* `request` Object
* `hostname` String
* `certificate` [Certificate](structures/certificate.md)
* `error` String - Verification result from chromium.
* `callback` Function
* `isTrusted` Boolean - Determines if the certificate should be trusted
* `verificationResult` Integer - Value can be one of certificate error codes
from [here](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h).
Apart from the certificate error codes, the following special codes can be used.
* `0` - Indicates success and disables Certificate Transperancy verification.
* `-2` - Indicates failure.
* `-3` - Uses the verification result from chromium.
Sets the certificate verify proc for `session`, the `proc` will be called with
`proc(hostname, certificate, callback)` whenever a server certificate
verification is requested. Calling `callback(true)` accepts the certificate,
calling `callback(false)` rejects it.
`proc(request, callback)` whenever a server certificate
verification is requested. Calling `callback(0)` accepts the certificate,
calling `callback(-2)` rejects it.
Calling `setCertificateVerifyProc(null)` will revert back to default certificate
verify proc.
@ -267,15 +274,20 @@ verify proc.
const {BrowserWindow} = require('electron')
let win = new BrowserWindow()
win.webContents.session.setCertificateVerifyProc((hostname, cert, callback) => {
callback(hostname === 'github.com')
win.webContents.session.setCertificateVerifyProc((request, callback) => {
const {hostname} = request
if (hostname === 'github.com') {
callback(0)
} else {
callback(-2)
}
})
```
#### `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
@ -376,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')

View file

@ -0,0 +1,6 @@
# CPUUsage Object
* `percentCPUUsage` Number - Percentage of CPU used since the last call to getCPUUsage.
First call returns 0.
* `idleWakeupsPerSecond` Number - The number of average idle cpu wakeups per second
since the last call to getCPUUsage. First call returns 0.

View file

@ -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

View file

@ -0,0 +1,8 @@
# IOCounters Object
* `readOperationCount` Number - The number of I/O read operations.
* `writeOperationCount` Number - The number of I/O write operations.
* `otherOperationCount` Number - Then number of I/O other operations.
* `readTransferCount` Number - The number of I/O read transfers.
* `writeTransferCount` Number - The number of I/O write transfers.
* `otherTransferCount` Number - Then number of I/O other transfers.

View file

@ -0,0 +1,12 @@
# MemoryInfo Object
* `workingSetSize` 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.
* `privateBytes` Integer - The amount of memory not shared by other processes, such as
JS heap or HTML content.
* `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.

View file

@ -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

View file

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

View file

@ -0,0 +1,4 @@
# ProcessMemoryInfo Object
* `pid` Integer - Process id of the process.
* `memory` [MemoryInfo](memory-info.md) - Memory information of the process.

View file

@ -0,0 +1,4 @@
# ScrubberItem Object
* `label` String - (Optional) The text to appear in this item
* `icon` NativeImage - (Optional) The image to appear in this item

View file

@ -0,0 +1,5 @@
# SegmentedControlSegment Object
* `label` String - (Optional) The text to appear in this segment
* `icon` NativeImage - (Optional) The image to appear in this segment
* `enabled` Boolean - (Optional) Whether this segment is selectable. Default: true

View file

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

View file

@ -0,0 +1,34 @@
## Class: TouchBarButton
> Create a button in the touch bar for native macOS applications
Process: [Main](../tutorial/quick-start.md#main-process)
### `new TouchBarButton(options)` _Experimental_
* `options` Object
* `label` String (optional) - Button text.
* `backgroundColor` String (optional) - Button background color in hex format,
i.e `#ABCDEF`.
* `icon` [NativeImage](native-image.md) (optional) - Button icon.
* `iconPosition` String - Can be `left`, `right` or `overlay`.
* `click` Function (optional) - Function to call when the button is clicked.
### Instance Properties
The following properties are available on instances of `TouchBarButton`:
#### `touchBarButton.label`
A `String` representing the button's current text. Changing this value immediately updates the button
in the touch bar.
#### `touchBarButton.backgroundColor`
A `String` hex code representing the button's current background color. Changing this value immediately updates
the button in the touch bar.
#### `touchBarButton.icon`
A `NativeImage` representing the button's current icon. Changing this value immediately updates the button
in the touch bar.

View file

@ -0,0 +1,29 @@
## Class: TouchBarColorPicker
> Create a color picker in the touch bar for native macOS applications
Process: [Main](../tutorial/quick-start.md#main-process)
### `new TouchBarColorPicker(options)` _Experimental_
* `options` Object
* `availableColors` String[] (optional) - Array of hex color strings to
appear as possible colors to select.
* `selectedColor` String (optional) - The selected hex color in the picker,
i.e `#ABCDEF`.
* `change` Function (optional) - Function to call when a color is selected.
* `color` String - The color that the user selected from the picker
### Instance Properties
The following properties are available on instances of `TouchBarColorPicker`:
#### `touchBarColorPicker.availableColors`
A `String[]` array representing the color picker's available colors to select. Changing this value immediately
updates the color picker in the touch bar.
#### `touchBarColorPicker.selectedColor`
A `String` hex code representing the color picker's currently selected color. Changing this value immediately
updates the color picker in the touch bar.

View file

@ -0,0 +1,10 @@
## Class: TouchBarGroup
> Create a group in the touch bar for native macOS applications
Process: [Main](../tutorial/quick-start.md#main-process)
### `new TouchBarGroup(options)` _Experimental_
* `options` Object
* `items` [TouchBar](touch-bar.md) - Items to display as a group.

View file

@ -0,0 +1,25 @@
## Class: TouchBarLabel
> Create a label in the touch bar for native macOS applications
Process: [Main](../tutorial/quick-start.md#main-process)
### `new TouchBarLabel(options)` _Experimental_
* `options` Object
* `label` String (optional) - Text to display.
* `textColor` String (optional) - Hex color of text, i.e `#ABCDEF`.
### Instance Properties
The following properties are available on instances of `TouchBarLabel`:
#### `touchBarLabel.label`
A `String` representing the label's current text. Changing this value immediately updates the label in
the touch bar.
#### `touchBarLabel.textColor`
A `String` hex code representing the label's current text color. Changing this value immediately updates the
label in the touch bar.

View file

@ -0,0 +1,28 @@
## Class: TouchBarPopover
> Create a popover in the touch bar for native macOS applications
Process: [Main](../tutorial/quick-start.md#main-process)
### `new TouchBarPopover(options)` _Experimental_
* `options` Object
* `label` String (optional) - Popover button text.
* `icon` [NativeImage](native-image.md) (optional) - Popover button icon.
* `items` [TouchBar](touch-bar.md) (optional) - Items to display in the popover.
* `showCloseButton` Boolean (optional) - `true` to display a close button
on the left of the popover, `false` to not show it. Default is `true`.
### Instance Properties
The following properties are available on instances of `TouchBarPopover`:
#### `touchBarPopover.label`
A `String` representing the popover's current button text. Changing this value immediately updates the
popover in the touch bar.
#### `touchBarPopover.icon`
A `NativeImage` representing the popover's current button icon. Changing this value immediately updates the
popover in the touch bar.

View file

@ -0,0 +1,65 @@
## Class: TouchBarScrubber
> Create a scrubber (a scrollable selector)
Process: [Main](../tutorial/quick-start.md#main-process)
### `new TouchBarScrubber(options)` _Experimental_
* `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` Integer - The index of the item the user selected
* `highlight` Function - Called when the user taps any item
* `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`.
* `mode` String - Defaults to `free`.
* `continuous` Boolean - Defaults to `true`.
### Instance Properties
The following properties are available on instances of `TouchBarScrubber`:
#### `touchBarSegmentedControl.items`
A `ScrubberItem[]` array representing the items in this scrubber. Updating this value immediately
updates the control in the touch bar. Updating deep properties inside this array **does not update the touch bar**.
#### `touchBarSegmentedControl.selectedStyle`
A `String` representing the style that selected items in the scrubber should have. Updating this value immediately
updates the control in the touch bar. Possible values:
* `background` - Maps to `[NSScrubberSelectionStyle roundedBackgroundStyle]`
* `outline` - Maps to `[NSScrubberSelectionStyle outlineOverlayStyle]`
* `null` - Actually null, not a string, removes all styles
#### `touchBarSegmentedControl.overlayStyle`
A `String` representing the style that selected items in the scrubber should have. This style is overlayed on top
of the scrubber item instead of being placed behind it. Updating this value immediately updates the control in the
touch bar. Possible values:
* `background` - Maps to `[NSScrubberSelectionStyle roundedBackgroundStyle]`
* `outline` - Maps to `[NSScrubberSelectionStyle outlineOverlayStyle]`
* `null` - Actually null, not a string, removes all styles
#### `touchBarSegmentedControl.showArrowButtons`
A `Boolean` representing whether to show the left / right selection arrows in this scrubber. Updating this value
immediately updates the control in the touch bar.
#### `touchBarSegmentedControl.mode`
A `String` representing the mode of this scrubber. Updating this value immediately
updates the control in the touch bar. Possible values:
* `fixed` - Maps to `NSScrubberModeFixed`
* `free` - Maps to `NSScrubberModeFree`
#### `touchBarSegmentedControl.continuous`
A `Boolean` representing whether this scrubber is continuous or not. Updating this value immediately
updates the control in the touch bar.

View file

@ -0,0 +1,51 @@
## Class: TouchBarSegmentedControl
> Create a segmented control (a button group) where one button has a selected state
Process: [Main](../tutorial/quick-start.md#main-process)
### `new TouchBarSegmentedControl(options)` _Experimental_
* `options` Object
* `segmentStyle` String - (Optional) Style of the segments:
* `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.
* `mode` String - (Optional) The selection mode of the control:
* `single` - Default. One item selected at a time, selecting one deselects the previously selected item.
* `multiple` - Multiple items can be selected at a time.
* `buttons` - Make the segments act as buttons, each segment can be pressed and released but never marked as active.
* `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. When the mode is multiple it will be the last selected item.
* `change` Function - Called when the user selects a new segment
* `selectedIndex` Integer - The index of the segment the user selected.
* `isSelected` Boolean - Whether as a result of user selection the segment is selected or not.
### Instance Properties
The following properties are available on instances of `TouchBarSegmentedControl`:
#### `touchBarSegmentedControl.segmentStyle`
A `String` representing the controls current segment style. Updating this value immediately updates the control
in the touch bar.
#### `touchBarSegmentedControl.segments`
A `SegmentedControlSegment[]` array representing the segments in this control. Updating this value immediately
updates the control in the touch bar. Updating deep properties inside this array **does not update the touch bar**.
#### `touchBarSegmentedControl.selectedIndex`
An `Integer` representing the currently selected segment. Changing this value immediately updates the control
in the touch bar. User interaction with the touch bar will update this value automatically.

View file

@ -0,0 +1,39 @@
## Class: TouchBarSlider
> Create a slider in the touch bar for native macOS applications
Process: [Main](../tutorial/quick-start.md#main-process)
### `new TouchBarSlider(options)` _Experimental_
* `options` Object
* `label` String (optional) - Label text.
* `value` Integer (optional) - Selected value.
* `minValue` Integer (optional) - Minimum value.
* `maxValue` Integer (optional) - Maximum value.
* `change` Function (optional) - Function to call when the slider is changed.
* `newValue` Number - The value that the user selected on the Slider
### Instance Properties
The following properties are available on instances of `TouchBarSlider`:
#### `touchBarSlider.label`
A `String` representing the slider's current text. Changing this value immediately updates the slider
in the touch bar.
#### `touchBarSlider.value`
A `Number` representing the slider's current value. Changing this value immediately updates the slider
in the touch bar.
#### `touchBarSlider.minValue`
A `Number` representing the slider's current minimum value. Changing this value immediately updates the
slider in the touch bar.
#### `touchBarSlider.maxValue`
A `Number` representing the slider's current maximum value. Changing this value immediately updates the
slider in the touch bar.

View file

@ -0,0 +1,13 @@
## Class: TouchBarSpacer
> Create a spacer between two items in the touch bar for native macOS applications
Process: [Main](../tutorial/quick-start.md#main-process)
### `new TouchBarSpacer(options)` _Experimental_
* `options` Object
* `size` String (optional) - Size of spacer, possible values are:
* `small` - Small space between items.
* `large` - Large space between items.
* `flexible` - Take up all available space.

150
docs/api/touch-bar.md Normal file
View file

@ -0,0 +1,150 @@
## Class: TouchBar
> Create TouchBar layouts for native macOS applications
Process: [Main](../tutorial/quick-start.md#main-process)
### `new TouchBar(options)` _Experimental_
* `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.
**Note:** The TouchBar API is currently experimental and may change or be
removed in future Electron releases.
**Tip:** If you don't have a MacBook with Touch Bar, you can use
[Touch Bar Simulator](https://github.com/sindresorhus/touch-bar-simulator)
to test Touch Bar usage in your app.
### 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
and some labels.
```javascript
const {app, BrowserWindow, TouchBar} = require('electron')
const {TouchBarLabel, TouchBarButton, TouchBarSpacer} = TouchBar
let spinning = false
// Reel labels
const reel1 = new TouchBarLabel()
const reel2 = new TouchBarLabel()
const reel3 = new TouchBarLabel()
// Spin result label
const result = new TouchBarLabel()
// Spin button
const spin = new TouchBarButton({
label: '🎰 Spin',
backgroundColor: '#7851A9',
click: () => {
// Ignore clicks if already spinning
if (spinning) {
return
}
spinning = true
result.label = ''
let timeout = 10
const spinLength = 4 * 1000 // 4 seconds
const startTime = Date.now()
const spinReels = () => {
updateReels()
if ((Date.now() - startTime) >= spinLength) {
finishSpin()
} else {
// Slow down a bit on each spin
timeout *= 1.1
setTimeout(spinReels, timeout)
}
}
spinReels()
}
})
const getRandomValue = () => {
const values = ['🍒', '💎', '7⃣', '🍊', '🔔', '⭐', '🍇', '🍀']
return values[Math.floor(Math.random() * values.length)]
}
const updateReels = () => {
reel1.label = getRandomValue()
reel2.label = getRandomValue()
reel3.label = getRandomValue()
}
const finishSpin = () => {
const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size
if (uniqueValues === 1) {
// All 3 values are the same
result.label = '💰 Jackpot!'
result.textColor = '#FDFF00'
} else if (uniqueValues === 2) {
// 2 values are the same
result.label = '😍 Winner!'
result.textColor = '#FDFF00'
} else {
// No values are the same
result.label = '🙁 Spin Again'
result.textColor = null
}
spinning = false
}
const touchBar = new TouchBar([
spin,
new TouchBarSpacer({size: 'large'}),
reel1,
new TouchBarSpacer({size: 'small'}),
reel2,
new TouchBarSpacer({size: 'small'}),
reel3,
new TouchBarSpacer({size: 'large'}),
result
])
let window
app.once('ready', () => {
window = new BrowserWindow({
frame: false,
titleBarStyle: 'hidden-inset',
width: 200,
height: 200,
backgroundColor: '#000'
})
window.loadURL('about:blank')
window.setTouchBar(touchBar)
})
```
### Running the above example
To run the example above, you'll need to (assuming you've got a terminal open in the dirtectory you want to run the example):
1. Save the above file to your computer as `touchbar.js`
2. Install Electron via `npm install electron`
3. Run the example inside Electron: `./node_modules/.bin/electron touchbar.js`
You should then see a new Electron window and the app running in your touch bar (or touch bar emulator).

View file

@ -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.

View file

@ -157,9 +157,20 @@ requested by `window.open` or an external link like `<a target='_blank'>`.
By default a new `BrowserWindow` will be created for the `url`.
Calling `event.preventDefault()` will prevent creating new windows. In such case, the
`event.newGuest` may be set with a reference to a `BrowserWindow` instance to make it
used by the Electron's runtime.
Calling `event.preventDefault()` will prevent Electron from automatically creating a
new `BrowserWindow`. If you call `event.preventDefault()` and manually create a new
`BrowserWindow` then you must set `event.newGuest` to reference the new `BrowserWindow`
instance, failing to do so may result in unexpected behavior. For example:
```javascript
myBrowserWindow.webContents.on('new-window', (event, url) => {
event.preventDefault()
const win = new BrowserWindow({show: false})
win.once('ready-to-show', () => win.show())
win.loadURL(url)
event.newGuest = win
})
```
#### Event: 'will-navigate'
@ -325,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.
@ -363,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`,
@ -502,6 +510,24 @@ win.loadURL('http://github.com')
Emitted when the devtools window instructs the webContents to reload
#### Event: 'will-attach-webview'
Returns:
* `event` Event
* `webPreferences` Object - The web preferences that will be used by the guest
page. This object can be modified to adjust the preferences for the guest
page.
* `params` Object - The other `<webview>` parameters such as the `src` URL.
This object can be modified to adjust the parameters of the guest page.
Emitted when a `<webview>`'s web contents is being attached to this web
contents. Calling `event.preventDefault()` will destroy the guest page.
This event can be used to configure `webPreferences` for the `webContents`
of a `<webview>` before it's loaded, and provides the ability to set settings
that can't be set via `<webview>` attributes.
### Instance Methods
#### `contents.loadURL(url[, options])`
@ -512,6 +538,7 @@ Emitted when the devtools window instructs the webContents to reload
* `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.
Loads the `url` in the window. The `url` must contain the protocol prefix,
e.g. the `http://` or `file://`. If the load should bypass http cache then
@ -642,7 +669,7 @@ Injects CSS into the current web page.
#### `contents.executeJavaScript(code[, userGesture, callback])`
* `code` String
* `userGesture` Boolean (optional)
* `userGesture` Boolean (optional) - Default is `false`.
* `callback` Function (optional) - Called after script has been executed.
* `result` Any
@ -1072,24 +1099,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`)
@ -1169,7 +1188,7 @@ End subscribing for frame presentation events.
#### `contents.startDrag(item)`
* `item` Object
* `file` String - The path to the file being dragged.
* `file` String or `files` Array - The path(s) to the file(s) being dragged.
* `icon` [NativeImage](native-image.md) - The image must be non-empty on
macOS.
@ -1187,7 +1206,7 @@ the cursor when dragging.
* `callback` Function - `(error) => {}`.
* `error` Error
Returns true if the process of saving page has been initiated successfully.
Returns `Boolean` - true if the process of saving page has been initiated successfully.
```javascript
const {BrowserWindow} = require('electron')
@ -1246,9 +1265,36 @@ Returns `Integer` - If *offscreen rendering* is enabled returns the current fram
#### `contents.invalidate()`
Schedules a full repaint of the window this web contents is in.
If *offscreen rendering* is enabled invalidates the frame and generates a new
one through the `'paint'` event.
#### `contents.getWebRTCIPHandlingPolicy()`
Returns `String` - Returns the WebRTC IP Handling Policy.
#### `contents.setWebRTCIPHandlingPolicy(policy)`
* `policy` String - Specify the WebRTC IP Handling Policy.
* `default` - Exposes user's public and local IPs. This is the default
behavior. When this policy is used, WebRTC has the right to enumerate all
interfaces and bind them to discover public interfaces.
* `default_public_interface_only` - Exposes user's public IP, but does not
expose user's local IP. When this policy is used, WebRTC should only use the
default route used by http. This doesn't expose any local addresses.
* `default_public_and_private_interfaces` - Exposes user's public and local
IPs. When this policy is used, WebRTC should only use the default route used
by http. This also exposes the associated default private address. Default
route is the route chosen by the OS on a multi-homed endpoint.
* `disable_non_proxied_udp` - Does not expose public or local IPs. When this
policy is used, WebRTC should only use TCP to contact peers or servers unless
the proxy server supports UDP.
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.
### Instance Properties
#### `contents.id`

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

View file

@ -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

View file

@ -2,6 +2,8 @@
> Display external web content in an isolated frame and process.
Process: [Renderer](../tutorial/quick-start.md#renderer-process)
Use the `webview` tag to embed 'guest' content (such as web pages) in your
Electron app. The guest content is contained within the `webview` container.
An embedded page within your app controls how the guest content is laid out and
@ -10,7 +12,8 @@ rendered.
Unlike an `iframe`, the `webview` runs in a separate process than your
app. It doesn't have the same permissions as your web page and all interactions
between your app and embedded content will be asynchronous. This keeps your app
safe from the embedded content.
safe from the embedded content. **Note:** Most methods called on the
webview from the host page require a syncronous call to the main process.
For security purposes, `webview` can only be used in `BrowserWindow`s that have
`nodeIntegration` enabled.
@ -177,7 +180,7 @@ Web security is enabled by default.
```html
<webview src="https://github.com" partition="persist:github"></webview>
<webview src="http://electron.atom.io" partition="electron"></webview>
<webview src="https://electron.atom.io" partition="electron"></webview>
```
Sets the session used by the page. If `partition` starts with `persist:`, the
@ -212,7 +215,7 @@ The full list of supported preference strings can be found in [BrowserWindow](br
The string follows the same format as the features string in `window.open`.
A name by itself is given a `true` boolean value.
A preference can be set to another value by including an `=`, followed by the value.
Special values `yes` and `1` are interpreted as `true`, while `no` and `0` are interpreted as `false`.
Special values `yes` and `1` are interpreted as `true`, while `no` and `0` are interpreted as `false`.
### `blinkfeatures`
@ -222,7 +225,7 @@ Special values `yes` and `1` are interpreted as `true`, while `no` and `0` are i
A list of strings which specifies the blink features to be enabled separated by `,`.
The full list of supported feature strings can be found in the
[RuntimeEnabledFeatures.in][blink-feature-string] file.
[RuntimeEnabledFeatures.json5][blink-feature-string] file.
### `disableblinkfeatures`
@ -232,7 +235,7 @@ The full list of supported feature strings can be found in the
A list of strings which specifies the blink features to be disabled separated by `,`.
The full list of supported feature strings can be found in the
[RuntimeEnabledFeatures.in][blink-feature-string] file.
[RuntimeEnabledFeatures.json5][blink-feature-string] file.
### `guestinstance`
@ -310,6 +313,7 @@ webview.addEventListener('dom-ready', () => {
* `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.
Loads the `url` in the webview, the `url` must contain the protocol prefix,
e.g. the `http://` or `file://`.
@ -535,20 +539,42 @@ Stops any `findInPage` request for the `webview` with the provided `action`.
### `<webview>.print([options])`
* `options` Object (optional)
* `silent` Boolean - Don't ask user for print settings. Default is `false`.
* `printBackground` Boolean - Also prints the background color and image of
the web page. Default is `false`.
Prints `webview`'s web page. Same as `webContents.print([options])`.
### `<webview>.printToPDF(options, callback)`
* `options` Object
* `marginsType` Integer - (optional) Specifies the type of margins to use. Uses 0 for
default margin, 1 for no margin, and 2 for minimum margin.
* `pageSize` String - (optional) Specify page size of the generated PDF. Can be `A3`,
`A4`, `A5`, `Legal`, `Letter`, `Tabloid` or an Object containing `height`
and `width` in microns.
* `printBackground` Boolean - (optional) Whether to print CSS backgrounds.
* `printSelectionOnly` Boolean - (optional) Whether to print selection only.
* `landscape` Boolean - (optional) `true` for landscape, `false` for portrait.
* `callback` Function
* `error` Error
* `data` Buffer
Prints `webview`'s web page as PDF, Same as `webContents.printToPDF(options, callback)`.
### `<webview>.capturePage([rect, ]callback)`
* `rect` [Rectangle](structures/rectangle.md) (optional) - The area of the page to be captured
* `callback` Function
* `image` [NativeImage](native-image.md)
Captures a snapshot of the `webview`'s page. Same as `webContents.capturePage([rect, ]callback)`.
### `<webview>.send(channel[, arg1][, arg2][, ...])`
* `channel` String
* `arg` (optional)
* `...args` any[]
Send an asynchronous message to renderer process via `channel`, you can also
send arbitrary arguments. The renderer process can handle the message by
@ -724,6 +750,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.
@ -913,4 +940,4 @@ Emitted when DevTools is closed.
Emitted when DevTools is focused / opened.
[blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.in
[blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.json5?l=62

View file

@ -30,6 +30,10 @@ has to be a field of `BrowserWindow`'s options.
* Node integration will always be disabled in the opened `window` if it is
disabled on the parent window.
* Context isolation will always be enabled in the opened `window` if it is
enabled on the parent window.
* JavaScript will always be disabled in the opened `window` if it is disabled on
the parent window.
* Non-standard features (that are not handled by Chromium or Electron) given in
`features` will be passed to any registered `webContent`'s `new-window` event
handler in the `additionalFeatures` argument.