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

docs: Update with new IPC modules

Browse source
This commit is contained in:
Cheng Zhao 2015-11-10 16:48:24 +08:00
parent 05611f5e60
commit 90a7d4a906
7 changed files with 136 additions and 143 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/README.md
View file

@ -36,7 +36,7 @@
* [content-tracing](api/content-tracing.md)
* [dialog](api/dialog.md)
* [global-shortcut](api/global-shortcut.md)
* [ipc (main process)](api/ipc-main-process.md)
* [ipc-main](api/ipc-main.md)
* [menu](api/menu.md)
* [menu-item](api/menu-item.md)
* [power-monitor](api/power-monitor.md)
@ -48,7 +48,7 @@
### Modules for the Renderer Process (Web Page):
* [ipc (renderer)](api/ipc-renderer.md)
* [ipc-renderer](api/ipc-renderer.md)
* [remote](api/remote.md)
* [web-frame](api/web-frame.md)

76
docs/api/ipc-main-process.md
View file

@ -1,76 +0,0 @@
# ipc (main process)
The `ipc` module, when used in the main process, handles asynchronous and
synchronous messages sent from a renderer process (web page). Messages sent from
a renderer will be emitted to this 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-args)
for more information.
- When sending a message, the event name is the `channel`.
- To reply a synchronous message, you need to set `event.returnValue`.
- To send an asynchronous back to the sender, you can use
`event.sender.send(...)`.
An example of sending and handling messages between the render and main
processes:
```javascript
// In main process.
var ipc = require('ipc');
ipc.on('asynchronous-message', function(event, arg) {
console.log(arg); // prints "ping"
event.sender.send('asynchronous-reply', 'pong');
});
ipc.on('synchronous-message', function(event, arg) {
console.log(arg); // prints "ping"
event.returnValue = 'pong';
});
```
```javascript
// In renderer process (web page).
var ipc = require('ipc');
console.log(ipc.sendSync('synchronous-message', 'ping')); // prints "pong"
ipc.on('asynchronous-reply', function(arg) {
console.log(arg); // prints "pong"
});
ipc.send('asynchronous-message', 'ping');
```
## Listening for Messages
The `ipc` module has the following method to listen for events:
### `ipc.on(channel, callback)`
* `channel` String - The event name.
* `callback` Function
When the event occurs the `callback` is called with an `event` object and a
message, `arg`.
## IPC Events
The `event` object passed to the `callback` has the following methods:
### `Event.returnValue`
Set this to the value to be returned in a synchronous message.
### `Event.sender`
Returns the `WebContents` that sent the message.
### `Event.sender.send(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `arg` (optional)
This sends an asynchronous message back to the render process. Optionally, there
can be one or a series of arguments, `arg`, which can have any type.

71
docs/api/ipc-main.md Normal file
View file

@ -0,0 +1,71 @@
# ipcMain
The `ipcMain` module, when used in the main process, handles asynchronous and
synchronous messages sent from a renderer process (web page). Messages sent from
a renderer will be emitted to this module.
## Sending Messages
It is also possible to send messages from the main process to the renderer
process, see [WebContents.send][webcontents-send] for more information.
* When sending a message, the event name is the `channel`.
* To reply a synchronous message, you need to set `event.returnValue`.
* To send an asynchronous back to the sender, you can use
`event.sender.send(...)`.
An example of sending and handling messages between the render and main
processes:
```javascript
// In main process.
var ipcMain = require('ipc-main');
ipcMain.on('asynchronous-message', function(event, arg) {
console.log(arg); // prints "ping"
event.sender.send('asynchronous-reply', 'pong');
});
ipcMain.on('synchronous-message', function(event, arg) {
console.log(arg); // prints "ping"
event.returnValue = 'pong';
});
```
```javascript
// In renderer process (web page).
var ipcRenderer = require('ipc-renderer');
console.log(ipcRenderer.sendSync('synchronous-message', 'ping')); // prints "pong"
ipcRenderer.on('asynchronous-reply', function(event, arg) {
console.log(arg); // prints "pong"
});
ipcRenderer.send('asynchronous-message', 'ping');
```
## Listening for Messages
The `ipcMain` module has the following method to listen for events:
### `ipcMain.on(channel, callback)`
* `channel` String - The event name.
* `callback` Function
When the event occurs the `callback` is called with an `event` object and a
message, `arg`.
## IPC Event
The `event` object passed to the `callback` has the following methods:
### `event.returnValue`
Set this to the value to be returned in a synchronous message.
### `event.sender`
Returns the `webContents` that sent the message, you can call
`event.sender.send` to reply to the asynchronous message, see
[WebContents.send][webcontents-send] for more information.
[webcontents-send]: web-contents.md#webcontentssendchannel-args

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

