electron/docs/api/native-image.md

327 lines
10 KiB
Markdown
Raw Normal View History

# nativeImage
2016-04-21 22:39:12 +00:00
> Create tray, dock, and application icons using PNG or JPG files.
2016-11-23 19:20:56 +00:00
Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
2016-11-03 17:26:00 +00:00
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
2018-09-13 16:10:51 +00:00
const { BrowserWindow, Tray } = require('electron')
const appIcon = new Tray('/Users/somebody/images/icon.png')
2018-09-13 16:10:51 +00:00
let win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })
console.log(appIcon, win)
```
2016-11-14 22:54:28 +00:00
Or read the image from the clipboard which returns a `NativeImage`:
2015-02-12 05:52:28 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { clipboard, Tray } = require('electron')
const image = clipboard.readImage()
const appIcon = new Tray(image)
console.log(appIcon)
2015-02-12 05:52:28 +00:00
```
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.
On Windows, you can also load `ICO` icons from file paths. For best visual
2016-08-01 11:13:40 +00:00
quality it is recommended to include at least the following sizes in the:
* Small icon
* 16x16 (100% DPI scale)
* 20x20 (125% DPI scale)
* 24x24 (150% DPI scale)
* 32x32 (200% DPI scale)
* Large icon
* 32x32 (100% DPI scale)
* 40x40 (125% DPI scale)
* 48x48 (150% DPI scale)
* 64x64 (200% DPI scale)
2016-05-20 10:58:47 +00:00
* 256x256
2016-08-01 11:13:40 +00:00
Check the *Size requirements* section in [this article][icons].
[icons]:https://msdn.microsoft.com/en-us/library/windows/desktop/dn742485(v=vs.85).aspx
2015-09-01 23:21:29 +00:00
## 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.
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.
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
2018-09-13 16:10:51 +00:00
const { Tray } = require('electron')
let appIcon = new Tray('/Users/somebody/images/icon.png')
console.log(appIcon)
```
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
2018-06-02 18:41:19 +00:00
Template images consist of black and an alpha channel.
2015-01-03 03:15:09 +00:00
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
2016-06-18 13:26:26 +00:00
**Note:** Template image is only supported on macOS.
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` module has the following methods, all of which return
an instance of the `NativeImage` class:
2015-08-29 04:33:45 +00:00
### `nativeImage.createEmpty()`
2015-02-12 05:55:45 +00:00
Returns `NativeImage`
Creates an empty `NativeImage` instance.
2015-02-12 05:55: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
Returns `NativeImage`
2016-09-21 17:48:01 +00:00
Creates a new `NativeImage` instance from a file located at `path`. This method
returns an empty image if the `path` does not exist, cannot be read, or is not
a valid image.
2015-02-12 05:52:28 +00:00
```javascript
const nativeImage = require('electron').nativeImage
let image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)
```
### `nativeImage.createFromBitmap(buffer, options)`
* `buffer` [Buffer][buffer]
* `options` Object
* `width` Integer
* `height` Integer
* `scaleFactor` Double (optional) - Defaults to 1.0.
Returns `NativeImage`
Creates a new `NativeImage` instance from `buffer` that contains the raw bitmap
pixel data returned by `toBitmap()`. The specific format is platform-dependent.
### `nativeImage.createFromBuffer(buffer[, options])`
2015-02-12 05:52:28 +00:00
* `buffer` [Buffer][buffer]
* `options` Object (optional)
2016-12-14 18:19:38 +00:00
* `width` Integer (optional) - Required for bitmap buffers.
* `height` Integer (optional) - Required for bitmap buffers.
* `scaleFactor` Double (optional) - Defaults to 1.0.
2015-02-12 05:52:28 +00:00
Returns `NativeImage`
Creates a new `NativeImage` instance from `buffer`. Tries to decode as PNG or JPEG first.
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
Returns `NativeImage`
Creates a new `NativeImage` instance from `dataURL`.
2017-10-10 06:05:13 +00:00
### `nativeImage.createFromNamedImage(imageName[, hslShift])` _macOS_
* `imageName` String
2017-10-10 06:05:13 +00:00
* `hslShift` Number[]
Returns `NativeImage`
Creates a new `NativeImage` instance from the NSImage that maps to the
2017-11-29 10:58:24 +00:00
given image name. See [`NSImageName`](https://developer.apple.com/documentation/appkit/nsimagename?language=objc)
for a list of possible values.
2017-10-10 06:05:13 +00:00
The `hslShift` is applied to the image with the following rules
* `hsl_shift[0]` (hue): The absolute hue value for the image - 0 and 1 map
to 0 and 360 on the hue color wheel (red).
* `hsl_shift[1]` (saturation): A saturation shift for the image, with the
2017-11-29 10:58:24 +00:00
following key values:
0 = remove all color.
0.5 = leave unchanged.
1 = fully saturate the image.
2017-10-10 06:05:13 +00:00
* `hsl_shift[2]` (lightness): A lightness shift for the image, with the
2017-11-29 10:58:24 +00:00
following key values:
0 = remove all lightness (make all pixels black).
0.5 = leave unchanged.
2017-10-10 06:05:13 +00:00
1 = full lightness (make all pixels white).
This means that `[-1, 0, 1]` will make the image completely white and
`[-1, 1, 0]` will make the image completely black.
In some cases, the `NSImageName` doesn't match its string representation; one example of this is `NSFolderImageName`, whose string representation would actually be `NSFolder`. Therefore, you'll need to determine the correct string representation for your image before passing it in. This can be done with the following:
`echo -e '#import <Cocoa/Cocoa.h>\nint main() { NSLog(@"%@", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test`
where `SYSTEM_IMAGE_NAME` should be replaced with any value from [this list](https://developer.apple.com/documentation/appkit/nsimagename?language=objc).
## Class: NativeImage
2016-08-22 21:11:03 +00:00
> Natively wrap images such as tray, dock, and application icons.
2015-02-12 05:52:28 +00:00
2016-11-23 19:20:56 +00:00
Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
### Instance Methods
2015-08-29 04:33:45 +00:00
The following methods are available on instances of the `NativeImage` class:
2015-02-12 05:52:28 +00:00
2017-03-07 00:22:48 +00:00
#### `image.toPNG([options])`
* `options` Object (optional)
* `scaleFactor` Double (optional) - Defaults to 1.0.
2015-02-12 05:52:28 +00:00
Returns `Buffer` - A [Buffer][buffer] that contains the image's `PNG` encoded data.
2015-02-12 05:52:28 +00:00
#### `image.toJPEG(quality)`
2015-02-12 07:38:16 +00:00
* `quality` Integer - Between 0 - 100.
2015-02-12 05:52:28 +00:00
Returns `Buffer` - A [Buffer][buffer] that contains the image's `JPEG` encoded data.
2015-02-12 05:52:28 +00:00
2017-03-07 00:22:48 +00:00
#### `image.toBitmap([options])`
* `options` Object (optional)
* `scaleFactor` Double (optional) - Defaults to 1.0.
2016-08-01 00:14:45 +00:00
Returns `Buffer` - A [Buffer][buffer] that contains a copy of the image's raw bitmap pixel
2016-08-05 08:55:57 +00:00
data.
2016-08-01 00:14:45 +00:00
2017-03-07 00:22:48 +00:00
#### `image.toDataURL([options])`
* `options` Object (optional)
* `scaleFactor` Double (optional) - Defaults to 1.0.
2015-02-12 07:38:16 +00:00
Returns `String` - The data URL of the image.
2015-02-12 07:38:16 +00:00
2017-03-07 00:22:48 +00:00
#### `image.getBitmap([options])`
* `options` Object (optional)
* `scaleFactor` Double (optional) - Defaults to 1.0.
2016-08-04 17:45:06 +00:00
Returns `Buffer` - A [Buffer][buffer] that contains the image's raw bitmap pixel data.
2016-08-05 08:55:57 +00:00
The difference between `getBitmap()` and `toBitmap()` is, `getBitmap()` does not
copy the bitmap data, so you have to use the returned Buffer immediately in
current event loop tick, otherwise the data might be changed or destroyed.
2016-08-04 17:45:06 +00:00
#### `image.getNativeHandle()` _macOS_
2016-03-14 03:11:43 +00:00
Returns `Buffer` - A [Buffer][buffer] that stores C pointer to underlying native handle of
2016-06-18 13:26:26 +00:00
the image. On macOS, a pointer to `NSImage` instance would be returned.
2016-03-14 03:11:43 +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
#### `image.isEmpty()`
2015-02-12 05:52:28 +00:00
2017-11-29 10:58:24 +00:00
Returns `Boolean` - Whether the image is empty.
2015-02-12 05:52:28 +00:00
#### `image.getSize()`
2015-02-12 05:52:28 +00:00
Returns [`Size`](structures/size.md)
#### `image.setTemplateImage(option)`
* `option` Boolean
Marks the image as a template image.
2015-07-29 03:48:40 +00:00
#### `image.isTemplateImage()`
2015-07-29 03:48:40 +00:00
Returns `Boolean` - Whether the image is a template image.
2016-10-04 20:34:24 +00:00
2016-10-05 15:02:04 +00:00
#### `image.crop(rect)`
2016-10-04 18:42:14 +00:00
* `rect` [Rectangle](structures/rectangle.md) - The area of the image to crop.
2016-10-04 18:42:14 +00:00
Returns `NativeImage` - The cropped image.
#### `image.resize(options)`
* `options` Object
2017-03-09 18:12:03 +00:00
* `width` Integer (optional) - Defaults to the image's width.
* `height` Integer (optional) - Defaults to the image's height.
2016-10-04 18:42:14 +00:00
* `quality` String (optional) - The desired quality of the resize image.
Possible values are `good`, `better` or `best`. The default is `best`.
These values express a desired quality/speed tradeoff. They are translated
into an algorithm-specific method that depends on the capabilities
(CPU, GPU) of the underlying platform. It is possible for all three methods
to be mapped to the same algorithm on a given platform.
Returns `NativeImage` - The resized image.
If only the `height` or the `width` are specified then the current aspect ratio
will be preserved in the resized image.
#### `image.getAspectRatio()`
Returns `Float` - The image's aspect ratio.
#### `image.addRepresentation(options)`
* `options` Object
* `scaleFactor` Double - The scale factor to add the image representation for.
2017-03-09 18:12:03 +00:00
* `width` Integer (optional) - Defaults to 0. Required if a bitmap buffer
is specified as `buffer`.
* `height` Integer (optional) - Defaults to 0. Required if a bitmap buffer
is specified as `buffer`.
* `buffer` Buffer (optional) - The buffer containing the raw image data.
* `dataURL` String (optional) - The data URL containing either a base 64
encoded PNG or JPEG image.
Add an image representation for a specific scale factor. This can be used
to explicitly add different scale factor representations to an image. This
can be called on empty images.
2016-10-04 20:34:24 +00:00
[buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer