diff --git a/docs/api/native-image.md b/docs/api/native-image.md index 4d4fb4bbf5be..c00ec3a9458a 100644 --- a/docs/api/native-image.md +++ b/docs/api/native-image.md @@ -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. diff --git a/docs/api/power-monitor.md b/docs/api/power-monitor.md index 4643110f35bb..c9a33cc1a128 100644 --- a/docs/api/power-monitor.md +++ b/docs/api/power-monitor.md @@ -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. diff --git a/docs/api/power-save-blocker.md b/docs/api/power-save-blocker.md index 23b1252c6789..26f0abc84808 100644 --- a/docs/api/power-save-blocker.md +++ b/docs/api/power-save-blocker.md @@ -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. diff --git a/docs/api/process.md b/docs/api/process.md index 930a5860fc44..abd3c4fe574c 100644 --- a/docs/api/process.md +++ b/docs/api/process.md @@ -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.