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

docs: Cleanup the IPC docs

Browse source
This commit is contained in:
Cheng Zhao 2016-02-16 11:34:39 +08:00
parent 63578f9d2b
commit b8e8e4c930
3 changed files with 61 additions and 53 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -9,7 +9,7 @@ module.
## Sending Messages ## Sending Messages
It is also possible to send messages from the main process to the renderer 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`. * When sending a message, the event name is the `channel`.
* To reply a synchronous message, you need to set `event.returnValue`. * 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: The `ipcMain` module has the following method to listen for events:
### `ipcMain.on(channel, callback)` ### `ipcMain.on(channel, listener)`
* `channel` String - The event name. * `channel` String
* `callback` Function * `listener` Function
When the event occurs the `callback` is called with an `event` object and Listens to `channel`, when a new message arrives `listener` would be called with
arbitrary arguments. `listener(event, args...)`.
### `ipcMain.removeListener(channel, callback)` ### `ipcMain.once(channel, listener)`
* `channel` String - The event name. * `channel` String
* `callback` Function - The reference to the same function that you used for * `listener` Function
`ipcMain.on(channel, callback)`
Once done listening for messages, if you no longer want to activate this Adds a one time `listener` function for the event. This `listener` is invoked
callback and for whatever reason can't merely stop sending messages on the only the next time a message is sent to `channel`, after which it is removed.
channel, this function will remove the callback handler for the specified
channel.
### `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, * `channel` String (optional)
as in, they won't be activated after one call of `callback`
## IPC Event Removes all listeners, or those of the specified `channel`.
## Event object
The `event` object passed to the `callback` has the following methods: 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 Returns the `webContents` that sent the message, you can call
`event.sender.send` to reply to the asynchronous message, see `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: The `ipcRenderer` module has the following method to listen for events:
### `ipcRenderer.on(channel, callback)` ### `ipcRenderer.on(channel, listener)`
* `channel` String - The event name. * `channel` String
* `callback` Function * `listener` Function
When the event occurs the `callback` is called with an `event` object and Listens to `channel`, when a new message arrives `listener` would be called with
arbitrary arguments. `listener(event, args...)`.
### `ipcRenderer.removeListener(channel, callback)` ### `ipcRenderer.once(channel, listener)`
* `channel` String - The event name. * `channel` String
* `callback` Function - The reference to the same function that you used for * `listener` Function
`ipcRenderer.on(channel, callback)`
Once done listening for messages, if you no longer want to activate this Adds a one time `listener` function for the event. This `listener` is invoked
callback and for whatever reason can't merely stop sending messages on the only the next time a message is sent to `channel`, after which it is removed.
channel, this function will remove the callback handler for the specified
channel.
### `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, * `channel` String (optional)
as in, they won't be activated after one call of `callback`
Removes all listeners, or those of the specified `channel`.
## Sending Messages ## Sending Messages
@ -48,30 +48,33 @@ The `ipcRenderer` module has the following methods for sending messages:
### `ipcRenderer.send(channel[, arg1][, arg2][, ...])` ### `ipcRenderer.send(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name. * `channel` String
* `arg` (optional) * `arg` (optional)
Send an event to the main process asynchronously via a `channel`, you can also Send a message to the main process asynchronously via `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 send arbitrary arguments. Arguments will be serialized in JSON internally and
`channel` event with `ipcMain`. 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][, ...])` ### `ipcRenderer.sendSync(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name. * `channel` String
* `arg` (optional) * `arg` (optional)
Send an event to the main process synchronously via a `channel`, you can also Send a message to the main process synchronously via `channel`, you can also
send arbitrary arguments. 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 The main process handles it by listening for `channel` with `ipcMain` module,
`ipcMain` and replies by setting `event.returnValue`. and replies by setting `event.returnValue`.
__Note:__ Sending a synchronous message will block the whole renderer process, __Note:__ Sending a synchronous message will block the whole renderer process,
unless you know what you are doing you should never use it. unless you know what you are doing you should never use it.
### `ipcRenderer.sendToHost(channel[, arg1][, arg2][, ...])` ### `ipcRenderer.sendToHost(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name. * `channel` String
* `arg` (optional) * `arg` (optional)
Like `ipcRenderer.send` but the event will be sent to the `<webview>` element in Like `ipcRenderer.send` but the event will be sent to the `<webview>` element in

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

@ -693,8 +693,11 @@ Opens the developer tools for the service worker context.
* `arg` (optional) * `arg` (optional)
Send an asynchronous message to renderer process via `channel`, you can also 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 send arbitrary arguments. Arguments will be serialized in JSON internally and
listening to the `channel` event with the `ipcRenderer` module. 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: An example of sending messages from the main process to the renderer process: