Merge branch 'master' into native-window-open

This commit is contained in:
Ryohei Ikegami 2017-04-18 21:59:22 +09:00
commit 8dff29185b
141 changed files with 2393 additions and 748 deletions

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

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

View file

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

View file

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

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

View file

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

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

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

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

@ -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 @@
# Size Object
* `width` Number
* `height` Number

View file

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

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

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

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