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

Merge pull request #6573 from electron/native-image-doc

Browse source 
Fix documentation for NativeImage
This commit is contained in:
Cheng Zhao 2016-07-25 16:55:09 +09:00 • committed by GitHub
commit a30997867f
1 changed files with 33 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -3,21 +3,21 @@
> Create tray, dock, and application icons using PNG or JPG files.
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.
`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`:
```javascript
const appIcon = new Tray('/Users/somebody/images/icon.png');
let win = new BrowserWindow({icon: '/Users/somebody/images/window.png'});
const appIcon = new Tray('/Users/somebody/images/icon.png')
let win = new BrowserWindow({icon: '/Users/somebody/images/window.png'})
```
Or read the image from the clipboard which returns a `nativeImage`:
```javascript
const image = clipboard.readImage();
const appIcon = new Tray(image);
const image = clipboard.readImage()
const appIcon = new Tray(image)
```
## Supported Formats
@ -25,8 +25,8 @@ const appIcon = new Tray(image);
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` icons from file paths, to get best visual
effects it is recommended to include at least followings sizes in the icon:
On Windows, you can also load `ICO` icons from file paths. For best visual
quality it is recommended to include at least the following sizes in the icon:
* 16x16
* 32x32
@ -35,8 +35,8 @@ effects it is recommended to include at least followings sizes in the icon:
## High Resolution Image
On platforms that have high-DPI support, you can append `@2x` after image's
base filename to mark it as a high resolution image.
On platforms that have high-DPI support such as Apple Retina displays, you can
append `@2x` after image's base filename to mark it as a high resolution image.
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
@ -55,7 +55,7 @@ images/
```javascript
let appIcon = new Tray('/Users/somebody/images/icon.png');
let appIcon = new Tray('/Users/somebody/images/icon.png')
```
Following suffixes for DPI are also supported:
@ -91,22 +91,22 @@ To mark an image as a template image, its filename should end with the word
## Methods
The `nativeImage` class has the following methods:
The `nativeImage` module has the following methods, all of which return
an instance of the `NativeImage` class:
### `nativeImage.createEmpty()`
Creates an empty `nativeImage` instance.
Creates an empty `NativeImage` instance.
### `nativeImage.createFromPath(path)`
* `path` String
Creates a new `nativeImage` instance from a file located at `path`.
Creates a new `NativeImage` instance from a file located at `path`.
```javascript
const nativeImage = require('electron').nativeImage;
let image = nativeImage.createFromPath('/Users/somebody/images/icon.png');
const {nativeImage} = require('electron')
let image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
```
### `nativeImage.createFromBuffer(buffer[, scaleFactor])`
@ -114,34 +114,38 @@ let image = nativeImage.createFromPath('/Users/somebody/images/icon.png');
* `buffer` [Buffer][buffer]
* `scaleFactor` Double (optional)
Creates a new `nativeImage` instance from `buffer`. The default `scaleFactor` is
Creates a new `NativeImage` instance from `buffer`. The default `scaleFactor` is
1.0.
### `nativeImage.createFromDataURL(dataURL)`
* `dataURL` String
Creates a new `nativeImage` instance from `dataURL`.
Creates a new `NativeImage` instance from `dataURL`.
## Instance Methods
## Class: NativeImage
The following methods are available on instances of `nativeImage`:
A native wrapper for images such as tray, dock, and application icons.
### `image.toPNG()`
### Instance Methods
The following methods are available on instances of the `NativeImage` class:
#### `image.toPNG()`
Returns a [Buffer][buffer] that contains the image's `PNG` encoded data.
### `image.toJPEG(quality)`
#### `image.toJPEG(quality)`
* `quality` Integer (**required**) - Between 0 - 100.
Returns a [Buffer][buffer] that contains the image's `JPEG` encoded data.
### `image.toDataURL()`
#### `image.toDataURL()`
Returns the data URL of the image.
### `image.getNativeHandle()` _macOS_
#### `image.getNativeHandle()` _macOS_
Returns a [Buffer][buffer] that stores C pointer to underlying native handle of
the image. On macOS, a pointer to `NSImage` instance would be returned.
@ -150,22 +154,22 @@ Notice that the returned pointer is a weak pointer to the underlying native
image instead of a copy, so you _must_ ensure that the associated
`nativeImage` instance is kept around.
### `image.isEmpty()`
#### `image.isEmpty()`
Returns a boolean whether the image is empty.
### `image.getSize()`
#### `image.getSize()`
Returns the size of the image.
[buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer
### `image.setTemplateImage(option)`
#### `image.setTemplateImage(option)`
* `option` Boolean
Marks the image as template image.
Marks the image as a template image.
### `image.isTemplateImage()`
#### `image.isTemplateImage()`
Returns a boolean whether the image is a template image.