doc: Separate pages into sub directories.
This commit is contained in:
parent
6b81070f67
commit
92241b91ce
21 changed files with 20 additions and 20 deletions
79
docs/api/renderer/ipc-renderer.md
Normal file
79
docs/api/renderer/ipc-renderer.md
Normal file
|
@ -0,0 +1,79 @@
|
|||
# ipc (renderer)
|
||||
|
||||
The `ipc` module provides a few methods so you can send synchronous and
|
||||
asynchronous messages to the browser, and also receive messages sent from
|
||||
browser. If you want to make use of modules of browser from renderer, you
|
||||
might consider using the [remote](remote.md) module.
|
||||
|
||||
An example of echoing messages between browser and renderer:
|
||||
|
||||
```javascript
|
||||
// In browser:
|
||||
var ipc = require('ipc');
|
||||
ipc.on('message', function(processId, routingId, m) {
|
||||
ipc.send(processId, routingId, m);
|
||||
});
|
||||
```
|
||||
|
||||
```javascript
|
||||
// In renderer:
|
||||
var ipc = require('ipc');
|
||||
ipc.on('message', function(m) {
|
||||
console.log('Received message', m);
|
||||
});
|
||||
ipc.send('Hello world');
|
||||
```
|
||||
|
||||
An example of sending synchronous message from renderer to browser:
|
||||
|
||||
```javascript
|
||||
// In browser:
|
||||
var ipc = require('ipc');
|
||||
ipc.on('browser-data-request', function(event, processId, routingId, message) {
|
||||
event.result = 'THIS SOME DATA FROM THE BROWSER';
|
||||
});
|
||||
```
|
||||
|
||||
```javascript
|
||||
// In renderer:
|
||||
var ipc = require('ipc');
|
||||
console.log(ipc.sendChannelSync('browser-data-request', 'THIS IS FROM THE RENDERER'));
|
||||
```
|
||||
|
||||
## Event: 'message'
|
||||
|
||||
Emitted when browser sent a message to this window.
|
||||
|
||||
## ipc.send([args...])
|
||||
|
||||
Send all arguments to the browser and return immediately, the browser should
|
||||
handle the message by listening to the `message` event.
|
||||
|
||||
## ipc.sendSync([args...])
|
||||
|
||||
Send all arguments to the browser synchronously, and returns the result sent
|
||||
from browser. The browser should handle the message by listening to the
|
||||
`sync-message` event.
|
||||
|
||||
**Note:** Usually developers should never use this API, since sending
|
||||
synchronous message would block the browser.
|
||||
|
||||
## ipc.sendChannel(channel, [args...])
|
||||
|
||||
* `channel` String
|
||||
|
||||
This is the same with `ipc.send`, except that the browser should listen to the
|
||||
`channel` event. The `ipc.send(args...)` can be seen as
|
||||
`ipc.sendChannel('message', args...)`.
|
||||
|
||||
|
||||
## ipc.sendChannelSync(channel, [args...])
|
||||
|
||||
* `channel` String
|
||||
|
||||
This is the same with `ipc.sendSync`, except that the browser should listen to
|
||||
the `channel` event. The `ipc.sendSync(args...)` can be seen as
|
||||
`ipc.sendChannelSync('sync-message', args...)`.
|
||||
|
||||
**Note:** Usually developers should never use this API, since sending
|
||||
synchronous message would block the browser.
|
82
docs/api/renderer/remote.md
Normal file
82
docs/api/renderer/remote.md
Normal file
|
@ -0,0 +1,82 @@
|
|||
# remote
|
||||
|
||||
It's common that the developers want to use modules in browsers from the
|
||||
renderer, like closing current window, opening file dialogs, etc. Instead of
|
||||
writing IPC code for every operation you want to do, atom-shell provides the
|
||||
`remote` module to let you do RPC call just like using normal javascript
|
||||
objects.
|
||||
|
||||
An example of creating a window in renderer:
|
||||
|
||||
```javascript
|
||||
var remote = require('remote');
|
||||
var BrowserWindow = remote.require('browser-window');
|
||||
var win = new BrowserWindow({ width: 800, height: 600 });
|
||||
win.loadUrl('https://github.com');
|
||||
```
|
||||
|
||||
## Lifetime of remote objects
|
||||
|
||||
Every object returned by `remote` module represents an object in browser (e.g.
|
||||
a remote object), so when you call methods of an object, or call a returned
|
||||
function, or even create a object with the returned constructor, you are
|
||||
indeed making a synchronous RPC call. And when the renderer releases the last
|
||||
reference to the remote object, the browser would release the corresponding
|
||||
reference too.
|
||||
|
||||
This also means that, if the renderer keeps a reference to an object in
|
||||
browser, the object would never be released. So be careful to never leak the
|
||||
remote objects.
|
||||
|
||||
## Passing callbacks
|
||||
|
||||
Many APIs in browser accepts callbacks, so the `remote` module also supports
|
||||
passing callbacks when calling remote functions, and the callbacks passed
|
||||
would become remote functions in the browser.
|
||||
|
||||
But in order to avoid possible dead locks, the callbacks passed to browser
|
||||
would be called asynchronously in browser, so you should never expect the
|
||||
browser to get the return value of the passed callback.
|
||||
|
||||
Another thing is the lifetime of the remote callbacks in browser, it might be
|
||||
very tempting to do things like following:
|
||||
|
||||
```javascript
|
||||
var remote = require('remote');
|
||||
remote.getCurrentWindow().on('close', function() {
|
||||
// blabla...
|
||||
});
|
||||
```
|
||||
|
||||
Yes it will work correctly, but when you reload the window, the callback you
|
||||
setup on the object in browser will not be erased, resources are leaked and
|
||||
there is no magic in javascript to release a referenced object.
|
||||
|
||||
So if you really need to keep a reference of callbacks in browser, you should
|
||||
write the callback in browser and send messages to renderer. And also make use
|
||||
of DOM's events like `unload` and `beforeunload`, they will work perfectly.
|
||||
|
||||
## remote.require(module)
|
||||
|
||||
* `module` String
|
||||
|
||||
Return a module in browser.
|
||||
|
||||
## remote.getCurrentWindow()
|
||||
|
||||
Return the `BrowserWindow` object that represents current window.
|
||||
|
||||
`Note:` it doesn't return the `window` object which represents the global
|
||||
scope, instead it returns an instance of the `BrowserWindow` class which is
|
||||
created with `browser-window` module in browser.
|
||||
|
||||
## remote.getGlobal(name)
|
||||
|
||||
* `name` String
|
||||
|
||||
Return the `global[name]` value in browser.
|
||||
|
||||
## remote.process
|
||||
|
||||
Getter to return the `process` object in browser, this is the same with
|
||||
`remote.getGlobal('process')` but gets cached.
|
Loading…
Add table
Add a link
Reference in a new issue