From f96c76584f21626a2eb054ef844444f16e744590 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Wed, 26 Aug 2015 17:27:17 -0700 Subject: [PATCH 1/7] First run at ipc-m-p edits --- docs/api/ipc-main-process.md | 52 ++++++++++++++++++++++++++---------- 1 file changed, 38 insertions(+), 14 deletions(-) diff --git a/docs/api/ipc-main-process.md b/docs/api/ipc-main-process.md index d558f7fb24d..b29d56f6ba3 100644 --- a/docs/api/ipc-main-process.md +++ b/docs/api/ipc-main-process.md @@ -1,17 +1,19 @@ # ipc (main process) -Handles asynchronous and synchronous message sent from a renderer process (web -page). +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. -The messages sent from a renderer would be emitted to this module, the event name -is the `channel` when sending message. 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(...)`. +## Sending Messages -It's also possible to send messages from main process to the renderer process, -see [WebContents.send](browser-window.md#webcontentssendchannel-args) for more. +It is also possible to send messages from the main process to the renderer +process, see [WebContents.send](browser-window.md#webcontentssendchannel-args) +for more information. -An example of sending and handling messages: +- 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. @@ -38,12 +40,34 @@ ipc.on('asynchronous-reply', function(arg) { ipc.send('asynchronous-message', 'ping'); ``` -## Class: Event +## Methods -### Event.returnValue +The `ipc` module has the following method: -Assign to this to return an value to synchronous messages. +### `ipc.on(channel, callback)` -### Event.sender +* `channel` String - The event name. +* `callback` Function -The `WebContents` that sent the message. +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, arg)` + +* `channel` String - The event name. +* `arg` + +This sends an asynchronous message back to the render process. The message, +`arg`, can be any value. From a34a16653eb50529c42d92933ba94cca0b3b6e0f Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Wed, 26 Aug 2015 17:32:47 -0700 Subject: [PATCH 2/7] Standardize global-shortcut --- docs/api/global-shortcut.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/api/global-shortcut.md b/docs/api/global-shortcut.md index 54da5638d19..52ec17326c6 100644 --- a/docs/api/global-shortcut.md +++ b/docs/api/global-shortcut.md @@ -1,9 +1,12 @@ # global-shortcut The `global-shortcut` module can register/unregister a global keyboard shortcut -with the operating system, so that you can customize the operations for various shortcuts. -Note that the shortcut is global; it will work even if the app does not have the keyboard focus. -You should not use this module until the `ready` event of the app module is emitted. +with the operating system so that you can customize the operations for various +shortcuts. + +Note that the shortcut is global; it will work even if the app does +not have the keyboard focus. You should not use this module until the `ready` +event of the app module is emitted. ```javascript var app = require('app'); @@ -32,7 +35,11 @@ app.on('will-quit', function() { }); ``` -## globalShortcut.register(accelerator, callback) +## Methods + +The `global-shortcut` module has the following methods: + +### `globalShortcut.register(accelerator, callback)` * `accelerator` [Accelerator](accelerator.md) * `callback` Function @@ -40,18 +47,18 @@ app.on('will-quit', function() { Registers a global shortcut of `accelerator`. The `callback` is called when the registered shortcut is pressed by the user. -## globalShortcut.isRegistered(accelerator) +### `globalShortcut.isRegistered(accelerator)` * `accelerator` [Accelerator](accelerator.md) Returns `true` or `false` depending on whether the shortcut `accelerator` is registered. -## globalShortcut.unregister(accelerator) +### `globalShortcut.unregister(accelerator)` * `accelerator` [Accelerator](accelerator.md) -Unregisters the global shortcut of `keycode`. +Unregisters the global shortcut of `accelerator`. -## globalShortcut.unregisterAll() +### `globalShortcut.unregisterAll()` Unregisters all the global shortcuts. From 71f46c02877fd1d42b5e6de195572ab2727d2503 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Wed, 26 Aug 2015 17:52:45 -0700 Subject: [PATCH 3/7] =?UTF-8?q?arg=20=E2=86=92=20message?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api/ipc-main-process.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/api/ipc-main-process.md b/docs/api/ipc-main-process.md index b29d56f6ba3..197b98e418b 100644 --- a/docs/api/ipc-main-process.md +++ b/docs/api/ipc-main-process.md @@ -64,10 +64,9 @@ Set this to the value to be returned in a synchronous message. Returns the `WebContents` that sent the message. -### `Event.sender.send(channel, arg)` +### `Event.sender.send(channel[, message])` * `channel` String - The event name. -* `arg` +* `message` (optional) -This sends an asynchronous message back to the render process. The message, -`arg`, can be any value. +This sends an asynchronous message back to the render process. The `message` can be any value. From a1f17069ec3a742bc83697c4bbf4c73a1a669834 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Wed, 26 Aug 2015 17:56:10 -0700 Subject: [PATCH 4/7] First run t ipc-r --- docs/api/ipc-renderer.md | 44 +++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/docs/api/ipc-renderer.md b/docs/api/ipc-renderer.md index 3aee11d781c..0d7b49aba70 100644 --- a/docs/api/ipc-renderer.md +++ b/docs/api/ipc-renderer.md @@ -1,29 +1,41 @@ # ipc (renderer) The `ipc` module provides a few methods so you can send synchronous and -asynchronous messages to the main process, and also receive messages sent from -main process. If you want to make use of modules of main process from renderer +asynchronous messages from the render process (web page) to the main process. You can also receive messages returned 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 [ipc (main process)](ipc-main-process.md) for examples. +See [ipc (main process)](ipc-main-process.md) for code examples. -## ipc.send(channel[, args...]) +## Methods -Send `args..` to the renderer via `channel` in asynchronous message, the main -process can handle it by listening to the `channel` event of `ipc` module. +The `ipc` module has the following methods for sending messages: -## ipc.sendSync(channel[, args...]) +**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). -Send `args..` to the renderer via `channel` in synchronous message, and returns -the result sent from main process. The main process can handle it by listening to -the `channel` event of `ipc` module, and returns by setting `event.returnValue`. +### `ipc.send(channel[, message])` -**Note:** Usually developers should never use this API, since sending -synchronous message would block the whole renderer process. +* `channel` String - The event name. +* `message` (optional) -## ipc.sendToHost(channel[, args...]) +Send a `message` (any type) to the main process asynchronously via a `channel`. The main process handles it by listening for the `channel` event with `ipc`. -Like `ipc.send` but the message will be sent to the host page instead of the -main process. +### `ipc.sendSync(channel[, message])` -This is mainly used by the page in `` to communicate with host page. +* `channel` String - The event name. +* `message` (optional) + +Send a `message` (any type) to the main process synchronously via a `channel`. A result is returned from the main process. + +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. + +### `ipc.sendToHost(channel[, message])` + +* `channel` String - The event name. +* `message` (optional) + +Like `ipc.send` but the message will be sent to the host page in a `` instead of the main process. From d02ced87b8481262f489ae4d87ff5366459ea263 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Thu, 27 Aug 2015 10:13:25 -0700 Subject: [PATCH 5/7] =?UTF-8?q?message=20=E2=86=92=20arg,=2080-col?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api/ipc-main-process.md | 7 ++++--- docs/api/ipc-renderer.md | 29 ++++++++++++++++++++--------- 2 files changed, 24 insertions(+), 12 deletions(-) diff --git a/docs/api/ipc-main-process.md b/docs/api/ipc-main-process.md index 197b98e418b..c34564ef82e 100644 --- a/docs/api/ipc-main-process.md +++ b/docs/api/ipc-main-process.md @@ -64,9 +64,10 @@ Set this to the value to be returned in a synchronous message. Returns the `WebContents` that sent the message. -### `Event.sender.send(channel[, message])` +### `Event.sender.send(channel[, arg1][, arg2][, ...])` * `channel` String - The event name. -* `message` (optional) +* `arg` (optional) -This sends an asynchronous message back to the render process. The `message` can be any value. +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-renderer.md b/docs/api/ipc-renderer.md index 0d7b49aba70..4a599566388 100644 --- a/docs/api/ipc-renderer.md +++ b/docs/api/ipc-renderer.md @@ -1,7 +1,8 @@ # ipc (renderer) The `ipc` 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 messages returned from the main process. +asynchronous messages from the render process (web page) to the main process. +You can also receive messages returned 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. @@ -12,30 +13,40 @@ See [ipc (main process)](ipc-main-process.md) for code examples. The `ipc` module has the following methods for sending messages: -**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). +**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). -### `ipc.send(channel[, message])` +### `ipc.send(channel[, arg1][, arg2][, ...])` * `channel` String - The event name. * `message` (optional) -Send a `message` (any type) to the main process asynchronously via a `channel`. The main process handles it by listening for the `channel` event with `ipc`. +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`. -### `ipc.sendSync(channel[, message])` +### `ipc.sendSync(channel[, arg1][, arg2][, ...])` * `channel` String - The event name. * `message` (optional) -Send a `message` (any type) to the main process synchronously via a `channel`. A result is returned from the main process. +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`. -The main process handles it by listening for the `channel` event with `ipc` and replies by setting the `event.returnValue`. +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. -### `ipc.sendToHost(channel[, message])` +### `ipc.sendToHost(channel[, arg1][, arg2][, ...])` * `channel` String - The event name. * `message` (optional) -Like `ipc.send` but the message will be sent to the host page in a `` instead of the main process. +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. From dbc1855b42a4aaeeb2bc5d35f3e3f9cd179509da Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Fri, 28 Aug 2015 14:21:37 -0700 Subject: [PATCH 6/7] Small edits --- docs/api/global-shortcut.md | 5 +++-- docs/api/ipc-main-process.md | 11 +++++++---- docs/api/ipc-renderer.md | 2 +- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/api/global-shortcut.md b/docs/api/global-shortcut.md index 52ec17326c6..f9ca654cf50 100644 --- a/docs/api/global-shortcut.md +++ b/docs/api/global-shortcut.md @@ -4,7 +4,7 @@ The `global-shortcut` module can register/unregister a global keyboard shortcut with the operating system so that you can customize the operations for various shortcuts. -Note that the shortcut is global; it will work even if the app does +**Note**: The shortcut is global; it will work even if the app does not have the keyboard focus. You should not use this module until the `ready` event of the app module is emitted. @@ -51,7 +51,8 @@ the registered shortcut is pressed by the user. * `accelerator` [Accelerator](accelerator.md) -Returns `true` or `false` depending on whether the shortcut `accelerator` is registered. +Returns `true` or `false` depending on whether the shortcut `accelerator` is +registered. ### `globalShortcut.unregister(accelerator)` diff --git a/docs/api/ipc-main-process.md b/docs/api/ipc-main-process.md index c34564ef82e..bbb581fcfc9 100644 --- a/docs/api/ipc-main-process.md +++ b/docs/api/ipc-main-process.md @@ -1,6 +1,8 @@ # 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. +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 @@ -10,7 +12,8 @@ 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(...)`. +- 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: @@ -40,9 +43,9 @@ ipc.on('asynchronous-reply', function(arg) { ipc.send('asynchronous-message', 'ping'); ``` -## Methods +## Listening for Messages -The `ipc` module has the following method: +The `ipc` module has the following method to listen for events: ### `ipc.on(channel, callback)` diff --git a/docs/api/ipc-renderer.md b/docs/api/ipc-renderer.md index 4a599566388..12cd11aec77 100644 --- a/docs/api/ipc-renderer.md +++ b/docs/api/ipc-renderer.md @@ -2,7 +2,7 @@ The `ipc` 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 messages returned from 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. From 8ee91bce44798a64fe969c7b5f1ba4d6e230c373 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Fri, 28 Aug 2015 14:57:14 -0700 Subject: [PATCH 7/7] =?UTF-8?q?message=20=E2=86=92=20arg?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api/ipc-renderer.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/ipc-renderer.md b/docs/api/ipc-renderer.md index 12cd11aec77..3adb0bc9547 100644 --- a/docs/api/ipc-renderer.md +++ b/docs/api/ipc-renderer.md @@ -19,7 +19,7 @@ for it in the main process with [`ipc (main process)`](ipc-main-process.md). ### `ipc.send(channel[, arg1][, arg2][, ...])` * `channel` String - The event name. -* `message` (optional) +* `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 @@ -29,7 +29,7 @@ type. The main process handles it by listening for the `channel` event with ### `ipc.sendSync(channel[, arg1][, arg2][, ...])` * `channel` String - The event name. -* `message` (optional) +* `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 @@ -45,7 +45,7 @@ using this method is not recommended. ### `ipc.sendToHost(channel[, arg1][, arg2][, ...])` * `channel` String - The event name. -* `message` (optional) +* `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