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

resolve update conflicts

Browse source
This commit is contained in:
Heilig Benedek 2016-02-27 03:23:10 +01:00
commit bb42c85df8
148 changed files with 4435 additions and 2699 deletions
Download patch file Download diff file Expand all files Collapse all files

9
docs/api/app.md
View file

@ -156,7 +156,7 @@ certificate you should prevent the default behavior with
`event.preventDefault()` and call `callback(true)`.
```javascript
session.on('certificate-error', function(event, webContents, url, error, certificate, callback) {
app.on('certificate-error', function(event, webContents, url, error, certificate, callback) {
if (url == "https://github.com") {
// Verification logic.
event.preventDefault();
@ -246,7 +246,7 @@ returning `false` in the `beforeunload` event handler.
### `app.hide()` _OS X_
Hides all application windows without minimising them.
Hides all application windows without minimizing them.
### `app.show()` _OS X_
@ -398,7 +398,7 @@ quit.
On OS X the system enforces single instance automatically when users try to open
a second instance of your app in Finder, and the `open-file` and `open-url`
events will be emitted for that. However when users start your app in command
line the system's single instance machanism will be bypassed and you have to
line the system's single instance mechanism will be bypassed and you have to
use this method to ensure single instance.
An example of activating the window of primary instance when a second instance
@ -413,7 +413,6 @@ var shouldQuit = app.makeSingleInstance(function(commandLine, workingDirectory)
if (myWindow.isMinimized()) myWindow.restore();
myWindow.focus();
}
return true;
});
if (shouldQuit) {
@ -516,7 +515,7 @@ Shows the dock icon.
### `app.dock.setMenu(menu)` _OS X_
* `menu` Menu
* `menu` [Menu](menu.md)
Sets the application's [dock menu][dock-menu].

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

@ -457,7 +457,7 @@ Returns a boolean, whether the window is in fullscreen mode.
* `aspectRatio` The aspect ratio we want to maintain for some portion of the
content view.
* `extraSize` Object (optional) - The extra size not to be included while
maintaining the aspect ratio. Properties:
maintaining the aspect ratio.
* `width` Integer
* `height` Integer
@ -477,13 +477,11 @@ height areas you have within the overall content view.
### `win.setBounds(options[, animate])`
* `options` Object, properties:
* `options` Object
* `x` Integer
* `y` Integer
* `width` Integer
* `height` Integer
* `animate` Boolean (optional) _OS X_
Resizes and moves the window to `width`, `height`, `x`, `y`.
@ -716,7 +714,7 @@ Returns the pathname of the file the window represents.
* `edited` Boolean
Specifies whether the window’s document has been edited, and the icon in title
bar will become grey when set to `true`.
bar will become gray when set to `true`.
### `win.isDocumentEdited()` _OS X_
@ -728,7 +726,7 @@ Whether the window's document has been edited.
### `win.capturePage([rect, ]callback)`
* `rect` Object (optional)- The area of page to be captured, properties:
* `rect` Object (optional) - The area of page to be captured
* `x` Integer
* `y` Integer
* `width` Integer
@ -801,27 +799,7 @@ Returns whether the window has a shadow. On Windows and Linux always returns
### `win.setThumbarButtons(buttons)` _Windows 7+_
`buttons` Array of `button` Objects:
`button` Object, properties:
* `icon` [NativeImage](native-image.md) - The icon showing in thumbnail
toolbar.
* `tooltip` String (optional) - The text of the button's tooltip.
* `flags` Array (optional) - Control specific states and behaviors
of the button. By default, it uses `enabled`. It can include following
Strings:
* `enabled` - The button is active and available to the user.
* `disabled` - The button is disabled. It is present, but has a visual
state indicating it will not respond to user action.
* `dismissonclick` - When the button is clicked, the taskbar button's
flyout closes immediately.
* `nobackground` - Do not draw a button border, use only the image.
* `hidden` - The button is not shown to the user.
* `noninteractive` - The button is enabled but not interactive; no
pressed button state is drawn. This value is intended for instances
where the button is used in a notification.
* `click` - Function
* `buttons` Array
Add a thumbnail toolbar with a specified set of buttons to the thumbnail image
of a window in a taskbar button layout. Returns a `Boolean` object indicates
@ -832,6 +810,29 @@ the limited room. Once you setup the thumbnail toolbar, the toolbar cannot be
removed due to the platform's limitation. But you can call the API with an empty
array to clean the buttons.
The `buttons` is an array of `Button` objects:
* `Button` Object
* `icon` [NativeImage](native-image.md) - The icon showing in thumbnail
toolbar.
* `click` Function
* `tooltip` String (optional) - The text of the button's tooltip.
* `flags` Array (optional) - Control specific states and behaviors of the
button. By default, it is `['enabled']`.
The `flags` is an array that can include following `String`s:
* `enabled` - The button is active and available to the user.
* `disabled` - The button is disabled. It is present, but has a visual state
indicating it will not respond to user action.
* `dismissonclick` - When the button is clicked, the thumbnail window closes
immediately.
* `nobackground` - Do not draw a button border, use only the image.
* `hidden` - The button is not shown to the user.
* `noninteractive` - The button is enabled but not interactive; no pressed
button state is drawn. This value is intended for instances where the button
is used in a notification.
### `win.showDefinitionForSelection()` _OS X_
Shows pop-up dictionary that searches the selected word on the page.

13
docs/api/clipboard.md
View file

@ -61,6 +61,19 @@ Returns the content in the clipboard as a [NativeImage](native-image.md).
Writes `image` to the clipboard.
### `clipboard.readRtf([type])`
* `type` String (optional)
Returns the content in the clipboard as RTF.
### `clipboard.writeRtf(text[, type])`
* `text` String
* `type` String (optional)
Writes the `text` into the clipboard in RTF.
### `clipboard.clear([type])`
* `type` String (optional)

2
docs/api/content-tracing.md
View file

@ -155,7 +155,7 @@ called.
* `eventName` String
* `callback` Function
`callback` will will be called every time the given event occurs on any
`callback` will be called every time the given event occurs on any
process.
### `contentTracing.cancelWatchEvent()`

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

@ -22,19 +22,16 @@ The `crash-reporter` module has the following methods:
### `crashReporter.start(options)`
`options` Object, properties:
* `productName` String, default: Electron.
* `companyName` String (**required**)
* `submitURL` String, (**required**)
* URL that crash reports will be sent to as POST.
* `autoSubmit` Boolean, default: `true`.
* Send the crash report without user interaction.
* `ignoreSystemCrashHandler` Boolean, default: `false`.
* `extra` Object
* An object you can define that will be sent along with the report.
* Only string properties are sent correctly.
* Nested objects are not supported.
* `options` Object
* `companyName` String
* `submitURL` String - URL that crash reports will be sent to as POST.
* `productName` String (optional) - Default is `Electron`.
* `autoSubmit` Boolean - Send the crash report without user interaction.
Default is `true`.
* `ignoreSystemCrashHandler` Boolean - Default is `false`.
* `extra` Object - An object you can define that will be sent along with the
report. Only string properties are sent correctly, Nested objects are not
supported.
You are required to call this method before using other `crashReporter`
APIs.

46
docs/api/ipc-main.md
View file

@ -9,7 +9,7 @@ module.
## Sending Messages
It is also possible to send messages from the main process to the renderer
process, see [webContents.send](web-contents.md#webcontentssendchannel-arg1-arg2-) for more information.
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`.
@ -48,37 +48,37 @@ ipcRenderer.send('asynchronous-message', 'ping');
The `ipcMain` module has the following method to listen for events:
### `ipcMain.on(channel, callback)`
### `ipcMain.on(channel, listener)`
* `channel` String - The event name.
* `callback` Function
* `channel` String
* `listener` Function
When the event occurs the `callback` is called with an `event` object and
arbitrary arguments.
Listens to `channel`, when a new message arrives `listener` would be called with
`listener(event, args...)`.
### `ipcMain.removeListener(channel, callback)`
### `ipcMain.once(channel, listener)`
* `channel` String - The event name.
* `callback` Function - The reference to the same function that you used for
`ipcMain.on(channel, callback)`
* `channel` String
* `listener` Function
Once done listening for messages, if you no longer want to activate this
callback and for whatever reason can't merely stop sending messages on the
channel, this function will remove the callback handler for the specified
channel.
Adds a one time `listener` function for the event. This `listener` is invoked
only the next time a message is sent to `channel`, after which it is removed.
### `ipcMain.removeAllListeners(channel)`
### `ipcMain.removeListener(channel, listener)`
* `channel` String - The event name.
* `channel` String
* `listener` Function
This removes *all* handlers to this ipc channel.
Removes the specified `listener` from the listener array for the specified
`channel`.
### `ipcMain.once(channel, callback)`
### `ipcMain.removeAllListeners([channel])`
Use this in place of `ipcMain.on()` to fire handlers meant to occur only once,
as in, they won't be activated after one call of `callback`
* `channel` String (optional)
## IPC Event
Removes all listeners, or those of the specified `channel`.
## Event object
The `event` object passed to the `callback` has the following methods:
@ -90,4 +90,6 @@ Set this to the value to be returned in a synchronous message.
Returns the `webContents` that sent the message, you can call
`event.sender.send` to reply to the asynchronous message, see
[webContents.send](web-contents.md#webcontentssendchannel-arg1-arg2-) for more information.
[webContents.send][web-contents-send] for more information.
[web-contents-send]: web-contents.md#webcontentssendchannel-arg1-arg2-

61
docs/api/ipc-renderer.md
View file

@ -12,35 +12,35 @@ See [ipcMain](ipc-main.md) for code examples.
The `ipcRenderer` module has the following method to listen for events:
### `ipcRenderer.on(channel, callback)`
### `ipcRenderer.on(channel, listener)`
* `channel` String - The event name.
* `callback` Function
* `channel` String
* `listener` Function
When the event occurs the `callback` is called with an `event` object and
arbitrary arguments.
Listens to `channel`, when a new message arrives `listener` would be called with
`listener(event, args...)`.
### `ipcRenderer.removeListener(channel, callback)`
### `ipcRenderer.once(channel, listener)`
* `channel` String - The event name.
* `callback` Function - The reference to the same function that you used for
`ipcRenderer.on(channel, callback)`
* `channel` String
* `listener` Function
Once done listening for messages, if you no longer want to activate this
callback and for whatever reason can't merely stop sending messages on the
channel, this function will remove the callback handler for the specified
channel.
Adds a one time `listener` function for the event. This `listener` is invoked
only the next time a message is sent to `channel`, after which it is removed.
### `ipcRenderer.removeAllListeners(channel)`
### `ipcRenderer.removeListener(channel, listener)`
* `channel` String - The event name.
* `channel` String
* `listener` Function
This removes *all* handlers to this ipc channel.
Removes the specified `listener` from the listener array for the specified
`channel`.
### `ipcRenderer.once(channel, callback)`
### `ipcRenderer.removeAllListeners([channel])`
Use this in place of `ipcRenderer.on()` to fire handlers meant to occur only once,
as in, they won't be activated after one call of `callback`
* `channel` String (optional)
Removes all listeners, or those of the specified `channel`.
## Sending Messages
@ -48,30 +48,33 @@ The `ipcRenderer` module has the following methods for sending messages:
### `ipcRenderer.send(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `channel` String
* `arg` (optional)
Send an event to the main process asynchronously via a `channel`, you can also
send arbitrary arguments. The main process handles it by listening for the
`channel` event with `ipcMain`.
Send a message to the main process asynchronously via `channel`, you can also
send arbitrary arguments. Arguments will be serialized in JSON internally and
hence no functions or prototype chain will be included.
The main process handles it by listening for `channel` with `ipcMain` module.
### `ipcRenderer.sendSync(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `channel` String
* `arg` (optional)
Send an event to the main process synchronously via a `channel`, you can also
send arbitrary arguments.
Send a message to the main process synchronously via `channel`, you can also
send arbitrary arguments. Arguments will be serialized in JSON internally and
hence no functions or prototype chain will be included.
The main process handles it by listening for the `channel` event with
`ipcMain` and replies by setting `event.returnValue`.
The main process handles it by listening for `channel` with `ipcMain` module,
and replies by setting `event.returnValue`.
__Note:__ Sending a synchronous message will block the whole renderer process,
unless you know what you are doing you should never use it.
### `ipcRenderer.sendToHost(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `channel` String
* `arg` (optional)
Like `ipcRenderer.send` but the event will be sent to the `<webview>` element in

2
docs/api/menu.md
View file

@ -143,7 +143,7 @@ var template = [
];
if (process.platform == 'darwin') {
var name = require('electron').app.getName();
var name = require('electron').remote.app.getName();
template.unshift({
label: name,
submenu: [

8
docs/api/shell.md
View file

@ -26,12 +26,16 @@ Show the given file in a file manager. If possible, select the file.
Open the given file in the desktop's default manner.
### `shell.openExternal(url)`
### `shell.openExternal(url[, options])`
* `url` String
* `options` Object (optional) _OS X_
* `activate` Boolean - `true` to bring the opened application to the
foreground. The default is `true`.
Open the given external protocol URL in the desktop's default manner. (For
example, mailto: URLs in the user's default mail agent.)
example, mailto: URLs in the user's default mail agent.) Returns true if an
application was available to open the URL, false otherwise.
### `shell.moveItemToTrash(fullPath)`

7
docs/api/tray.md
View file

@ -32,6 +32,13 @@ __Platform limitations:__
install `libappindicator1` to make the tray icon work.
* App indicator will only be shown when it has a context menu.
* When app indicator is used on Linux, the `click` event is ignored.
* On Linux in order for changes made to individual `MenuItem`s to take effect,
you have to call `setContextMenu` again. For example:
```javascript
contextMenu.items[2].checked = false;
appIcon.setContextMenu(contextMenu);
```
If you want to keep exact same behaviors on all platforms, you should not
rely on the `click` event and always attach a context menu to the tray icon.

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

@ -259,8 +259,8 @@ Returns:
* `result` Object
* `requestId` Integer
* `finalUpdate` Boolean - Indicates if more responses are to follow.
* `matches` Integer (Optional) - Number of Matches.
* `selectionArea` Object (Optional) - Coordinates of first match region.
* `matches` Integer (optional) - Number of Matches.
* `selectionArea` Object (optional) - Coordinates of first match region.
Emitted when a result is available for
[`webContents.findInPage`](web-contents.md#webcontentsfindinpage) request.
@ -310,7 +310,7 @@ The `webContents` object has the following instance methods:
### `webContents.loadURL(url[, options])`
* `url` URL
* `options` Object (optional), properties:
* `options` Object (optional)
* `httpReferrer` String - A HTTP Referrer url.
* `userAgent` String - A user agent originating the request.
* `extraHeaders` String - Extra headers separated by "\n"
@ -425,10 +425,12 @@ Returns a `String` representing the user agent for this web page.
Injects CSS into the current web page.
### `webContents.executeJavaScript(code[, userGesture])`
### `webContents.executeJavaScript(code[, userGesture, callback])`
* `code` String
* `userGesture` Boolean (optional)
* `callback` Function (optional) - Called after script has been executed.
* `result`
Evaluates `code` in page.
@ -503,7 +505,7 @@ Inserts `text` to the focused element.
### `webContents.findInPage(text[, options])`
* `text` String - Content to be searched, must not be empty.
* `options` Object (Optional)
* `options` Object (optional)
* `forward` Boolean - Whether to search forward or backward, defaults to `true`.
* `findNext` Boolean - Whether the operation is first request or a follow up,
defaults to `false`.
@ -556,11 +558,10 @@ when the JS promise is rejected.
### `webContents.print([options])`
`options` Object (optional), properties:
* `silent` Boolean - Don't ask user for print settings, defaults to `false`
* `printBackground` Boolean - Also prints the background color and image of
the web page, defaults to `false`.
* `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 window's web page. When `silent` is set to `false`, Electron will pick
up system's default printer and default settings for printing.
@ -574,31 +575,22 @@ size.
### `webContents.printToPDF(options, callback)`
`options` Object, properties:
* `marginsType` Integer - Specify the type of margins to use
* 0 - default
* 1 - none
* 2 - minimum
* `pageSize` String - Specify page size of the generated PDF.
* `A5`
* `A4`
* `A3`
* `Legal`
* `Letter`
* `Tabloid`
* `printBackground` Boolean - Whether to print CSS backgrounds.
* `printSelectionOnly` Boolean - Whether to print selection only.
* `landscape` Boolean - `true` for landscape, `false` for portrait.
`callback` Function - `function(error, data) {}`
* `error` Error
* `data` Buffer - PDF file content.
* `options` Object
* `marginsType` Integer - Specifies the type of margins to use. Uses 0 for
default margin, 1 for no margin, and 2 for minimum margin.
* `pageSize` String - Specify page size of the generated PDF. Can be `A3`,
`A4`, `A5`, `Legal`, `Letter` and `Tabloid`.
* `printBackground` Boolean - Whether to print CSS backgrounds.
* `printSelectionOnly` Boolean - Whether to print selection only.
* `landscape` Boolean - `true` for landscape, `false` for portrait.
* `callback` Function
Prints window's web page as PDF with Chromium's preview printing custom
settings.
The `callback` will be called with `callback(error, data)` on completion. The
`data` is a `Buffer` that contains the generated PDF data.
By default, an empty `options` will be regarded as:
```javascript
@ -651,7 +643,7 @@ Removes the specified path from DevTools workspace.
### `webContents.openDevTools([options])`
* `options` Object (optional). Properties:
* `options` Object (optional)
* `detach` Boolean - opens DevTools in a new window
Opens the devtools.
@ -693,8 +685,11 @@ Opens the developer tools for the service worker context.
* `arg` (optional)
Send an asynchronous message to renderer process via `channel`, you can also
send arbitrary arguments. The renderer process can handle the message by
listening to the `channel` event with the `ipcRenderer` module.
send arbitrary arguments. Arguments will be serialized in JSON internally and
hence no functions or prototype chain will be included.
The renderer process can handle the message by listening to `channel` with the
`ipcRenderer` module.
An example of sending messages from the main process to the renderer process:
@ -776,8 +771,10 @@ For keyboard events, the `event` object also have following properties:
* `keyCode` Char or String (**required**) - The character that will be sent
as the keyboard event. Can be a single UTF-8 character, or the name of the
key that generates the event. Accepted key names are `enter`, `backspace`,
`delete`, `tab`, `escape`, `control`, `alt`, `shift`, `end`, `home`, `insert`,
`left`, `up`, `right`, `down`, `pageUp`, `pageDown`, `printScreen`
`delete`, `tab`, `escape`, `control`, `alt`, `altgr` (Windows only), `shift`,
`end`, `home`, `insert`, `left`, `up`, `right`, `down`, `pageUp`, `pageDown`,
`printScreen`, `meta`, `cmd` (OSX only), `command` (OSX only), `option`
(OSX only)
For mouse events, the `event` object also have following properties:
@ -849,6 +846,10 @@ win.webContents.on('did-finish-load', function() {
Returns the [session](session.md) object used by this webContents.
### `webContents.hostWebContents`
Returns the `WebContents` that might own this `WebContents`.
### `webContents.devToolsWebContents`
Get the `WebContents` of DevTools for this `WebContents`.

18
docs/api/web-view-tag.md
View file

@ -184,7 +184,7 @@ webview.addEventListener("dom-ready", function() {
### `<webview>.loadURL(url[, options])`
* `url` URL
* `options` Object (optional), properties:
* `options` Object (optional)
* `httpReferrer` String - A HTTP Referrer url.
* `userAgent` String - A user agent originating the request.
* `extraHeaders` String - Extra headers separated by "\n"
@ -279,10 +279,12 @@ Returns a `String` representing the user agent for guest page.
Injects CSS into the guest page.
### `<webview>.executeJavaScript(code, userGesture)`
### `<webview>.executeJavaScript(code, userGesture, callback)`
* `code` String
* `userGesture` Boolean - Default `false`.
* `callback` Function (optional) - Called after script has been executed.
* `result`
Evaluates `code` in page. If `userGesture` is set, it will create the user
gesture context in the page. HTML APIs like `requestFullScreen`, which require
@ -382,7 +384,7 @@ Inserts `text` to the focused element.
### `<webview>.findInPage(text[, options])`
* `text` String - Content to be searched, must not be empty.
* `options` Object (Optional)
* `options` Object (optional)
* `forward` Boolean - Whether to search forward or backward, defaults to `true`.
* `findNext` Boolean - Whether the operation is first request or a follow up,
defaults to `false`.
@ -438,6 +440,10 @@ Sends an input `event` to the page.
See [webContents.sendInputEvent](web-contents.md##webcontentssendinputeventevent)
for detailed description of `event` object.
### `<webview>.getWebContents()`
Returns the [WebContents](web-contents.md) associated with this `webview`.
## DOM events
The following DOM events are available to the `webview` tag:
@ -522,7 +528,7 @@ Returns:
* `explicitSet` Boolean
Fired when page title is set during navigation. `explicitSet` is false when
title is synthesised from file url.
title is synthesized from file url.
### Event: 'page-favicon-updated'
@ -567,8 +573,8 @@ Returns:
* `result` Object
* `requestId` Integer
* `finalUpdate` Boolean - Indicates if more responses are to follow.
* `matches` Integer (Optional) - Number of Matches.
* `selectionArea` Object (Optional) - Coordinates of first match region.
* `matches` Integer (optional) - Number of Matches.
* `selectionArea` Object (optional) - Coordinates of first match region.
Fired when a result is available for
[`webview.findInPage`](web-view-tag.md#webviewtagfindinpage) request.