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

Merge pull request #4497 from atom/docs-revise

Browse source 
Improve the IPC related docs
This commit is contained in:
Cheng Zhao 2016-02-16 12:20:00 +08:00
commit 95d8716ffa
8 changed files with 151 additions and 157 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -458,7 +458,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
@ -478,13 +478,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`.
@ -729,7 +727,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
@ -802,27 +800,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
@ -833,6 +811,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.

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. Arguments will be serialized (json) and hence no functions or prototype chain will be included. 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

59
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"
@ -503,7 +503,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 +556,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 +573,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 +641,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 +683,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. Arguments will be serialized (json) and hence no functions or prototype chain will be included. 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:

8
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"
@ -382,7 +382,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`.
@ -567,8 +567,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.

40
docs/faq/electron-faq.md
View file

@ -18,40 +18,34 @@ New features of Node.js are usually brought by V8 upgrades, since Electron is
using the V8 shipped by Chrome browser, the shiny new JavaScript feature of a
new Node.js version is usually already in Electron.
## What are the different techniques to share objects between web pages?
## How to share data between web pages?
To share objects between web pages (that is on the renderer side) the simplest
and more natural technique is to use a web standard API already available in all
browsers. A good candidate is the
[Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Storage),
through either the
[`window.localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) property or the
[`window.sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) property.
Note that the Storage API allows only to store strings, so objects must be
serialized as JSON.
Another candidate is
[IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
To share data between web pages (the renderer processes) the simplest way is to
use HTML5 APIs which are already available in browsers. Good candidates are
[Storage API][storage], [`localStorage`][local-storage],
[`sessionStorage`][session-storage], and [IndexedDB][indexed-db].
Another technique, but this time specific to Electron, is to store objects in
the main process as a global variable and then to access them from the renderers
through the `remote` module:
Or you can use the IPC system, which are specific to Electron, to store objects
in the main process as a global variable, and then to access them from the
renderers through the `remote` module:
```javascript
// In main.js of browser process
global.sharedObject = {};
// In the main process.
global.sharedObject = {
someProperty: 'default value'
};
```
```javascript
// js in page-1.html
require('remote').getGlobal('sharedObject').someProperty = 'some value';
// In page 1.
require('remote').getGlobal('sharedObject').someProperty = 'new value';
```
```javascript
// js in page-2.html
// In page 2.
console.log(require('remote').getGlobal('sharedObject').someProperty);
```
## My app's window/tray disappeared after a few minutes.
This happens when the variable which is used to store the window/tray gets
@ -154,3 +148,7 @@ is only available in renderer processes.
[memory-management]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_Management
[variable-scope]: https://msdn.microsoft.com/library/bzt2dkta(v=vs.94).aspx
[electron-module]: https://www.npmjs.com/package/electron
[storage]: https://developer.mozilla.org/en-US/docs/Web/API/Storage
[local-storage]: https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage
[session-storage]: https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage
[indexed-db]: https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API

18
docs/tutorial/quick-start.md
View file

@ -34,8 +34,8 @@ The main process creates web pages by creating `BrowserWindow` instances. Each
is also terminated.
The main process manages all web pages and their corresponding renderer
processes. Each renderer process is isolated and only cares
about the web page running in it.
processes. Each renderer process is isolated and only cares about the web page
running in it.
In web pages, calling native GUI related APIs is not allowed because managing
native GUI resources in web pages is very dangerous and it is easy to leak
@ -43,13 +43,11 @@ resources. If you want to perform GUI operations in a web page, the renderer
process of the web page must communicate with the main process to request that
the main process perform those operations.
In Electron, we have provided the [ipc](../api/ipc-renderer.md) module for
communication between the main process and renderer process. There is also a
[remote](../api/remote.md) module for RPC style communication.
And finally there are different techniques [to share objects between web
pages](../faq/electron-faq.md#what-are-the-different-techniques-to-share-objects-between-web-pages)
of the same window or of different windows.
In Electron, we have several ways to communicate between the main process and
renderer processes. Like [`ipcRenderer`](../api/ipc-renderer.md) and
[`ipcMain`](../api/ipc-main.md) modules for sending messages, and the
[remote](../api/remote.md) module for RPC style communication. There is also
an FAQ entry on [how to share data between web pages][share-data].
## Write your First Electron App
@ -209,3 +207,5 @@ $ cd electron-quick-start
# Install dependencies and run the app
$ npm install && npm start
```
[share-data]: ../faq/electron-faq.md#how-to-share-data-between-web-pages