diff --git a/docs/api/native-image.md b/docs/api/native-image.md index f03178577b86..5db9fa6fa8a9 100644 --- a/docs/api/native-image.md +++ b/docs/api/native-image.md @@ -3,7 +3,7 @@ > 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`: @@ -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 @@ -91,21 +91,21 @@ 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'); ``` @@ -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.