@ -1,52 +1,55 @@
# ipc (renderer)
# ipcRenderer
The `ipc` module provides a few methods so you can send synchronous and
The `ipcRenderer` module provides a few methods so you can send synchronous and
asynchronous messages from the render process (web page) to the main process.
You can also receive replies from the main process.
**Note:** If you want to make use of modules in the main process from the renderer
process, you might consider using the [remote](remote.md) module.
See [ipcMain](ipc-main.md) for code examples.
See [ipc (main process)](ipc-main-process.md) for code examples.
## Listening for Messages
## Methods
The `ipcRenderer` module has the following method to listen for events:
The `ipc` module has the following methods for sending messages:
### `ipcRenderer.on(channel, callback)`
**Note:** When using these methods to send a `message` you must also listen
for it in the main process with [`ipc (main process)`](ipc-main-process.md).
* `channel` String - The event name.
* `callback` Function
### `ipc.send(channel[, arg1][, arg2][, ...])`
When the event occurs the `callback` is called with an `event` object and
arbitrary arguments.
## Sending Messages
The `ipcRenderer` module has the following methods for sending messages:
### `ipcRenderer.send(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `arg` (optional)
Send an event to the main process asynchronously via a `channel`. Optionally,
there can be a message: one or a series of arguments, `arg`, which can have any
type. The main process handles it by listening for the `channel` event with
`ipc`.
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`.
### `ipc.sendSync(channel[, arg1][, arg2][, ...])`
### `ipcRenderer.sendSync(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `arg` (optional)
Send an event to the main process synchronously via a `channel`. Optionally,
there can be a message: one or a series of arguments, `arg`, which can have any
type. The main process handles it by listening for the `channel` event with
`ipc`.
Send an event to the main process synchronously via a `channel`, you can also
send arbitrary arguments. The main process handles it by listening for the
`channel` event with `ipcMain`.
The main process handles it by listening for the `channel` event with `ipc` and
replies by setting the `event.returnValue`.
**Note:** Sending a synchronous message will block the whole renderer process so
using this method is not recommended.
__Note:__ Sending a synchronous message will block the whole renderer process,
unless you know what you are doing you should never use it.
### `ipc.sendToHost(channel[, arg1][, arg2][, ...])`
### `ipcRenderer.sendToHost(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `arg` (optional)
Like `ipc.send` but the event will be sent to the host page in a `<webview>`
instead of the main process. Optionally, there can be a message: one or a series
of arguments, `arg`, which can have any type.
Like `ipcRenderer.send` but the event will be sent to the `<webview>` element in
the host page instead of the main process.

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

@ -510,13 +510,14 @@ Starts inspecting element at position (`x`, `y`).
Opens the developer tools for the service worker context.
### `webContents.send(channel[, args...])`
### `webContents.send(channel[, arg1][, arg2][, ...])`
* `channel` String
* `args...` (optional)
* `arg` (optional)
Send `args...` to the web page via `channel` in an asynchronous message, the web
page can handle it by listening to the `channel` event of the `ipc` module.
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.
An example of sending messages from the main process to the renderer process:
@ -537,7 +538,7 @@ app.on('ready', function() {
<html>
<body>
<script>
require('ipc').on('ping', function(message) {
require('ipcRenderer').on('ping', function(event, message) {
console.log(message); // Prints "whoooooooh!"
});
</script>
@ -545,13 +546,6 @@ app.on('ready', function() {
</html>
```
**Note:**
1. The IPC message handler in web pages does not have an `event` parameter,
which is different from the handlers in the main process.
2. There is no way to send synchronous messages from the main process to a
renderer process, because it would be very easy to cause dead locks.
### `webContents.enableDeviceEmulation(parameters)`
`parameters` Object, properties:

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

@ -355,15 +355,16 @@ Prints `webview`'s web page. Same with `webContents.print([options])`.
Prints webview's web page as PDF, Same with `webContents.printToPDF(options, callback)`
### `<webview>.send(channel[, args...])`
### `<webview>.send(channel[, arg1][, arg2][, ...])`
* `channel` String
* `arg` (optional)
Send `args..` to guest page via `channel` in asynchronous message, the guest
page can handle it by listening to the `channel` event of `ipc` module.
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.
See [WebContents.send](web-contents.md#webcontentssendchannel-args) for
See [webContents.send](web-contents.md#webcontentssendchannel-args) for
examples.
### `<webview>.sendInputEvent(event)`
@ -372,7 +373,7 @@ examples.
Sends an input `event` to the page.
See [WebContents.sendInputEvent](web-contents.md##webcontentssendinputeventevent)
See [webContents.sendInputEvent](web-contents.md##webcontentssendinputeventevent)
for detailed description of `event` object.
## DOM events

46
docs/tutorial/online-offline-events.md
View file

@ -21,18 +21,18 @@ _online-status.html_
```html
<!DOCTYPE html>
<html>
<body>
<script>
var alertOnlineStatus = function() {
window.alert(navigator.onLine ? 'online' : 'offline');
};
<body>
<script>
var alertOnlineStatus = function() {
window.alert(navigator.onLine ? 'online' : 'offline');
};
window.addEventListener('online', alertOnlineStatus);
window.addEventListener('offline', alertOnlineStatus);
window.addEventListener('online', alertOnlineStatus);
window.addEventListener('offline', alertOnlineStatus);
alertOnlineStatus();
</script>
</body>
alertOnlineStatus();
</script>
</body>
</html>
```
@ -46,7 +46,7 @@ _main.js_
```javascript
var app = require('app');
var ipc = require('ipc');
var ipcMain = require('ipc-main');
var BrowserWindow = require('browser-window');
var onlineStatusWindow;
@ -55,7 +55,7 @@ app.on('ready', function() {
onlineStatusWindow.loadUrl('file://' + __dirname + '/online-status.html');
});
ipc.on('online-status-changed', function(event, status) {
ipcMain.on('online-status-changed', function(event, status) {
console.log(status);
});
```
@ -65,18 +65,18 @@ _online-status.html_
```html
<!DOCTYPE html>
<html>
<body>
<script>
var ipc = require('ipc');
var updateOnlineStatus = function() {
ipc.send('online-status-changed', navigator.onLine ? 'online' : 'offline');
};
<body>
<script>
var ipcRenderer = require('ipc-renderer');
var updateOnlineStatus = function() {
ipcRenderer.send('online-status-changed', navigator.onLine ? 'online' : 'offline');
};
window.addEventListener('online', updateOnlineStatus);
window.addEventListener('offline', updateOnlineStatus);
window.addEventListener('online', updateOnlineStatus);
window.addEventListener('offline', updateOnlineStatus);
updateOnlineStatus();
</script>
</body>
updateOnlineStatus();
</script>
</body>
</html>
```