refactor: make templateImage a property on nativeImage (#18124)

* refactor: make templateImage a property on nativeImage

* Update docs/api/native-image.md

Co-Authored-By: codebytere <[email protected]>

* fix nativeImage prototype deprecation

* update for new property name

* Update docs/api/native-image.md

Co-Authored-By: codebytere <[email protected]>

atom/common/api/atom_api_native_image.cc

@@ -638,8 +638,10 @@ void NativeImage::BuildPrototype(v8::Isolate* isolate,
       .SetMethod("toDataURL", &NativeImage::ToDataURL)
       .SetMethod("isEmpty", &NativeImage::IsEmpty)
       .SetMethod("getSize", &NativeImage::GetSize)
-      .SetMethod("setTemplateImage", &NativeImage::SetTemplateImage)
-      .SetMethod("isTemplateImage", &NativeImage::IsTemplateImage)
+      .SetMethod("_setTemplateImage", &NativeImage::SetTemplateImage)
+      .SetMethod("_isTemplateImage", &NativeImage::IsTemplateImage)
+      .SetProperty("isMacTemplateImage", &NativeImage::IsTemplateImage,
+                   &NativeImage::SetTemplateImage)
       .SetMethod("resize", &NativeImage::Resize)
       .SetMethod("crop", &NativeImage::Crop)
       .SetMethod("getAspectRatio", &NativeImage::GetAspectRatio)

docs/api/modernization/property-updates.md

@@ -30,8 +30,6 @@ The Electron team is currently undergoing an initiative to convert separate gett
 * `DownloadItem` class
   * `savePath`
   * `paused`
-* `NativeImage`
-  * `templateImage`
 * `Session` module
   * `preloads`
 * `SystemPreferences` module
@@ -58,3 +56,5 @@ The Electron team is currently undergoing an initiative to convert separate gett
   * `applicationMenu`
   * `badgeCount`
   * `name`
+* `NativeImage`
+  * `isMacTemplateImage`

docs/api/native-image.md

@@ -71,7 +71,6 @@ images/
 └── [email protected]
 ```
 
-
 ```javascript
 const { Tray } = require('electron')
 let appIcon = new Tray('/Users/somebody/images/icon.png')
@@ -276,10 +275,14 @@ Returns [`Size`](structures/size.md)
 
 Marks the image as a template image.
 
+**[Deprecated Soon](modernization/property-updates.md)**
+
 #### `image.isTemplateImage()`
 
 Returns `Boolean` - Whether the image is a template image.
 
+**[Deprecated Soon](modernization/property-updates.md)**
+
 #### `image.crop(rect)`
 
 * `rect` [Rectangle](structures/rectangle.md) - The area of the image to crop.
@@ -324,3 +327,11 @@ to explicitly add different scale factor representations to an image. This
 can be called on empty images.
 
 [buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer
+
+## Properties
+
+### `nativeImage.isMacTemplateImage` _macOS_
+
+A `Boolean` property that determines whether the image is considered a [template image](https://developer.apple.com/documentation/appkit/nsimage/1520017-template).
+
+Please note that this property only has an effect on macOS.

lib/common/api/native-image.js

@@ -1,5 +1,8 @@
 'use strict'
 
-const { nativeImage } = process.electronBinding('native_image')
+const { deprecate } = require('electron')
+const { NativeImage, nativeImage } = process.electronBinding('native_image')
+
+deprecate.fnToProperty(NativeImage.prototype, 'isMacTemplateImage', '_isTemplateImage', '_setTemplateImage')
 
 module.exports = nativeImage

spec/api-native-image-spec.js

@@ -105,6 +105,34 @@ describe('nativeImage module', () => {
     return matchingImage
   }
 
+  describe('isMacTemplateImage property', () => {
+    before(function () {
+      if (process.platform !== 'darwin') this.skip()
+    })
+
+    it('returns whether the image is a template image', () => {
+      const image = nativeImage.createFromPath(path.join(__dirname, 'fixtures', 'assets', 'logo.png'))
+
+      expect(image.isMacTemplateImage).to.be.a('boolean')
+
+      expect(image.isTemplateImage).to.be.a('function')
+      expect(image.setTemplateImage).to.be.a('function')
+    })
+
+    it('correctly recognizes a template image', () => {
+      const templateImage = nativeImage.createFromPath(path.join(__dirname, 'fixtures', 'assets', 'logo_Template.png'))
+      expect(templateImage.isMacTemplateImage).to.be.true()
+    })
+
+    it('sets a template image', function () {
+      const image = nativeImage.createFromPath(path.join(__dirname, 'fixtures', 'assets', 'logo.png'))
+      expect(image.isMacTemplateImage).to.be.false()
+
+      image.isMacTemplateImage = true
+      expect(image.isMacTemplateImage).to.be.true()
+    })
+  })
+
   describe('createEmpty()', () => {
     it('returns an empty image', () => {
       const empty = nativeImage.createEmpty()