Merge branch 'master' into felix-notification-docs
This commit is contained in:
Zeke "Offline in April" Sikelianos
GitHub
commit
9fd1e2c8c4
243 changed files with 6040 additions and 1835 deletions
|
|
@ -104,3 +104,6 @@ an issue:
|
|||
* [Debug Instructions (Windows)](development/debug-instructions-windows.md)
|
||||
* [Setting Up Symbol Server in debugger](development/setting-up-symbol-server.md)
|
||||
* [Documentation Styleguide](styleguide.md)
|
||||
* [Upgrading Chrome](development/upgrading-chrome.md)
|
||||
* [Chromium Development](development/chromium-development.md)
|
||||
* [V8 Development](development/v8-development.md)
|
||||
|
|
|
|||
74
docs/api/browser-view.md
Normal file
74
docs/api/browser-view.md
Normal 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.
|
||||
|
|
@ -211,6 +211,9 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
|
|||
width of the web page when zoomed, `false` will cause it to zoom to the
|
||||
width of the screen. This will also affect the behavior when calling
|
||||
`maximize()` directly. Default is `false`.
|
||||
* `tabbingIdentifier` String (optional) - Tab group name, allows opening the
|
||||
window as a native tab on macOS 10.12+. Windows with the same tabbing
|
||||
identifier will be grouped together.
|
||||
* `webPreferences` Object (optional) - Settings of web page's features.
|
||||
* `devTools` Boolean (optional) - Whether to enable DevTools. If it is set to `false`, can not use `BrowserWindow.webContents.openDevTools()` to open DevTools. Default is `true`.
|
||||
* `nodeIntegration` Boolean (optional) - Whether node integration is enabled. Default
|
||||
|
|
@ -225,6 +228,13 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
|
|||
When node integration is turned off, the preload script can reintroduce
|
||||
Node global symbols back to the global scope. See example
|
||||
[here](process.md#event-loaded).
|
||||
* `sandbox` Boolean (optional) - If set, this will sandbox the renderer
|
||||
associated with the window, making it compatible with the Chromium
|
||||
OS-level sandbox and disabling the Node.js engine. This is not the same as
|
||||
the `nodeIntegration` option and the APIs available to the preload script
|
||||
are more limited. Read more about the option [here](sandbox-option.md).
|
||||
**Note:** This option is currently experimental and may change or be
|
||||
removed in future Electron releases.
|
||||
* `session` [Session](session.md#class-session) (optional) - Sets the session used by the
|
||||
page. Instead of passing the Session object directly, you can also choose to
|
||||
use the `partition` option instead, which accepts a partition string. When
|
||||
|
|
@ -282,7 +292,6 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
|
|||
window. Defaults to `false`. See the
|
||||
[offscreen rendering tutorial](../tutorial/offscreen-rendering.md) for
|
||||
more details.
|
||||
* `sandbox` Boolean (optional) - Whether to enable Chromium OS-level sandbox.
|
||||
* `contextIsolation` Boolean (optional) - Whether to run Electron APIs and
|
||||
the specified `preload` script in a separate JavaScript context. Defaults
|
||||
to `false`. The context that the `preload` script runs in will still
|
||||
|
|
@ -367,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.
|
||||
|
|
@ -489,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:
|
||||
|
|
@ -673,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
|
||||
|
|
@ -1282,6 +1302,13 @@ machine has a touch bar and is running on macOS 10.12.1+.
|
|||
**Note:** The TouchBar API is currently experimental and may change or be
|
||||
removed in future Electron releases.
|
||||
|
||||
#### `win.setBrowserView(browserView)` _Experimental_
|
||||
|
||||
* `browserView` [BrowserView](browser-view.md)
|
||||
|
||||
**Note:** The BrowserView API is currently experimental and may change or be
|
||||
removed in future Electron releases.
|
||||
|
||||
[blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.json5?l=62
|
||||
[quick-look]: https://en.wikipedia.org/wiki/Quick_Look
|
||||
[vibrancy-docs]: https://developer.apple.com/reference/appkit/nsvisualeffectview?language=objc
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ The `crashReporter` module has the following methods:
|
|||
* `companyName` String (optional)
|
||||
* `submitURL` String - URL that crash reports will be sent to as POST.
|
||||
* `productName` String (optional) - Defaults to `app.getName()`.
|
||||
* `uploadToServer` Boolean (optional) _Linux_ _macOS_ - Whether crash reports should be sent to the server
|
||||
* `uploadToServer` Boolean (optional) - Whether crash reports should be sent to the server
|
||||
Default is `true`.
|
||||
* `ignoreSystemCrashHandler` Boolean (optional) - Default is `false`.
|
||||
* `extra` Object (optional) - An object you can define that will be sent along with the
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -46,16 +46,8 @@ The `dialog` module has the following methods:
|
|||
* `noResolveAliases` - Disable the automatic alias (symlink) path
|
||||
resolution. Selected aliases will now return the alias path instead of
|
||||
their target path. _macOS_
|
||||
* `normalizeAccessKeys` Boolean (optional) - Normalize the keyboard access keys
|
||||
across platforms. Default is `false`. Enabling this assumes `&` is used in
|
||||
the button labels for the placement of the keyboard shortcut access key
|
||||
and labels will be converted so they work correctly on each platform, `&`
|
||||
characters are removed on macOS, converted to `_` on Linux, and left
|
||||
untouched on Windows. For example, a button label of `Vie&w` will be
|
||||
converted to `Vie_w` on Linux and `View` on macOS and can be selected
|
||||
via `Alt-W` on Windows and Linux.
|
||||
* `message` String (optional) _macOS_ - Message to display above input
|
||||
boxes.
|
||||
* `message` String (optional) _macOS_ - Message to display above input
|
||||
boxes.
|
||||
* `callback` Function (optional)
|
||||
* `filePaths` String[] - An array of file paths chosen by the user
|
||||
|
||||
|
|
@ -123,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
|
||||
|
|
@ -147,6 +140,14 @@ will be passed via `callback(filename)`
|
|||
others as command links in the dialog. This can make the dialog appear in
|
||||
the style of modern Windows apps. If you don't like this behavior, you can
|
||||
set `noLink` to `true`.
|
||||
* `normalizeAccessKeys` Boolean (optional) - Normalize the keyboard access keys
|
||||
across platforms. Default is `false`. Enabling this assumes `&` is used in
|
||||
the button labels for the placement of the keyboard shortcut access key
|
||||
and labels will be converted so they work correctly on each platform, `&`
|
||||
characters are removed on macOS, converted to `_` on Linux, and left
|
||||
untouched on Windows. For example, a button label of `Vie&w` will be
|
||||
converted to `Vie_w` on Linux and `View` on macOS and can be selected
|
||||
via `Alt-W` on Windows and Linux.
|
||||
* `callback` Function (optional)
|
||||
* `response` Number - The index of the button that was clicked
|
||||
* `checkboxChecked` Boolean - The checked state of the checkbox if
|
||||
|
|
@ -175,6 +176,20 @@ it is usually used to report errors in early stage of startup. If called
|
|||
before the app `ready`event on Linux, the message will be emitted to stderr,
|
||||
and no GUI dialog will appear.
|
||||
|
||||
### `dialog.showCertificateTrustDialog([browserWindow, ]options, callback)` _macOS_
|
||||
|
||||
* `browserWindow` BrowserWindow (optional)
|
||||
* `options` Object
|
||||
* `certificate` [Certificate](structures/certificate.md) - The certificate to trust/import.
|
||||
* `message` String - The message to display to the user.
|
||||
* `callback` Function
|
||||
|
||||
Displays a modal dialog that shows a message and certificate information, and
|
||||
gives the user the option of trusting/importing the certificate.
|
||||
|
||||
The `browserWindow` argument allows the dialog to attach itself to a parent
|
||||
window, making it modal.
|
||||
|
||||
## Sheets
|
||||
|
||||
On macOS, dialogs are presented as sheets attached to a window if you provide
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
176
docs/api/menu.md
176
docs/api/menu.md
|
|
@ -16,8 +16,11 @@ The `menu` class has the following static methods:
|
|||
|
||||
* `menu` Menu
|
||||
|
||||
Sets `menu` as the application menu on macOS. On Windows and Linux, the `menu`
|
||||
will be set as each window's top menu.
|
||||
Sets `menu` as the application menu on macOS. On Windows and Linux, the
|
||||
`menu` will be set as each window's top menu.
|
||||
|
||||
Passing `null` will remove the menu bar on Windows and Linux but has no
|
||||
effect on macOS.
|
||||
|
||||
**Note:** This API has to be called after the `ready` event of `app` module.
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -115,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'}
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
@ -202,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'}
|
||||
]
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -219,10 +219,7 @@ Returns `Boolean` - Whether the image is empty.
|
|||
|
||||
#### `image.getSize()`
|
||||
|
||||
Returns `Object`:
|
||||
|
||||
* `width` Integer
|
||||
* `height` Integer
|
||||
Returns [`Size`](structures/size.md)
|
||||
|
||||
#### `image.setTemplateImage(option)`
|
||||
|
||||
|
|
@ -236,11 +233,7 @@ Returns `Boolean` - Whether the image is a template image.
|
|||
|
||||
#### `image.crop(rect)`
|
||||
|
||||
* `rect` Object - The area of the image to crop
|
||||
* `x` Integer
|
||||
* `y` Integer
|
||||
* `width` Integer
|
||||
* `height` Integer
|
||||
* `rect` [Rectangle](structures/rectangle.md) - The area of the image to crop
|
||||
|
||||
Returns `NativeImage` - The cropped image.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
195
docs/api/sandbox-option.md
Normal 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.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -287,7 +287,7 @@ win.webContents.session.setCertificateVerifyProc((request, callback) => {
|
|||
#### `ses.setPermissionRequestHandler(handler)`
|
||||
|
||||
* `handler` Function
|
||||
* `webContents` Object - [WebContents](web-contents.md) requesting the permission.
|
||||
* `webContents` [WebContents](web-contents.md) - WebContents requesting the permission.
|
||||
* `permission` String - Enum of 'media', 'geolocation', 'notifications', 'midiSysex',
|
||||
'pointerLock', 'fullscreen', 'openExternal'.
|
||||
* `callback` Function
|
||||
|
|
@ -388,15 +388,15 @@ The following properties are available on instances of `Session`:
|
|||
|
||||
#### `ses.cookies`
|
||||
|
||||
A Cookies object for this session.
|
||||
A [Cookies](cookies.md) object for this session.
|
||||
|
||||
#### `ses.webRequest`
|
||||
|
||||
A WebRequest object for this session.
|
||||
A [WebRequest](web-request.md) object for this session.
|
||||
|
||||
#### `ses.protocol`
|
||||
|
||||
A Protocol object (an instance of [protocol](protocol.md) module) for this session.
|
||||
A [Protocol](protocol.md) object for this session.
|
||||
|
||||
```javascript
|
||||
const {app, session} = require('electron')
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
4
docs/api/structures/point.md
Normal file
4
docs/api/structures/point.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
# Point Object
|
||||
|
||||
* `x` Number
|
||||
* `y` Number
|
||||
4
docs/api/structures/size.md
Normal file
4
docs/api/structures/size.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
# Size Object
|
||||
|
||||
* `width` Number
|
||||
* `height` Number
|
||||
|
|
@ -11,6 +11,7 @@ Process: [Main](../tutorial/quick-start.md#main-process)
|
|||
* `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
|
||||
|
|
|
|||
|
|
@ -9,9 +9,9 @@ Process: [Main](../tutorial/quick-start.md#main-process)
|
|||
* `options` Object
|
||||
* `items` [ScrubberItem[]](structures/scrubber-item.md) - An array of items to place in this scrubber
|
||||
* `select` Function - Called when the user taps an item that was not the last tapped item
|
||||
* `selectedIndex` - The index of the item the user selected
|
||||
* `selectedIndex` Integer - The index of the item the user selected
|
||||
* `highlight` Function - Called when the user taps any item
|
||||
* `highlightedIndex` - The index of the item the user touched
|
||||
* `highlightedIndex` Integer - The index of the item the user touched
|
||||
* `selectedStyle` String - Selected item style. Defaults to `null`.
|
||||
* `overlayStyle` String - Selected overlay item style. Defaults to `null`.
|
||||
* `showArrowButtons` Boolean - Defaults to `false`.
|
||||
|
|
|
|||
|
|
@ -8,18 +8,23 @@ Process: [Main](../tutorial/quick-start.md#main-process)
|
|||
|
||||
* `options` Object
|
||||
* `segmentStyle` String - (Optional) Style of the segments:
|
||||
* `automatic` - Default
|
||||
* `rounded`
|
||||
* `textured-rounded`
|
||||
* `round-rect`
|
||||
* `textured-square`
|
||||
* `capsule`
|
||||
* `small-square`
|
||||
* `separated`
|
||||
* `automatic` - Default. The appearance of the segmented control is
|
||||
automatically determined based on the type of window in which the control
|
||||
is displayed and the position within the window.
|
||||
* `rounded` - The control is displayed using the rounded style.
|
||||
* `textured-rounded` - The control is displayed using the textured rounded
|
||||
style.
|
||||
* `round-rect` - The control is displayed using the round rect style.
|
||||
* `textured-square` - The control is displayed using the textured square
|
||||
style.
|
||||
* `capsule` - The control is displayed using the capsule style
|
||||
* `small-square` - The control is displayed using the small square style.
|
||||
* `separated` - The segments in the control are displayed very close to each
|
||||
other but not touching.
|
||||
* `segments` [SegmentedControlSegment[]](structures/segmented-control-segment.md) - An array of segments to place in this control
|
||||
* `selectedIndex` Integer (Optional) - The index of the currently selected segment, will update automatically with user interaction
|
||||
* `change` Function - Called when the user selects a new segment
|
||||
* `selectedIndex` - The index of the segment the user selected
|
||||
* `selectedIndex` Integer - The index of the segment the user selected
|
||||
|
||||
### Instance Properties
|
||||
|
||||
|
|
|
|||
|
|
@ -4,9 +4,11 @@
|
|||
|
||||
Process: [Main](../tutorial/quick-start.md#main-process)
|
||||
|
||||
### `new TouchBar(items)` _Experimental_
|
||||
### `new TouchBar(options)` _Experimental_
|
||||
|
||||
* `items` ([TouchBarButton](touch-bar-button.md) | [TouchBarColorPicker](touch-bar-color-picker.md) | [TouchBarGroup](touch-bar-group.md) | [TouchBarLabel](touch-bar-label.md) | [TouchBarPopover](touch-bar-popover.md) | [TouchBarSlider](touch-bar-slider.md) | [TouchBarSpacer](touch-bar-spacer.md))[]
|
||||
* `options` - Object
|
||||
* `items` ([TouchBarButton](touch-bar-button.md) | [TouchBarColorPicker](touch-bar-color-picker.md) | [TouchBarGroup](touch-bar-group.md) | [TouchBarLabel](touch-bar-label.md) | [TouchBarPopover](touch-bar-popover.md) | [TouchBarScrubber](touch-bar-scrubber.md) | [TouchBarSegmentedControl](touch-bar-segmented-control.md) | [TouchBarSlider](touch-bar-slider.md) | [TouchBarSpacer](touch-bar-spacer.md))[]
|
||||
* `escapeItem` ([TouchBarButton](touch-bar-button.md) | [TouchBarColorPicker](touch-bar-color-picker.md) | [TouchBarGroup](touch-bar-group.md) | [TouchBarLabel](touch-bar-label.md) | [TouchBarPopover](touch-bar-popover.md) | [TouchBarScrubber](touch-bar-scrubber.md) | [TouchBarSegmentedControl](touch-bar-segmented-control.md) | [TouchBarSlider](touch-bar-slider.md) | [TouchBarSpacer](touch-bar-spacer.md)) (optional)
|
||||
|
||||
Creates a new touch bar with the specified items. Use
|
||||
`BrowserWindow.setTouchBar` to add the `TouchBar` to a window.
|
||||
|
|
@ -14,6 +16,20 @@ Creates a new touch bar with the specified items. Use
|
|||
**Note:** The TouchBar API is currently experimental and may change or be
|
||||
removed in future Electron releases.
|
||||
|
||||
**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
|
||||
|
|
@ -122,3 +138,13 @@ app.once('ready', () => {
|
|||
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).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -336,6 +336,7 @@ Returns:
|
|||
* `activeMatchOrdinal` Integer - Position of the active match.
|
||||
* `matches` Integer - Number of Matches.
|
||||
* `selectionArea` Object - Coordinates of first match region.
|
||||
* `finalUpdate` Boolean
|
||||
|
||||
Emitted when a result is available for
|
||||
[`webContents.findInPage`] request.
|
||||
|
|
@ -374,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`,
|
||||
|
|
@ -1066,24 +1063,16 @@ app.on('ready', () => {
|
|||
(default: `desktop`)
|
||||
* `desktop` - Desktop screen type
|
||||
* `mobile` - Mobile screen type
|
||||
* `screenSize` Object - Set the emulated screen size (screenPosition == mobile)
|
||||
* `width` Integer - Set the emulated screen width
|
||||
* `height` Integer - Set the emulated screen height
|
||||
* `viewPosition` Object - Position the view on the screen
|
||||
* `screenSize` [Size](structures/size.md) - Set the emulated screen size (screenPosition == mobile)
|
||||
* `viewPosition` [Point](structures/point.md) - Position the view on the screen
|
||||
(screenPosition == mobile) (default: `{x: 0, y: 0}`)
|
||||
* `x` Integer - Set the x axis offset from top left corner
|
||||
* `y` Integer - Set the y axis offset from top left corner
|
||||
* `deviceScaleFactor` Integer - Set the device scale factor (if zero defaults to
|
||||
original device scale factor) (default: `0`)
|
||||
* `viewSize` Object - Set the emulated view size (empty means no override)
|
||||
* `width` Integer - Set the emulated view width
|
||||
* `height` Integer - Set the emulated view height
|
||||
* `viewSize` [Size](structures/size.md) - Set the emulated view size (empty means no override)
|
||||
* `fitToView` Boolean - Whether emulated view should be scaled down if
|
||||
necessary to fit into available space (default: `false`)
|
||||
* `offset` Object - Offset of the emulated view inside available space (not in
|
||||
fit to view mode) (default: `{x: 0, y: 0}`)
|
||||
* `x` Float - Set the x axis offset from top left corner
|
||||
* `y` Float - Set the y axis offset from top left corner
|
||||
* `offset` [Point](structures/point.md) - Offset of the emulated view inside available space
|
||||
(not in fit to view mode) (default: `{x: 0, y: 0}`)
|
||||
* `scale` Float - Scale of emulated view inside available space (not in fit to
|
||||
view mode) (default: `1`)
|
||||
|
||||
|
|
@ -1247,7 +1236,7 @@ one through the `'paint'` event.
|
|||
|
||||
#### `contents.getWebRTCIPHandlingPolicy()`
|
||||
|
||||
* Returns `String` - Returns the WebRTC IP Handling Policy.
|
||||
Returns `String` - Returns the WebRTC IP Handling Policy.
|
||||
|
||||
#### `contents.setWebRTCIPHandlingPolicy(policy)`
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -12,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.
|
||||
|
|
@ -749,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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -10,6 +10,9 @@ Follow the guidelines below for building Electron on Windows.
|
|||
* [Python 2.7](http://www.python.org/download/releases/2.7/)
|
||||
* [Node.js](http://nodejs.org/download/)
|
||||
* [Git](http://git-scm.com)
|
||||
* [Debugging Tools for Windows](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063.aspx)
|
||||
if you plan on creating a full distribution since `symstore.exe` is used for
|
||||
creating a symbol store from `.pdb` files.
|
||||
|
||||
If you don't currently have a Windows installation,
|
||||
[dev.microsoftedge.com](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/)
|
||||
|
|
|
|||
14
docs/development/chromium-development.md
Normal file
14
docs/development/chromium-development.md
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
# Chromium Development
|
||||
|
||||
> A collection of resources for learning about Chromium and tracking its development
|
||||
|
||||
- [chromiumdev](https://chromiumdev-slack.herokuapp.com) on Slack
|
||||
- [@ChromiumDev](https://twitter.com/ChromiumDev) on Twitter
|
||||
- [@googlechrome](https://twitter.com/googlechrome) on Twitter
|
||||
- [Blog](https://blog.chromium.org)
|
||||
- [Code Search](https://cs.chromium.org/)
|
||||
- [Source Code](https://cs.chromium.org/chromium/src/)
|
||||
- [Development Calendar and Release Info](https://www.chromium.org/developers/calendar)
|
||||
- [Discussion Groups](http://www.chromium.org/developers/discussion-groups)
|
||||
|
||||
See also [V8 Development](v8-development.md)
|
||||
|
|
@ -45,6 +45,46 @@ Chrome/Node API changes.
|
|||
- 64-bit Linux
|
||||
- ARM Linux
|
||||
|
||||
## Verify ffmpeg Support
|
||||
|
||||
Electron ships with a version of `ffmpeg` that includes proprietary codecs by
|
||||
default. A version without these codecs is built and distributed with each
|
||||
release as well. Each Chrome upgrade should verify that switching this version is
|
||||
still supported.
|
||||
|
||||
You can verify Electron's support for multiple `ffmpeg` builds by loading the
|
||||
following page. It should work with the default `ffmpeg` library distributed
|
||||
with Electron and not work with the `ffmpeg` library built without proprietary
|
||||
codecs.
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Proprietary Codec Check</title>
|
||||
</head>
|
||||
<body>
|
||||
<p>Checking if Electron is using proprietary codecs by loading video from http://www.quirksmode.org/html5/videos/big_buck_bunny.mp4</p>
|
||||
<p id="outcome"></p>
|
||||
<video style="display:none" src="http://www.quirksmode.org/html5/videos/big_buck_bunny.mp4" autoplay></video>
|
||||
<script>
|
||||
const video = document.querySelector('video')
|
||||
video.addEventListener('error', ({target}) => {
|
||||
if (target.error.code === target.error.MEDIA_ERR_SRC_NOT_SUPPORTED) {
|
||||
document.querySelector('#outcome').textContent = 'Not using proprietary codecs, video emitted source not supported error event.'
|
||||
} else {
|
||||
document.querySelector('#outcome').textContent = `Unexpected error: ${target.error.code}`
|
||||
}
|
||||
})
|
||||
video.addEventListener('playing', () => {
|
||||
document.querySelector('#outcome').textContent = 'Using proprietary codecs, video started playing.'
|
||||
})
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
## Links
|
||||
|
||||
- [Chrome Release Schedule](https://www.chromium.org/developers/calendar)
|
||||
|
|
|
|||
11
docs/development/v8-development.md
Normal file
11
docs/development/v8-development.md
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
# V8 Development
|
||||
|
||||
> A collection of resources for learning and using V8
|
||||
|
||||
* [V8 Tracing](https://github.com/v8/v8/wiki/Tracing-V8)
|
||||
* [V8 Profiler](https://github.com/v8/v8/wiki/V8-Profiler) - Profiler combinations which are useful for profiling: `--prof`, `--trace-ic`, `--trace-opt`, `--trace-deopt`, `--print-bytecode`, `--print-opt-code`
|
||||
* [V8 Interpreter Design](https://docs.google.com/document/d/11T2CRex9hXxoJwbYqVQ32yIPMh0uouUZLdyrtmMoL44/edit?ts=56f27d9d#heading=h.6jz9dj3bnr8t)
|
||||
* [Optimizing compiler](https://github.com/v8/v8/wiki/TurboFan)
|
||||
* [V8 GDB Debugging](https://github.com/v8/v8/wiki/GDB-JIT-Interface)
|
||||
|
||||
See also [Chromium Development](chromium-development.md)
|
||||
|
|
@ -148,7 +148,7 @@ npm uninstall electron
|
|||
npm uninstall -g electron
|
||||
```
|
||||
|
||||
However if your are using the built-in module but still getting this error, it
|
||||
However if you are using the built-in module but still getting this error, it
|
||||
is very likely you are using the module in the wrong process. For example
|
||||
`electron.app` can only be used in the main process, while `electron.webFrame`
|
||||
is only available in renderer processes.
|
||||
|
|
|
|||
|
|
@ -8,6 +8,10 @@ applications can put a custom menu in the dock menu.
|
|||
This guide explains how to integrate your application into those desktop
|
||||
environments with Electron APIs.
|
||||
|
||||
## Notifications
|
||||
|
||||
See [Notifications](notifications.md)
|
||||
|
||||
## Recent documents (Windows & macOS)
|
||||
|
||||
Windows and macOS provide easy access to a list of recent documents opened by
|
||||
|
|
|
|||
|
|
@ -1,21 +1,55 @@
|
|||
# Electron Versioning
|
||||
|
||||
If you are a seasoned Node developer, you are surely aware of `semver` - and
|
||||
might be used to giving your dependency management systems only rough guidelines
|
||||
rather than fixed version numbers. Due to the hard dependency on Node and
|
||||
Chromium, Electron is in a slightly more difficult position and does not follow
|
||||
semver. You should therefore always reference a specific version of Electron.
|
||||
If you've been using Node and npm for a while, you are probably aware of [Semantic Versioning], or SemVer for short. It's a convention for specifying version numbers for software that helps communicate intentions to the users of your software.
|
||||
|
||||
Version numbers are bumped using the following rules:
|
||||
## Overview of Semantic Versioning
|
||||
|
||||
* Major: For breaking changes in Electron's API - if you upgrade from `0.37.0`
|
||||
to `1.0.0`, you will have to update your app.
|
||||
* Minor: For major Chrome and minor Node upgrades; or significant Electron
|
||||
changes - if you upgrade from `1.0.0` to `1.1.0`, your app is supposed to
|
||||
Semantic versions are always made up of three numbers:
|
||||
|
||||
```
|
||||
major.minor.patch
|
||||
```
|
||||
|
||||
Semantic version numbers are bumped (incremented) using the following rules:
|
||||
|
||||
* **Major** is for changes that break backwards compatibility.
|
||||
* **Minor** is for new features that don't break backwards compatibility.
|
||||
* **Patch** is for bug fixes and other minor changes.
|
||||
|
||||
A simple mnemonic for remembering this scheme is as follows:
|
||||
|
||||
```
|
||||
breaking.feature.fix
|
||||
```
|
||||
|
||||
## Electron Versioning
|
||||
|
||||
Due to its dependency on Node and Chromium, it is not possible for the Electron
|
||||
project to adhere to a SemVer policy. **You should therefore always
|
||||
reference a specific version of Electron.**
|
||||
|
||||
Electron version numbers are bumped using the following rules:
|
||||
|
||||
* **Major** is for breaking changes in Electron's API. If you upgrade from `0.37.0`
|
||||
to `1.0.0`, you will have to make changes to your app.
|
||||
* **Minor** is for major Chrome and minor Node upgrades, or significant Electron
|
||||
changes. If you upgrade from `1.5.0` to `1.6.0`, your app is supposed to
|
||||
still work, but you might have to work around small changes.
|
||||
* Patch: For new features and bug fixes - if you upgrade from `1.0.0` to
|
||||
`1.0.1`, your app will continue to work as-is.
|
||||
* **Patch** is for new features and bug fixes. If you upgrade from `1.6.2` to
|
||||
`1.6.3`, your app will continue to work as-is.
|
||||
|
||||
If you are using `electron` or `electron-prebuilt`, we recommend that you set a fixed version
|
||||
number (`1.1.0` instead of `^1.1.0`) to ensure that all upgrades of Electron are
|
||||
a manual operation made by you, the developer.
|
||||
We recommend that you set a fixed version when installing Electron from npm:
|
||||
|
||||
```sh
|
||||
npm install electron --save-exact --save-dev
|
||||
```
|
||||
|
||||
The `--save-exact` flag will add `electron` to your `package.json` file without
|
||||
using a `^` or `~`, e.g. `1.6.2` instead of `^1.6.2`. This practice ensures that
|
||||
all upgrades of Electron are a manual operation made by you, the developer.
|
||||
|
||||
Alternatively, you can use the `~` prefix in your SemVer range, like `~1.6.2`.
|
||||
This will lock your major and minor version, but allow new patch versions to
|
||||
be installed.
|
||||
|
||||
[Semantic Versioning]: http://semver.org
|
||||
|
|
|
|||
|
|
@ -69,8 +69,7 @@ The output should look roughly like this:
|
|||
│ └── atom.asar
|
||||
├── snapshot_blob.bin
|
||||
├── squirrel.exe
|
||||
├── ui_resources_200_percent.pak
|
||||
└── xinput1_3.dll
|
||||
└── ui_resources_200_percent.pak
|
||||
```
|
||||
|
||||
## Step 2: Running electron-windows-store
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue