Merge pull request #2655 from atom/jl-std-docs-7
Standardize Docs: protocol, remote, screen
This commit is contained in:
Jessica Lord
commit
159b6ca611
3 changed files with 146 additions and 110 deletions
|
|
@ -3,7 +3,7 @@
|
|||
The `protocol` module can register a custom protocol or intercept an existing
|
||||
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:
|
||||
|
||||
```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.
|
||||
|
||||
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
|
||||
includes `file:` and `filesystem:`.
|
||||
|
||||
## protocol.registerFileProtocol(scheme, handler[, completion])
|
||||
### `protocol.registerFileProtocol(scheme, handler[, completion])`
|
||||
|
||||
* `scheme` String
|
||||
* `handler` Function
|
||||
* `completion` Function
|
||||
* `completion` Function (optional)
|
||||
|
||||
Registers a protocol of `scheme` that will send file as response, the `handler`
|
||||
will be called with `handler(request, callback)` when a `request` is going to be
|
||||
created with `scheme`, and `completion` will be called with `completion(null)`
|
||||
when `scheme` is successfully registered, or `completion(error)` when failed.
|
||||
Registers a protocol of `scheme` that will send the file as a response. The
|
||||
`handler` will be called with `handler(request, callback)` when a `request` is
|
||||
going to be created with `scheme`. `completion` will be called with
|
||||
`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
|
||||
or an object that has `path` property, e.g. `callback(filePath)` or
|
||||
To handle the `request`, the `callback` should be called with either the file's
|
||||
path or an object that has a `path` property, e.g. `callback(filePath)` or
|
||||
`callback({path: filePath})`.
|
||||
|
||||
When `callback` is called with nothing, or a number, or an object that has
|
||||
`error` property, the `request` will be failed with the `error` number you
|
||||
specified. For the available error numbers you can use, please check:
|
||||
https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h
|
||||
When `callback` is called with nothing, a number, or an object that has an
|
||||
`error` property, the `request` will fail with the `error` number you
|
||||
specified. For the available error numbers you can use, please see the
|
||||
[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
|
||||
from protocols that follows "generic URI syntax" like `file:`, so you probably
|
||||
want to call `protocol.registerStandardSchemes` to make your scheme treated as
|
||||
standard scheme.
|
||||
By default the `scheme` is treated like `http:`, which is parsed differently
|
||||
than protocols that follow the "generic URI syntax" like `file:`, so you
|
||||
probably want to call `protocol.registerStandardSchemes` to have your scheme
|
||||
treated as a standard scheme.
|
||||
|
||||
## protocol.registerBufferProtocol(scheme, handler[, completion])
|
||||
### `protocol.registerBufferProtocol(scheme, handler[, completion])`
|
||||
|
||||
* `scheme` String
|
||||
* `handler` Function
|
||||
* `completion` Function
|
||||
* `completion` Function (optional)
|
||||
|
||||
Registers a protocol of `scheme` that will send `Buffer` as response, the
|
||||
`callback` should be called with either an `Buffer` object, or an object that
|
||||
has `data`, `mimeType`, `chart` properties.
|
||||
Registers a protocol of `scheme` that will send a `Buffer` as a response. The
|
||||
`callback` should be called with either a `Buffer` object or an object that
|
||||
has the `data`, `mimeType`, and `chart` properties.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -78,37 +84,37 @@ protocol.registerBufferProtocol('atom', function(request, callback) {
|
|||
});
|
||||
```
|
||||
|
||||
## protocol.registerStringProtocol(scheme, handler[, completion])
|
||||
### `protocol.registerStringProtocol(scheme, handler[, completion])`
|
||||
|
||||
* `scheme` String
|
||||
* `handler` Function
|
||||
* `completion` Function
|
||||
* `completion` Function (optional)
|
||||
|
||||
Registers a protocol of `scheme` that will send `String` as response, the
|
||||
`callback` should be called with either a `String`, or an object that
|
||||
has `data`, `mimeType`, `chart` properties.
|
||||
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 has the
|
||||
`data`, `mimeType`, and `chart` properties.
|
||||
|
||||
## protocol.registerHttpProtocol(scheme, handler[, completion])
|
||||
### `protocol.registerHttpProtocol(scheme, handler[, completion])`
|
||||
|
||||
* `scheme` String
|
||||
* `handler` Function
|
||||
* `completion` Function
|
||||
* `completion` Function (optional)
|
||||
|
||||
Registers a protocol of `scheme` that will send a HTTP request as response, the
|
||||
`callback` should be called with an object that has `url`, `method`, `referer`,
|
||||
`session` properties.
|
||||
Registers a protocol of `scheme` that will send an HTTP request as a response.
|
||||
The `callback` should be called with an object that has the `url`, `method`,
|
||||
`referer`, and `session` properties.
|
||||
|
||||
By default the HTTP request will reuse current session, if you want the request
|
||||
to have different session you should specify `session` to `null`.
|
||||
By default the HTTP request will reuse the current session. If you want the
|
||||
request to have a different session you should set `session` to `null`.
|
||||
|
||||
## protocol.unregisterProtocol(scheme[, completion])
|
||||
### `protocol.unregisterProtocol(scheme[, completion])`
|
||||
|
||||
* `scheme` String
|
||||
* `completion` Function
|
||||
* `completion` Function (optional)
|
||||
|
||||
Unregisters the custom protocol of `scheme`.
|
||||
|
||||
## protocol.isProtocolHandled(scheme, callback)
|
||||
### `protocol.isProtocolHandled(scheme, callback)`
|
||||
|
||||
* `scheme` String
|
||||
* `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
|
||||
already a handler for `scheme`.
|
||||
|
||||
## protocol.interceptFileProtocol(scheme, handler[, completion])
|
||||
### `protocol.interceptFileProtocol(scheme, handler[, completion])`
|
||||
|
||||
* `scheme` String
|
||||
* `handler` Function
|
||||
* `completion` Function
|
||||
* `completion` Function (optional)
|
||||
|
||||
Intercepts `scheme` protocol and use `handler` as the protocol's new handler
|
||||
which sends file as response.
|
||||
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
|
||||
which sends a file as a response.
|
||||
|
||||
## protocol.interceptStringProtocol(scheme, handler[, completion])
|
||||
### `protocol.interceptStringProtocol(scheme, handler[, completion])`
|
||||
|
||||
* `scheme` String
|
||||
* `handler` Function
|
||||
* `completion` Function
|
||||
* `completion` Function (optional)
|
||||
|
||||
Intercepts `scheme` protocol and use `handler` as the protocol's new handler
|
||||
which sends String as response.
|
||||
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
|
||||
which sends a `String` as a response.
|
||||
|
||||
## protocol.interceptBufferProtocol(scheme, handler[, completion])
|
||||
## `protocol.interceptBufferProtocol(scheme, handler[, completion])`
|
||||
|
||||
* `scheme` String
|
||||
* `handler` Function
|
||||
* `completion` Function
|
||||
* `completion` Function (optional)
|
||||
|
||||
Intercepts `scheme` protocol and use `handler` as the protocol's new handler
|
||||
which sends `Buffer` as response.
|
||||
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
|
||||
which sends a `Buffer` as a response.
|
||||
|
||||
## protocol.interceptHttpProtocol(scheme, handler[, completion])
|
||||
## `protocol.interceptHttpProtocol(scheme, handler[, completion])`
|
||||
|
||||
* `scheme` String
|
||||
* `handler` Function
|
||||
* `completion` Function
|
||||
* `completion` Function (optional)
|
||||
|
||||
Intercepts `scheme` protocol and use `handler` as the protocol's new handler
|
||||
which sends a new HTTP request as response.
|
||||
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
|
||||
which sends a new HTTP request as a response.
|
||||
|
||||
## protocol.uninterceptProtocol(scheme[, completion])
|
||||
## `protocol.uninterceptProtocol(scheme[, completion])`
|
||||
|
||||
* `scheme` String
|
||||
* `completion` Function
|
||||
|
|
|
|||
|
|
@ -1,29 +1,29 @@
|
|||
# remote
|
||||
|
||||
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.
|
||||
Without the `remote` module, users who wanted to call a main process API in
|
||||
the renderer process would have to explicitly send inter-process messages
|
||||
to the main process. With the `remote` module, users can invoke methods of
|
||||
main process object without explicitly sending inter-process messages,
|
||||
similar to Java's
|
||||
[RMI](http://en.wikipedia.org/wiki/Java_remote_method_invocation).
|
||||
Without the `remote` module, users who want to call a main process API in
|
||||
the renderer process will have to explicitly send inter-process messages
|
||||
to the main process. With the `remote` module, you can invoke methods of the
|
||||
main process object without explicitly sending inter-process messages, similar
|
||||
to Java's [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
|
||||
var remote = require('remote');
|
||||
var BrowserWindow = remote.require('browser-window');
|
||||
|
||||
var win = new BrowserWindow({ width: 800, height: 600 });
|
||||
win.loadUrl('https://github.com');
|
||||
```
|
||||
|
||||
Note: for the reverse (access renderer process from main process), you can use
|
||||
[webContents.executeJavascript](browser-window.md#webcontents-executejavascript-code).
|
||||
**Note**: for the reverse (access the renderer process from the main process),
|
||||
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
|
||||
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.
|
||||
|
||||
In the example above, both `BrowserWindow` and `win` were remote objects and
|
||||
`new BrowserWindow` didn't create a `BrowserWindow` object in the renderer process.
|
||||
Instead, it created a `BrowserWindow` object in the main process and returned the
|
||||
corresponding remote object in the renderer process, namely the `win` object.
|
||||
`new BrowserWindow` didn't create a `BrowserWindow` object in the renderer
|
||||
process. Instead, it created a `BrowserWindow` object in the main process and
|
||||
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
|
||||
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
|
||||
garbage collected, the corresponding object in the main process would be
|
||||
in the main process will not be released. When the remote object has been
|
||||
garbage collected, the corresponding object in the main process will be
|
||||
dereferenced.
|
||||
|
||||
If the remote object is leaked in renderer process (e.g. stored in a map but never
|
||||
freed), the corresponding object in the main process would also be leaked,
|
||||
If the remote object is leaked in the renderer process (e.g. stored in a map but
|
||||
never freed), the corresponding object in the main process will also be leaked,
|
||||
so you should be very careful not to leak remote objects.
|
||||
|
||||
Primary value types like strings and numbers, however, are sent by copy.
|
||||
|
||||
## Passing callbacks to the main process
|
||||
|
||||
Code in the main process can accept callbacks from the renderer - for instance the `remote` module -
|
||||
but you should be extremely careful when using this feature.
|
||||
Code in the main process can accept callbacks from the renderer - for instance
|
||||
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
|
||||
are called asynchronously. You should not expect the main process to
|
||||
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
|
||||
// main process mapNumbers.js
|
||||
|
|
@ -69,10 +72,12 @@ exports.withRendererCallback = function(mapper) {
|
|||
|
||||
exports.withLocalCallback = function() {
|
||||
return exports.mapNumbers(function(x) {
|
||||
return x + 1;
|
||||
return x + 1;
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
// renderer process
|
||||
var mapNumbers = require("remote").require("mapNumbers");
|
||||
|
||||
|
|
@ -85,8 +90,9 @@ var withLocalCb = mapNumbers.withLocalCallback()
|
|||
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,
|
||||
and didn't match the return value of an indentical callback that lives in the main process.
|
||||
As you can see, the renderer callback's synchronous return value was not as
|
||||
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
|
||||
main process garbage-collects them.
|
||||
|
|
@ -96,45 +102,52 @@ callback for the `close` event on a remote object:
|
|||
|
||||
```javascript
|
||||
var remote = require('remote');
|
||||
|
||||
remote.getCurrentWindow().on('close', function() {
|
||||
// blabla...
|
||||
});
|
||||
```
|
||||
|
||||
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
|
||||
be installed again, leaking one callback each restart.
|
||||
explicitly uninstall it. If you do not, each time you reload your window the
|
||||
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,
|
||||
when the `close` event was emitted exceptions would be raised in the main process.
|
||||
To make things worse, since the context of previously installed callbacks has
|
||||
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
|
||||
process. This involves cleaning up event handlers, or ensuring the main process is explicitly told to deference
|
||||
callbacks that came from a renderer process that is exiting.
|
||||
To avoid this problem, ensure you clean up any references to renderer callbacks
|
||||
passed to the main process. This involves cleaning up event handlers, or
|
||||
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
|
||||
|
||||
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
|
||||
belongs to.
|
||||
Returns the [`BrowserWindow`](browser-window.md) object to which this web page
|
||||
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
|
||||
|
||||
Returns the global variable of `name` (e.g. `global[name]`) in the main
|
||||
process.
|
||||
|
||||
## remote.process
|
||||
### `remote.process`
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,14 @@
|
|||
# screen
|
||||
|
||||
Gets various info about screen size, displays, cursor position, etc. You should
|
||||
not use this module until the `ready` event of `app` module gets emitted.
|
||||
The `screen` module retrieves information about screen size, displays, cursor
|
||||
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).
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -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
|
||||
* `newDisplay` Object
|
||||
|
||||
Emitted when `newDisplay` has been added.
|
||||
|
||||
## Event: display-removed
|
||||
### Event: 'display-removed'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `oldDisplay` Object
|
||||
|
||||
Emitted when `oldDisplay` has been removed.
|
||||
|
||||
## Event: display-metrics-changed
|
||||
### Event: 'display-metrics-changed'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `display` Object
|
||||
* `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`,
|
||||
`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.
|
||||
|
||||
## screen.getPrimaryDisplay()
|
||||
### `screen.getPrimaryDisplay()`
|
||||
|
||||
Returns the primary display.
|
||||
|
||||
## screen.getAllDisplays()
|
||||
### `screen.getAllDisplays()`
|
||||
|
||||
Returns an array of displays that are currently available.
|
||||
|
||||
## screen.getDisplayNearestPoint(point)
|
||||
### `screen.getDisplayNearestPoint(point)`
|
||||
|
||||
* `point` Object
|
||||
* `x` Integer
|
||||
|
|
@ -94,7 +111,7 @@ Returns an array of displays that are currently available.
|
|||
|
||||
Returns the display nearest the specified point.
|
||||
|
||||
## screen.getDisplayMatching(rect)
|
||||
### `screen.getDisplayMatching(rect)`
|
||||
|
||||
* `rect` Object
|
||||
* `x` Integer
|
||||
|
|
|
|||
Loading…
Reference in a new issue