Merge pull request #2654 from atom/jl-std-docs-6
Standardize Docs: native-image, power-monitor, power-save-blocker, process
This commit is contained in:
Jessica Lord
commit
e6265ec405
4 changed files with 100 additions and 75 deletions
|
|
@ -1,17 +1,17 @@
|
|||
# NativeImage
|
||||
|
||||
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.
|
||||
In Electron, for the APIs that take images, you can pass either file paths or
|
||||
`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
|
||||
file path as a `String`:
|
||||
For example, when creating a tray or setting a window's icon, you can pass an
|
||||
image file path as a `String`:
|
||||
|
||||
```javascript
|
||||
var appIcon = new Tray('/Users/somebody/images/icon.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
|
||||
var clipboard = require('clipboard');
|
||||
|
|
@ -19,25 +19,25 @@ var image = clipboard.readImage();
|
|||
var appIcon = new Tray(image);
|
||||
```
|
||||
|
||||
## Supported formats
|
||||
## Supported Formats
|
||||
|
||||
Currently `PNG` and `JPEG` are supported. It is recommended to use `PNG` because
|
||||
of its support for transparency and lossless compression.
|
||||
Currently `PNG` and `JPEG` image formats are supported. `PNG` is recommended
|
||||
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
|
||||
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
|
||||
`icon@2x.png` would be treated as a high resolution image that has double DPI
|
||||
For example if `icon.png` is a normal image that has standard resolution, then
|
||||
`icon@2x.png` will be treated as a high resolution image that has double DPI
|
||||
density.
|
||||
|
||||
If you want to support displays with different DPI density at the same time, you
|
||||
can put images with different sizes in the same folder, and use the filename
|
||||
without DPI suffixes, like this:
|
||||
If you want to support displays with different DPI densities at the same time,
|
||||
you can put images with different sizes in the same folder and use the filename
|
||||
without DPI suffixes. For example:
|
||||
|
||||
```text
|
||||
images/
|
||||
|
|
@ -51,7 +51,7 @@ images/
|
|||
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`
|
||||
* `@1.25x`
|
||||
|
|
@ -65,81 +65,91 @@ Following suffixes as DPI denses are also supported:
|
|||
* `@4x`
|
||||
* `@5x`
|
||||
|
||||
## Template image
|
||||
## Template Image
|
||||
|
||||
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
|
||||
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
|
||||
to both light and dark menu bars.
|
||||
The most common case is to use template images for a menu bar icon so it can
|
||||
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
|
||||
`Template`, examples are:
|
||||
To mark an image as a template image, its filename should end with the word
|
||||
`Template`. For example:
|
||||
|
||||
* `xxxTemplate.png`
|
||||
* `xxxTemplate@2x.png`
|
||||
|
||||
## nativeImage.createEmpty()
|
||||
## Methods
|
||||
|
||||
The `NativeImage` class has the following methods:
|
||||
|
||||
### `NativeImage.createEmpty()`
|
||||
|
||||
Creates an empty `NativeImage` instance.
|
||||
|
||||
## nativeImage.createFromPath(path)
|
||||
### `NativeImage.createFromPath(path)`
|
||||
|
||||
* `path` String
|
||||
|
||||
Creates a new `NativeImage` instance from a file located at `path`.
|
||||
|
||||
## nativeImage.createFromBuffer(buffer[, scaleFactor])
|
||||
### `NativeImage.createFromBuffer(buffer[, scaleFactor])`
|
||||
|
||||
* `buffer` [Buffer][buffer]
|
||||
* `scaleFactor` Double
|
||||
* `scaleFactor` Double (optional)
|
||||
|
||||
Creates a new `NativeImage` instance from `buffer`. The `scaleFactor` is 1.0 by
|
||||
default.
|
||||
Creates a new `NativeImage` instance from `buffer`. The default `scaleFactor` is
|
||||
1.0.
|
||||
|
||||
## nativeImage.createFromDataUrl(dataUrl)
|
||||
### `NativeImage.createFromDataUrl(dataUrl)`
|
||||
|
||||
* `dataUrl` String
|
||||
|
||||
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.
|
||||
|
||||
[buffer]: https://iojs.org/api/buffer.html#buffer_class_buffer
|
||||
|
||||
### NativeImage.setTemplateImage(option)
|
||||
### `image.setTemplateImage(option)`
|
||||
|
||||
* `option` Boolean
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
# power-monitor
|
||||
|
||||
The `power-monitor` module is used to monitor the power state change. You can
|
||||
only use it on the main process. You should not use this module until the `ready`
|
||||
event of `app` module gets emitted.
|
||||
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`
|
||||
event of the `app` module is emitted.
|
||||
|
||||
An example is:
|
||||
For example:
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
## Event: resume
|
||||
### Event: 'resume'
|
||||
|
||||
Emitted when system is resuming.
|
||||
|
||||
## Event: on-ac
|
||||
### Event: 'on-ac'
|
||||
|
||||
Emitted when the system changes to AC power.
|
||||
|
||||
## Event: on-battery
|
||||
### Event: 'on-battery'
|
||||
|
||||
Emitted when system changes to battery power.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,10 @@
|
|||
# power-save-blocker
|
||||
# powerSaveBlocker
|
||||
|
||||
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
|
||||
var powerSaveBlocker = require('power-save-blocker');
|
||||
|
|
@ -14,35 +15,40 @@ console.log(powerSaveBlocker.isStarted(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.
|
||||
Keeps system active, but allows screen to be turned off. Example use cases:
|
||||
downloading a file, playing audio.
|
||||
* `prevent-display-sleep`- Prevent the display from going to sleep. Keeps system
|
||||
and screen active. Example use case: playing video.
|
||||
Keeps system active but allows screen to be turned off. Example use cases:
|
||||
downloading a file or playing audio.
|
||||
* `prevent-display-sleep`- Prevent the display from going to sleep. Keeps
|
||||
system and screen active. Example use case: playing video.
|
||||
|
||||
Starts the power save blocker preventing the system entering lower-power mode.
|
||||
Returns an integer identified the power save blocker.
|
||||
Starts preventing the system from entering lower-power mode. Returns an integer
|
||||
identifying the power save blocker.
|
||||
|
||||
**Note:**
|
||||
`prevent-display-sleep` has higher precedence level than `prevent-app-suspension`.
|
||||
Only the highest precedence type takes effect. In other words, `prevent-display-sleep`
|
||||
always take precedence over `prevent-app-suspension`.
|
||||
**Note:** `prevent-display-sleep` has higher has precedence over
|
||||
`prevent-app-suspension`. Only the highest precedence type takes effect. In
|
||||
other words, `prevent-display-sleep` always takes precedence over
|
||||
`prevent-app-suspension`.
|
||||
|
||||
For example, an API calling A requests for `prevent-app-suspension`, and
|
||||
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`.
|
||||
|
||||
Stops the specified power save blocker.
|
||||
|
||||
## powerSaveBlocker.isStarted(id)
|
||||
### `powerSaveBlocker.isStarted(id)`
|
||||
|
||||
* `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.
|
||||
|
|
|
|||
|
|
@ -1,14 +1,19 @@
|
|||
# Process object
|
||||
# process
|
||||
|
||||
The `process` object in Electron has the following differences from the one in
|
||||
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['chrome']` String - Version of Chromium.
|
||||
* `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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue