doc: Separate pages into sub directories.

This commit is contained in:
Cheng Zhao 2013-09-09 15:49:13 +08:00
parent 6b81070f67
commit 92241b91ce
21 changed files with 20 additions and 20 deletions

View 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.

View 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.