diff --git a/docs/README.md b/docs/README.md index 754048f5e3f3..fb5c64a8f17e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) diff --git a/docs/api/ipc-main-process.md b/docs/api/ipc-main-process.md deleted file mode 100644 index 98d9c3c22d43..000000000000 --- a/docs/api/ipc-main-process.md +++ /dev/null @@ -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. diff --git a/docs/api/ipc-main.md b/docs/api/ipc-main.md new file mode 100644 index 000000000000..4f3d6ebc3bf7 --- /dev/null +++ b/docs/api/ipc-main.md @@ -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 diff --git a/docs/api/ipc-renderer.md b/docs/api/ipc-renderer.md index 752af2ebe293..e591f9e0bca2 100644 --- a/docs/api/ipc-renderer.md +++ b/docs/api/ipc-renderer.md @@ -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 `` -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 `` element in +the host page instead of the main process. diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 52a06b87edb1..d62706b2ba9a 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -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() { @@ -545,13 +546,6 @@ app.on('ready', function() { ``` -**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: diff --git a/docs/api/web-view-tag.md b/docs/api/web-view-tag.md index 3fda3a98edb5..9a0e0be33b36 100644 --- a/docs/api/web-view-tag.md +++ b/docs/api/web-view-tag.md @@ -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)` -### `.send(channel[, args...])` +### `.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. ### `.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 diff --git a/docs/tutorial/online-offline-events.md b/docs/tutorial/online-offline-events.md index 88f9a32f2ec6..46d659e07d05 100644 --- a/docs/tutorial/online-offline-events.md +++ b/docs/tutorial/online-offline-events.md @@ -21,18 +21,18 @@ _online-status.html_ ```html - - - + alertOnlineStatus(); + + ``` @@ -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 - - - + updateOnlineStatus(); + + ```