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

Merge pull request #2655 from atom/jl-std-docs-7

Browse source 
Standardize Docs: protocol, remote, screen
This commit is contained in:
Jessica Lord 2015-09-02 09:46:39 -07:00
commit 159b6ca611
3 changed files with 146 additions and 110 deletions
Download patch file Download diff file Expand all files Collapse all files

120
docs/api/protocol.md
View file

@ -3,7 +3,7 @@
The `protocol` module can register a custom protocol or intercept an existing The `protocol` module can register a custom protocol or intercept an existing
protocol. protocol.
An example of implementing a protocol that has the same effect with the An example of implementing a protocol that has the same effect as the
`file://` protocol: `file://` protocol:
```javascript ```javascript
@ -22,50 +22,56 @@ app.on('ready', function() {
}); });
``` ```
**Note:** This module can only be used after the `ready` event was emitted. **Note:** This module can only be used after the `ready` event in the `app`
module is emitted.
## protocol.registerStandardSchemes(schemes) ## Methods
The `protocol` module has the following methods:
### `protocol.registerStandardSchemes(schemes)`
* `schemes` Array - Custom schemes to be registered as standard schemes. * `schemes` Array - Custom schemes to be registered as standard schemes.
A standard scheme adheres to what RFC 3986 calls A standard `scheme` adheres to what RFC 3986 calls
[generic URI syntax](https://tools.ietf.org/html/rfc3986#section-3). This [generic URI syntax](https://tools.ietf.org/html/rfc3986#section-3). This
includes `file:` and `filesystem:`. includes `file:` and `filesystem:`.
## protocol.registerFileProtocol(scheme, handler[, completion]) ### `protocol.registerFileProtocol(scheme, handler[, completion])`
* `scheme` String * `scheme` String
* `handler` Function * `handler` Function
* `completion` Function * `completion` Function (optional)
Registers a protocol of `scheme` that will send file as response, the `handler` Registers a protocol of `scheme` that will send the file as a response. The
will be called with `handler(request, callback)` when a `request` is going to be `handler` will be called with `handler(request, callback)` when a `request` is
created with `scheme`, and `completion` will be called with `completion(null)` going to be created with `scheme`. `completion` will be called with
when `scheme` is successfully registered, or `completion(error)` when failed. `completion(null)` when `scheme` is successfully registered or
`completion(error)` when failed.
To handle the `request`, the `callback` should be called with either file's path To handle the `request`, the `callback` should be called with either the file's
or an object that has `path` property, e.g. `callback(filePath)` or path or an object that has a `path` property, e.g. `callback(filePath)` or
`callback({path: filePath})`. `callback({path: filePath})`.
When `callback` is called with nothing, or a number, or an object that has When `callback` is called with nothing, a number, or an object that has an
`error` property, the `request` will be failed with the `error` number you `error` property, the `request` will fail with the `error` number you
specified. For the available error numbers you can use, please check: specified. For the available error numbers you can use, please see the
https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h [net error list](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h).
By default the scheme is treated like `http:`, which is parsed differently By default the `scheme` is treated like `http:`, which is parsed differently
from protocols that follows "generic URI syntax" like `file:`, so you probably than protocols that follow the "generic URI syntax" like `file:`, so you
want to call `protocol.registerStandardSchemes` to make your scheme treated as probably want to call `protocol.registerStandardSchemes` to have your scheme
standard scheme. treated as a standard scheme.
## protocol.registerBufferProtocol(scheme, handler[, completion]) ### `protocol.registerBufferProtocol(scheme, handler[, completion])`
* `scheme` String * `scheme` String
* `handler` Function * `handler` Function
* `completion` Function * `completion` Function (optional)
Registers a protocol of `scheme` that will send `Buffer` as response, the Registers a protocol of `scheme` that will send a `Buffer` as a response. The
`callback` should be called with either an `Buffer` object, or an object that `callback` should be called with either a `Buffer` object or an object that
has `data`, `mimeType`, `chart` properties. has the `data`, `mimeType`, and `chart` properties.
Example: Example:
@ -78,37 +84,37 @@ protocol.registerBufferProtocol('atom', function(request, callback) {
}); });
``` ```
## protocol.registerStringProtocol(scheme, handler[, completion]) ### `protocol.registerStringProtocol(scheme, handler[, completion])`
* `scheme` String * `scheme` String
* `handler` Function * `handler` Function
* `completion` Function * `completion` Function (optional)
Registers a protocol of `scheme` that will send `String` as response, the Registers a protocol of `scheme` that will send a `String` as a response. The
`callback` should be called with either a `String`, or an object that `callback` should be called with either a `String` or an object that has the
has `data`, `mimeType`, `chart` properties. `data`, `mimeType`, and `chart` properties.
## protocol.registerHttpProtocol(scheme, handler[, completion]) ### `protocol.registerHttpProtocol(scheme, handler[, completion])`
* `scheme` String * `scheme` String
* `handler` Function * `handler` Function
* `completion` Function * `completion` Function (optional)
Registers a protocol of `scheme` that will send a HTTP request as response, the Registers a protocol of `scheme` that will send an HTTP request as a response.
`callback` should be called with an object that has `url`, `method`, `referer`, The `callback` should be called with an object that has the `url`, `method`,
`session` properties. `referer`, and `session` properties.
By default the HTTP request will reuse current session, if you want the request By default the HTTP request will reuse the current session. If you want the
to have different session you should specify `session` to `null`. request to have a different session you should set `session` to `null`.
## protocol.unregisterProtocol(scheme[, completion]) ### `protocol.unregisterProtocol(scheme[, completion])`
* `scheme` String * `scheme` String
* `completion` Function * `completion` Function (optional)
Unregisters the custom protocol of `scheme`. Unregisters the custom protocol of `scheme`.
## protocol.isProtocolHandled(scheme, callback) ### `protocol.isProtocolHandled(scheme, callback)`
* `scheme` String * `scheme` String
* `callback` Function * `callback` Function
@ -116,43 +122,43 @@ Unregisters the custom protocol of `scheme`.
The `callback` will be called with a boolean that indicates whether there is The `callback` will be called with a boolean that indicates whether there is
already a handler for `scheme`. already a handler for `scheme`.
## protocol.interceptFileProtocol(scheme, handler[, completion]) ### `protocol.interceptFileProtocol(scheme, handler[, completion])`
* `scheme` String * `scheme` String
* `handler` Function * `handler` Function
* `completion` Function * `completion` Function (optional)
Intercepts `scheme` protocol and use `handler` as the protocol's new handler Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends file as response. which sends a file as a response.
## protocol.interceptStringProtocol(scheme, handler[, completion]) ### `protocol.interceptStringProtocol(scheme, handler[, completion])`
* `scheme` String * `scheme` String
* `handler` Function * `handler` Function
* `completion` Function * `completion` Function (optional)
Intercepts `scheme` protocol and use `handler` as the protocol's new handler Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends String as response. which sends a `String` as a response.
## protocol.interceptBufferProtocol(scheme, handler[, completion]) ## `protocol.interceptBufferProtocol(scheme, handler[, completion])`
* `scheme` String * `scheme` String
* `handler` Function * `handler` Function
* `completion` Function * `completion` Function (optional)
Intercepts `scheme` protocol and use `handler` as the protocol's new handler Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends `Buffer` as response. which sends a `Buffer` as a response.
## protocol.interceptHttpProtocol(scheme, handler[, completion]) ## `protocol.interceptHttpProtocol(scheme, handler[, completion])`
* `scheme` String * `scheme` String
* `handler` Function * `handler` Function
* `completion` Function * `completion` Function (optional)
Intercepts `scheme` protocol and use `handler` as the protocol's new handler Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a new HTTP request as response. which sends a new HTTP request as a response.
## protocol.uninterceptProtocol(scheme[, completion]) ## `protocol.uninterceptProtocol(scheme[, completion])`
* `scheme` String * `scheme` String
* `completion` Function * `completion` Function

