electron/docs/api/native-image.md

156 lines
3.7 KiB
Markdown
Raw Normal View History

2015-02-12 05:52:28 +00:00
# NativeImage
2015-08-29 04:33:45 +00:00
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.
2015-08-29 04:33:45 +00:00
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'});
```
2015-08-29 04:33:45 +00:00
Or read the image from the clipboard which returns a `NativeImage`:
2015-02-12 05:52:28 +00:00
```javascript
var clipboard = require('clipboard');
var image = clipboard.readImage();
var appIcon = new Tray(image);
```
2015-01-03 03:15:09 +00:00
2015-02-12 05:52:28 +00:00
## Supported formats
Currently `PNG` and `JPEG` are supported. It is recommended to use `PNG` because
of its support for transparency and lossless compression.
On Windows, you can also load `ICO` icon from a file path.
## High resolution image
On platforms that have high-DPI support, you can append `@2x` after image's
2015-08-31 03:52:46 +00:00
base filename to mark it as a high resolution image.
2015-08-29 04:33:45 +00:00
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
2015-05-23 20:00:09 +00:00
density.
2015-08-31 03:52:46 +00:00
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/
├── icon.png
├── icon@2x.png
└── icon@3x.png
```
```javascript
var appIcon = new Tray('/Users/somebody/images/icon.png');
```
2015-08-31 03:52:46 +00:00
Following suffixes for DPI are also supported:
* `@1x`
* `@1.25x`
* `@1.33x`
* `@1.4x`
* `@1.5x`
* `@1.8x`
* `@2x`
* `@2.5x`
* `@3x`
2015-01-03 03:15:09 +00:00
* `@4x`
* `@5x`
2015-08-29 04:33:45 +00:00
## Template Image
2015-01-03 03:15:09 +00:00
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.
2015-08-31 03:52:46 +00:00
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.
2015-01-03 03:15:09 +00:00
2015-08-31 03:52:46 +00:00
**Note**: Template image is only supported on OS X.
2015-01-03 03:15:09 +00:00
2015-08-29 04:33:45 +00:00
To mark an image as a template image, its filename should end with the word
2015-08-31 03:52:46 +00:00
`Template`. For example:
2015-01-03 03:15:09 +00:00
* `xxxTemplate.png`
* `xxxTemplate@2x.png`
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
## Methods
The `NativeImage` class has the following methods:
### `NativeImage.createEmpty()`
2015-02-12 05:55:45 +00:00
2015-02-12 07:38:16 +00:00
Creates an empty `NativeImage` instance.
2015-02-12 05:55:45 +00:00
2015-08-29 04:33:45 +00:00
### `NativeImage.createFromPath(path)`
2015-02-12 05:52:28 +00:00
2015-02-12 07:38:16 +00:00
* `path` String
2015-02-12 05:52:28 +00:00
2015-05-23 20:00:09 +00:00
Creates a new `NativeImage` instance from a file located at `path`.
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
### `NativeImage.createFromBuffer(buffer[, scaleFactor])`
2015-02-12 05:52:28 +00:00
* `buffer` [Buffer][buffer]
2015-08-29 04:33:45 +00:00
* `scaleFactor` Double (optional)
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
Creates a new `NativeImage` instance from `buffer`. The default `scaleFactor` is
1.0.
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
### `NativeImage.createFromDataUrl(dataUrl)`
2015-02-12 05:52:28 +00:00
2015-02-12 07:38:16 +00:00
* `dataUrl` String
2015-02-12 05:52:28 +00:00
2015-02-12 07:38:16 +00:00
Creates a new `NativeImage` instance from `dataUrl`.
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
## Instance Methods
2015-08-31 03:52:46 +00:00
The following methods are available on instances of `nativeImage`:
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
```javascript
2015-08-31 03:52:37 +00:00
var NativeImage = require('native-image');
var image = NativeImage.createFromPath('/Users/somebody/images/icon.png');
2015-08-29 04:33:45 +00:00
```
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
### `image.toPng()`
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
Returns a [Buffer][buffer] that contains the image's `PNG` encoded data.
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
### `image.toJpeg(quality)`
2015-02-12 07:38:16 +00:00
2015-08-29 04:33:45 +00:00
* `quality` Integer between 0 - 100 (**required**)
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
Returns a [Buffer][buffer] that contains the image's `JPEG` encoded data.
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
### `image.toDataUrl()`
2015-02-12 07:38:16 +00:00
2015-08-29 04:33:45 +00:00
Returns the data URL of the image.
2015-02-12 07:38:16 +00:00
2015-08-29 04:33:45 +00:00
### `image.isEmpty()`
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
Returns a boolean whether the image is empty.
2015-02-12 05:52:28 +00:00
2015-08-29 04:33:45 +00:00
### `image.getSize()`
2015-02-12 05:52:28 +00:00
Returns the size of the image.
[buffer]: https://iojs.org/api/buffer.html#buffer_class_buffer
2015-08-29 04:33:45 +00:00
### `image.setTemplateImage(option)`
* `option` Boolean
Marks the image as template image.
2015-07-29 03:48:40 +00:00
2015-08-29 04:33:45 +00:00
### `image.isTemplateImage()`
2015-07-29 03:48:40 +00:00
2015-08-29 04:33:45 +00:00
Returns a boolean whether the image is a template image.