2015-11-12 13:20:09 +00:00
|
|
|
# nativeImage
|
2014-06-23 14:58:42 +00:00
|
|
|
|
2016-04-21 22:35:29 +00:00
|
|
|
Create tray, dock, and application icons using PNG or JPG files.
|
|
|
|
|
2015-08-29 04:33:45 +00:00
|
|
|
In Electron, for the APIs that take images, you can pass either file paths or
|
2015-11-12 13:20:09 +00:00
|
|
|
`nativeImage` instances. An empty image will be used when `null` is passed.
|
2014-06-23 14:58:42 +00:00
|
|
|
|
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`:
|
2014-06-23 14:58:42 +00:00
|
|
|
|
|
|
|
```javascript
|
2014-08-06 03:20:00 +00:00
|
|
|
var appIcon = new Tray('/Users/somebody/images/icon.png');
|
2014-06-23 14:58:42 +00:00
|
|
|
var window = new BrowserWindow({icon: '/Users/somebody/images/window.png'});
|
|
|
|
```
|
|
|
|
|
2015-11-12 13:20:09 +00:00
|
|
|
Or read the image from the clipboard which returns a `nativeImage`:
|
2014-06-23 14:58:42 +00:00
|
|
|
|
2015-02-12 05:52:28 +00:00
|
|
|
```javascript
|
|
|
|
var image = clipboard.readImage();
|
|
|
|
var appIcon = new Tray(image);
|
|
|
|
```
|
2015-01-03 03:15:09 +00:00
|
|
|
|
2015-09-01 23:21:29 +00:00
|
|
|
## Supported Formats
|
2015-02-12 05:52:28 +00:00
|
|
|
|
2015-09-01 23:21:29 +00:00
|
|
|
Currently `PNG` and `JPEG` image formats are supported. `PNG` is recommended
|
|
|
|
because of its support for transparency and lossless compression.
|
2015-08-08 16:08:09 +00:00
|
|
|
|
2015-09-01 23:21:29 +00:00
|
|
|
On Windows, you can also load an `ICO` icon from a file path.
|
2014-06-23 14:58:42 +00:00
|
|
|
|
2015-09-01 23:21:29 +00:00
|
|
|
## High Resolution Image
|
2014-06-23 14:58:42 +00:00
|
|
|
|
|
|
|
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.
|
2014-06-23 14:58:42 +00:00
|
|
|
|
2015-08-29 04:33:45 +00:00
|
|
|
For example if `icon.png` is a normal image that has standard resolution, then
|
2015-09-01 23:21:29 +00:00
|
|
|
`icon@2x.png` will be treated as a high resolution image that has double DPI
|
2015-05-23 20:00:09 +00:00
|
|
|
density.
|
2014-08-06 03:20:00 +00:00
|
|
|
|
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:
|
2014-08-06 03:20:00 +00:00
|
|
|
|
|
|
|
```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:
|
2014-08-06 03:20:00 +00:00
|
|
|
|
|
|
|
* `@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-09-09 21:09:14 +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:
|
2014-08-06 03:20:00 +00:00
|
|
|
|
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
|
|
|
|
|
2015-11-12 13:20:09 +00:00
|
|
|
The `nativeImage` class has the following methods:
|
2015-08-29 04:33:45 +00:00
|
|
|
|
2015-11-12 13:20:09 +00:00
|
|
|
### `nativeImage.createEmpty()`
|
2015-02-12 05:55:45 +00:00
|
|
|
|
2015-11-12 13:20:09 +00:00
|
|
|
Creates an empty `nativeImage` instance.
|
2015-02-12 05:55:45 +00:00
|
|
|
|
2015-11-12 13:20:09 +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-11-12 13:20:09 +00:00
|
|
|
Creates a new `nativeImage` instance from a file located at `path`.
|
2015-02-12 05:52:28 +00:00
|
|
|
|
2015-11-12 13:20:09 +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-11-12 13:20:09 +00:00
|
|
|
Creates a new `nativeImage` instance from `buffer`. The default `scaleFactor` is
|
2015-08-29 04:33:45 +00:00
|
|
|
1.0.
|
2015-02-12 05:52:28 +00:00
|
|
|
|
2015-11-13 08:03:40 +00:00
|
|
|
### `nativeImage.createFromDataURL(dataURL)`
|
2015-02-12 05:52:28 +00:00
|
|
|
|
2015-11-13 08:03:40 +00:00
|
|
|
* `dataURL` String
|
2015-02-12 05:52:28 +00:00
|
|
|
|
2015-11-13 08:03:40 +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-11-12 13:20:09 +00:00
|
|
|
const nativeImage = require('electron').nativeImage;
|
2015-08-31 03:52:37 +00:00
|
|
|
|
2015-11-12 13:20:09 +00:00
|
|
|
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-12-18 03:12:07 +00:00
|
|
|
* `quality` Integer (**required**) - Between 0 - 100.
|
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-11-13 08:03:40 +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
|
|
|
|
2016-03-17 12:55:02 +00:00
|
|
|
### `image.getNativeHandle()` _OS X_
|
2016-03-14 03:11:43 +00:00
|
|
|
|
2016-03-17 12:55:02 +00:00
|
|
|
Returns a [Buffer][buffer] that stores C pointer to underlying native handle of
|
|
|
|
the image. On OS X, a pointer to `NSImage` instance would be returned.
|
2016-03-14 03:11:43 +00:00
|
|
|
|
2016-03-17 12:55:02 +00:00
|
|
|
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.
|
2016-03-14 03:11:43 +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.
|
|
|
|
|
2015-10-05 18:12:29 +00:00
|
|
|
[buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer
|
2015-04-08 08:20:03 +00:00
|
|
|
|
2015-08-29 04:33:45 +00:00
|
|
|
### `image.setTemplateImage(option)`
|
2015-04-08 08:20:03 +00:00
|
|
|
|
|
|
|
* `option` Boolean
|
|
|
|
|
2015-04-13 03:53:24 +00:00
|
|
|
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.
|