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

Merge pull request #2654 from atom/jl-std-docs-6

Browse source 
Standardize Docs: native-image, power-monitor, power-save-blocker, process
This commit is contained in:
Jessica Lord 2015-09-01 18:44:52 -07:00
commit e6265ec405
4 changed files with 100 additions and 75 deletions
Download patch file Download diff file Expand all files Collapse all files

100
docs/api/native-image.md
View file

@ -1,17 +1,17 @@
# NativeImage # NativeImage
In Electron for the APIs that take images, you can pass either file paths or In Electron, for the APIs that take images, you can pass either file paths or
`NativeImage` instances. When passing `null`, an empty image will be used. `NativeImage` instances. An empty image will be used when `null` is passed.
For example, when creating a tray or setting a window's icon, you can pass an image For example, when creating a tray or setting a window's icon, you can pass an
file path as a `String`: image file path as a `String`:
```javascript ```javascript
var appIcon = new Tray('/Users/somebody/images/icon.png'); var appIcon = new Tray('/Users/somebody/images/icon.png');
var window = new BrowserWindow({icon: '/Users/somebody/images/window.png'}); var window = new BrowserWindow({icon: '/Users/somebody/images/window.png'});
``` ```
Or read the image from the clipboard: Or read the image from the clipboard which returns a `NativeImage`:
```javascript ```javascript
var clipboard = require('clipboard'); var clipboard = require('clipboard');
@ -19,25 +19,25 @@ var image = clipboard.readImage();
var appIcon = new Tray(image); var appIcon = new Tray(image);
``` ```
## Supported formats ## Supported Formats
Currently `PNG` and `JPEG` are supported. It is recommended to use `PNG` because Currently `PNG` and `JPEG` image formats are supported. `PNG` is recommended
of its support for transparency and lossless compression. because of its support for transparency and lossless compression.
On Windows, you can also load `ICO` icon from a file path. On Windows, you can also load an `ICO` icon from a file path.
## High resolution image ## High Resolution Image
On platforms that have high-DPI support, you can append `@2x` after image's On platforms that have high-DPI support, you can append `@2x` after image's
file name's base name to mark it as a high resolution image. base filename to mark it as a high resolution image.
For example if `icon.png` is a normal image that has standard resolution, the For example if `icon.png` is a normal image that has standard resolution, then
`icon@2x.png` would be treated as a high resolution image that has double DPI `icon@2x.png` will be treated as a high resolution image that has double DPI
density. density.
If you want to support displays with different DPI density at the same time, you If you want to support displays with different DPI densities at the same time,
can put images with different sizes in the same folder, and use the filename you can put images with different sizes in the same folder and use the filename
without DPI suffixes, like this: without DPI suffixes. For example:
```text ```text
images/ images/
@ -51,7 +51,7 @@ images/
var appIcon = new Tray('/Users/somebody/images/icon.png'); var appIcon = new Tray('/Users/somebody/images/icon.png');
``` ```
Following suffixes as DPI denses are also supported: Following suffixes for DPI are also supported:
* `@1x` * `@1x`
* `@1.25x` * `@1.25x`
@ -65,81 +65,91 @@ Following suffixes as DPI denses are also supported:
* `@4x` * `@4x`
* `@5x` * `@5x`
## Template image ## Template Image
Template images consist of black and clear colors (and an alpha channel). Template images consist of black and clear colors (and an alpha channel).
Template images are not intended to be used as standalone images and are usually Template images are not intended to be used as standalone images and are usually
mixed with other content to create the desired final appearance. mixed with other content to create the desired final appearance.
The most common case is to use template image for menu bar icon so it can adapt The most common case is to use template images for a menu bar icon so it can
to both light and dark menu bars. adapt to both light and dark menu bars.
Template image is only supported on Mac. **Note**: Template image is only supported on OS X.
To mark an image as template image, its filename should end with the word To mark an image as a template image, its filename should end with the word
`Template`, examples are: `Template`. For example:
* `xxxTemplate.png` * `xxxTemplate.png`
* `xxxTemplate@2x.png` * `xxxTemplate@2x.png`
## nativeImage.createEmpty() ## Methods
The `NativeImage` class has the following methods:
### `NativeImage.createEmpty()`
Creates an empty `NativeImage` instance. Creates an empty `NativeImage` instance.
## nativeImage.createFromPath(path) ### `NativeImage.createFromPath(path)`
* `path` String * `path` String
Creates a new `NativeImage` instance from a file located at `path`. Creates a new `NativeImage` instance from a file located at `path`.
## nativeImage.createFromBuffer(buffer[, scaleFactor]) ### `NativeImage.createFromBuffer(buffer[, scaleFactor])`
* `buffer` [Buffer][buffer] * `buffer` [Buffer][buffer]
* `scaleFactor` Double * `scaleFactor` Double (optional)
Creates a new `NativeImage` instance from `buffer`. The `scaleFactor` is 1.0 by Creates a new `NativeImage` instance from `buffer`. The default `scaleFactor` is
default. 1.0.
## nativeImage.createFromDataUrl(dataUrl) ### `NativeImage.createFromDataUrl(dataUrl)`
* `dataUrl` String * `dataUrl` String
Creates a new `NativeImage` instance from `dataUrl`. Creates a new `NativeImage` instance from `dataUrl`.
## Class: NativeImage ## Instance Methods
This class is used to represent an image. The following methods are available on instances of `nativeImage`:
### NativeImage.toPng() ```javascript
var NativeImage = require('native-image');
Returns a [Buffer][buffer] that contains image's `PNG` encoded data. var image = NativeImage.createFromPath('/Users/somebody/images/icon.png');
```
### NativeImage.toJpeg(quality) ### `image.toPng()`
* `quality` Integer between 0 - 100 (required) Returns a [Buffer][buffer] that contains the image's `PNG` encoded data.
Returns a [Buffer][buffer] that contains image's `JPEG` encoded data. ### `image.toJpeg(quality)`
### NativeImage.toDataUrl() * `quality` Integer between 0 - 100 (**required**)
Returns the data URL of image. Returns a [Buffer][buffer] that contains the image's `JPEG` encoded data.
### NativeImage.isEmpty() ### `image.toDataUrl()`
Returns whether the image is empty. Returns the data URL of the image.
### NativeImage.getSize() ### `image.isEmpty()`
Returns a boolean whether the image is empty.
### `image.getSize()`
Returns the size of the image. Returns the size of the image.
[buffer]: https://iojs.org/api/buffer.html#buffer_class_buffer [buffer]: https://iojs.org/api/buffer.html#buffer_class_buffer
### NativeImage.setTemplateImage(option) ### `image.setTemplateImage(option)`
* `option` Boolean * `option` Boolean
Marks the image as template image. Marks the image as template image.
### NativeImage.isTemplateImage() ### `image.isTemplateImage()`
Returns whether the image is a template image. Returns a boolean whether the image is a template image.

20
docs/api/power-monitor.md
View file

@ -1,10 +1,10 @@
# power-monitor # power-monitor
The `power-monitor` module is used to monitor the power state change. You can The `power-monitor` module is used to monitor power state changes. You can
only use it on the main process. You should not use this module until the `ready` only use it on the main process. You should not use this module until the `ready`
event of `app` module gets emitted. event of the `app` module is emitted.
An example is: For example:
```javascript ```javascript
var app = require('app'); var app = require('app');
@ -16,18 +16,22 @@ app.on('ready', function() {
}); });
``` ```
## Event: suspend ## Events
The `power-monitor` module emits the following events:
### Event: 'suspend'
Emitted when the system is suspending. Emitted when the system is suspending.
## Event: resume ### Event: 'resume'
Emitted when system is resuming. Emitted when system is resuming.
## Event: on-ac ### Event: 'on-ac'
Emitted when the system changes to AC power. Emitted when the system changes to AC power.
## Event: on-battery ### Event: 'on-battery'
Emitted when system changes to battery power. Emitted when system changes to battery power.

44
docs/api/power-save-blocker.md
View file

@ -1,9 +1,10 @@
# power-save-blocker # powerSaveBlocker
The `power-save-blocker` module is used to block the system from entering The `power-save-blocker` module is used to block the system from entering
low-power(sleep) mode, allowing app to keep system and screen active. low-power (sleep) mode and thus allowing the app to keep the system and screen
active.
An example is: For example:
```javascript ```javascript
var powerSaveBlocker = require('power-save-blocker'); var powerSaveBlocker = require('power-save-blocker');
@ -14,35 +15,40 @@ console.log(powerSaveBlocker.isStarted(id));
powerSaveBlocker.stop(id); powerSaveBlocker.stop(id);
``` ```
## powerSaveBlocker.start(type) ## Methods
* `type` String - Power save blocker type The `powerSaveBlocker` module has the following methods:
### `powerSaveBlocker.start(type)`
* `type` String - Power save blocker type.
* `prevent-app-suspension` - Prevent the application from being suspended. * `prevent-app-suspension` - Prevent the application from being suspended.
Keeps system active, but allows screen to be turned off. Example use cases: Keeps system active but allows screen to be turned off. Example use cases:
downloading a file, playing audio. downloading a file or playing audio.
* `prevent-display-sleep`- Prevent the display from going to sleep. Keeps system * `prevent-display-sleep`- Prevent the display from going to sleep. Keeps
and screen active. Example use case: playing video. system and screen active. Example use case: playing video.
Starts the power save blocker preventing the system entering lower-power mode. Starts preventing the system from entering lower-power mode. Returns an integer
Returns an integer identified the power save blocker. identifying the power save blocker.
**Note:** **Note:** `prevent-display-sleep` has higher has precedence over
`prevent-display-sleep` has higher precedence level than `prevent-app-suspension`. `prevent-app-suspension`. Only the highest precedence type takes effect. In
Only the highest precedence type takes effect. In other words, `prevent-display-sleep` other words, `prevent-display-sleep` always takes precedence over
always take precedence over `prevent-app-suspension`. `prevent-app-suspension`.
For example, an API calling A requests for `prevent-app-suspension`, and For example, an API calling A requests for `prevent-app-suspension`, and
another calling B requests for `prevent-display-sleep`. `prevent-display-sleep` another calling B requests for `prevent-display-sleep`. `prevent-display-sleep`
will be used until B stops its request. After that, `prevent-app-suspension` is used. will be used until B stops its request. After that, `prevent-app-suspension`
is used.
## powerSaveBlocker.stop(id) ### `powerSaveBlocker.stop(id)`
* `id` Integer - The power save blocker id returned by `powerSaveBlocker.start`. * `id` Integer - The power save blocker id returned by `powerSaveBlocker.start`.
Stops the specified power save blocker. Stops the specified power save blocker.
## powerSaveBlocker.isStarted(id) ### `powerSaveBlocker.isStarted(id)`
* `id` Integer - The power save blocker id returned by `powerSaveBlocker.start`. * `id` Integer - The power save blocker id returned by `powerSaveBlocker.start`.
Returns whether the corresponding `powerSaveBlocker` starts. Returns a boolean whether the corresponding `powerSaveBlocker` has started.

11
docs/api/process.md
View file

@ -1,14 +1,19 @@
# Process object # process
The `process` object in Electron has the following differences from the one in The `process` object in Electron has the following differences from the one in
upstream node: upstream node:
* `process.type` String - Process's type, can be `browser` (i.e. main process) or `renderer`. * `process.type` String - Process's type, can be `browser` (i.e. main process)
or `renderer`.
* `process.versions['electron']` String - Version of Electron. * `process.versions['electron']` String - Version of Electron.
* `process.versions['chrome']` String - Version of Chromium. * `process.versions['chrome']` String - Version of Chromium.
* `process.resourcesPath` String - Path to JavaScript source code. * `process.resourcesPath` String - Path to JavaScript source code.
## process.hang # Methods
The `process` object has the following method:
### `process.hang`
Causes the main thread of the current process hang. Causes the main thread of the current process hang.