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

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

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

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

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