95
docs/api/remote.md
View file

@ -1,29 +1,29 @@
# remote # remote
The `remote` module provides a simple way to do inter-process communication The `remote` module provides a simple way to do inter-process communication
between the renderer process and the main process. (IPC) between the renderer process (web page) and the main process.
In Electron, only GUI-unrelated modules are available in the renderer process. In Electron, only GUI-unrelated modules are available in the renderer process.
Without the `remote` module, users who wanted to call a main process API in Without the `remote` module, users who want to call a main process API in
the renderer process would have to explicitly send inter-process messages the renderer process will have to explicitly send inter-process messages
to the main process. With the `remote` module, users can invoke methods of to the main process. With the `remote` module, you can invoke methods of the
main process object without explicitly sending inter-process messages, main process object without explicitly sending inter-process messages, similar
similar to Java's to Java's [RMI](http://en.wikipedia.org/wiki/Java_remote_method_invocation).
[RMI](http://en.wikipedia.org/wiki/Java_remote_method_invocation).
An example of creating a browser window in renderer process: An example of creating a browser window from a renderer process:
```javascript ```javascript
var remote = require('remote'); var remote = require('remote');
var BrowserWindow = remote.require('browser-window'); var BrowserWindow = remote.require('browser-window');
var win = new BrowserWindow({ width: 800, height: 600 }); var win = new BrowserWindow({ width: 800, height: 600 });
win.loadUrl('https://github.com'); win.loadUrl('https://github.com');
``` ```
Note: for the reverse (access renderer process from main process), you can use **Note**: for the reverse (access the renderer process from the main process),
[webContents.executeJavascript](browser-window.md#webcontents-executejavascript-code). you can use [webContents.executeJavascript](browser-window.md#webcontents-executejavascript-code).
## Remote objects ## Remote Objects
Each object (including functions) returned by the `remote` module represents an Each object (including functions) returned by the `remote` module represents an
object in the main process (we call it a remote object or remote function). object in the main process (we call it a remote object or remote function).
@ -32,34 +32,37 @@ a new object with the remote constructor (function), you are actually sending
synchronous inter-process messages. synchronous inter-process messages.
In the example above, both `BrowserWindow` and `win` were remote objects and In the example above, both `BrowserWindow` and `win` were remote objects and
`new BrowserWindow` didn't create a `BrowserWindow` object in the renderer process. `new BrowserWindow` didn't create a `BrowserWindow` object in the renderer
Instead, it created a `BrowserWindow` object in the main process and returned the process. Instead, it created a `BrowserWindow` object in the main process and
corresponding remote object in the renderer process, namely the `win` object. returned the corresponding remote object in the renderer process, namely the
`win` object.
## Lifetime of remote objects ## Lifetime of Remote Objects
Electron makes sure that as long as the remote object in the renderer process Electron makes sure that as long as the remote object in the renderer process
lives (in other words, has not been garbage collected), the corresponding object lives (in other words, has not been garbage collected), the corresponding object
in the main process would never be released. When the remote object has been in the main process will not be released. When the remote object has been
garbage collected, the corresponding object in the main process would be garbage collected, the corresponding object in the main process will be
dereferenced. dereferenced.
If the remote object is leaked in renderer process (e.g. stored in a map but never If the remote object is leaked in the renderer process (e.g. stored in a map but
freed), the corresponding object in the main process would also be leaked, never freed), the corresponding object in the main process will also be leaked,
so you should be very careful not to leak remote objects. so you should be very careful not to leak remote objects.
Primary value types like strings and numbers, however, are sent by copy. Primary value types like strings and numbers, however, are sent by copy.
## Passing callbacks to the main process ## Passing callbacks to the main process
Code in the main process can accept callbacks from the renderer - for instance the `remote` module - Code in the main process can accept callbacks from the renderer - for instance
but you should be extremely careful when using this feature. the `remote` module - but you should be extremely careful when using this
feature.
First, in order to avoid deadlocks, the callbacks passed to the main process First, in order to avoid deadlocks, the callbacks passed to the main process
are called asynchronously. You should not expect the main process to are called asynchronously. You should not expect the main process to
get the return value of the passed callbacks. get the return value of the passed callbacks.
For instance you can't use a function from the renderer process in a `Array.map` called in the main process: For instance you can't use a function from the renderer process in an
`Array.map` called in the main process:
```javascript ```javascript
// main process mapNumbers.js // main process mapNumbers.js
@ -69,10 +72,12 @@ exports.withRendererCallback = function(mapper) {
exports.withLocalCallback = function() { exports.withLocalCallback = function() {
return exports.mapNumbers(function(x) { return exports.mapNumbers(function(x) {
return x + 1; return x + 1;
}); });
} }
```
```javascript
// renderer process // renderer process
var mapNumbers = require("remote").require("mapNumbers"); var mapNumbers = require("remote").require("mapNumbers");
@ -85,8 +90,9 @@ var withLocalCb = mapNumbers.withLocalCallback()
console.log(withRendererCb, withLocalCb) // [true, true, true], [2, 3, 4] console.log(withRendererCb, withLocalCb) // [true, true, true], [2, 3, 4]
``` ```
As you can see, the renderer callback's synchronous return value was not as expected, As you can see, the renderer callback's synchronous return value was not as
and didn't match the return value of an indentical callback that lives in the main process. expected, and didn't match the return value of an identical callback that lives
in the main process.
Second, the callbacks passed to the main process will persist until the Second, the callbacks passed to the main process will persist until the
main process garbage-collects them. main process garbage-collects them.
@ -96,45 +102,52 @@ callback for the `close` event on a remote object:
```javascript ```javascript
var remote = require('remote'); var remote = require('remote');
remote.getCurrentWindow().on('close', function() { remote.getCurrentWindow().on('close', function() {
// blabla... // blabla...
}); });
``` ```
But remember the callback is referenced by the main process until you But remember the callback is referenced by the main process until you
explicitly uninstall it! If you do not, each time you reload your window the callback will explicitly uninstall it. If you do not, each time you reload your window the
be installed again, leaking one callback each restart. callback will be installed again, leaking one callback for each restart.
To make things worse, since the context of previously installed callbacks have been released, To make things worse, since the context of previously installed callbacks has
when the `close` event was emitted exceptions would be raised in the main process. been released, exceptions will be raised in the main process when the `close`
event is emitted.
To avoid this problem, ensure you clean up any references to renderer callbacks passed to the main To avoid this problem, ensure you clean up any references to renderer callbacks
process. This involves cleaning up event handlers, or ensuring the main process is explicitly told to deference passed to the main process. This involves cleaning up event handlers, or
callbacks that came from a renderer process that is exiting. ensuring the main process is explicitly told to deference callbacks that came
from a renderer process that is exiting.
## remote.require(module) ## Methods
The `remote` module has the following methods:
### `remote.require(module)`
* `module` String * `module` String
Returns the object returned by `require(module)` in the main process. Returns the object returned by `require(module)` in the main process.
## remote.getCurrentWindow() ### `remote.getCurrentWindow()`
Returns the [BrowserWindow](browser-window.md) object which this web page Returns the [`BrowserWindow`](browser-window.md) object to which this web page
belongs to. belongs.
## remote.getCurrentWebContents() ### `remote.getCurrentWebContents()`
Returns the WebContents object of this web page. Returns the [`WebContents`](web-contents.md) object of this web page.
## remote.getGlobal(name) ### `remote.getGlobal(name)`
* `name` String * `name` String
Returns the global variable of `name` (e.g. `global[name]`) in the main Returns the global variable of `name` (e.g. `global[name]`) in the main
process. process.
## remote.process ### `remote.process`
Returns the `process` object in the main process. This is the same as Returns the `process` object in the main process. This is the same as
`remote.getGlobal('process')`, but gets cached. `remote.getGlobal('process')` but is cached.

41
docs/api/screen.md
View file

@ -1,11 +1,14 @@
# screen # screen
Gets various info about screen size, displays, cursor position, etc. You should The `screen` module retrieves information about screen size, displays, cursor
not use this module until the `ready` event of `app` module gets emitted. position, etc. You should not use this module until the `ready` event of the
`app` module is emitted.
`screen` is an [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter). `screen` is an [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
Make sure to note that in the renderer / DevTools, `window.screen` is a reserved DOM property, so writing `screen = require('screen')` won't work. In our examples below, we use `atomScreen` as the variable name instead. **Note**: In the renderer / DevTools, `window.screen` is a reserved
DOM property, so writing `var screen = require('screen')` will not work. In our
examples below, we use `atomScreen` as the variable name instead.
An example of creating a window that fills the whole screen: An example of creating a window that fills the whole screen:
@ -50,43 +53,57 @@ app.on('ready', function() {
}); });
``` ```
## Event: display-added ## Events
The `screen` module emits the following events:
### Event: 'display-added'
Returns:
* `event` Event * `event` Event
* `newDisplay` Object * `newDisplay` Object
Emitted when `newDisplay` has been added. Emitted when `newDisplay` has been added.
## Event: display-removed ### Event: 'display-removed'
Returns:
* `event` Event * `event` Event
* `oldDisplay` Object * `oldDisplay` Object
Emitted when `oldDisplay` has been removed. Emitted when `oldDisplay` has been removed.
## Event: display-metrics-changed ### Event: 'display-metrics-changed'
Returns:
* `event` Event * `event` Event
* `display` Object * `display` Object
* `changedMetrics` Array * `changedMetrics` Array
Emitted when a `display` has one or more metrics changed, `changedMetrics` is Emitted when one or more metrics change in a `display`. The `changedMetrics` is
an array of strings that describe the changes. Possible changes are `bounds`, an array of strings that describe the changes. Possible changes are `bounds`,
`workArea`, `scaleFactor` and `rotation`. `workArea`, `scaleFactor` and `rotation`.
## screen.getCursorScreenPoint() ## Methods
The `screen` module has the following methods:
### `screen.getCursorScreenPoint()`
Returns the current absolute position of the mouse pointer. Returns the current absolute position of the mouse pointer.
## screen.getPrimaryDisplay() ### `screen.getPrimaryDisplay()`
Returns the primary display. Returns the primary display.
## screen.getAllDisplays() ### `screen.getAllDisplays()`
Returns an array of displays that are currently available. Returns an array of displays that are currently available.
## screen.getDisplayNearestPoint(point) ### `screen.getDisplayNearestPoint(point)`
* `point` Object * `point` Object
* `x` Integer * `x` Integer
@ -94,7 +111,7 @@ Returns an array of displays that are currently available.
Returns the display nearest the specified point. Returns the display nearest the specified point.
## screen.getDisplayMatching(rect) ### `screen.getDisplayMatching(rect)`
* `rect` Object * `rect` Object
* `x` Integer * `x` Integer