rogerwang/node-webkit — pull request #2775 by mrfabbri (2014-12-09 16:32:12+00:00)
Title: Add API methods and support for styling of icons (Tray, MenuItem) under Mac OS X (Yosemite) Dark Mode 

- Add boolean property (defaults to `true`) `iconsAreTemplates` to `Tray` objects to allow for proper display of icons in Mac OS X (Yosemite) Dark Menus.
- Add boolean property (defaults to `true`) `iconsIsTemplate` to `MenuItem` objects to allow for proper display of icons in Mac OS X (Yosemite) Dark Menus.
- On Linux and Windows the introduced properties have no effect.

FIX rogerwang/node-webkit#2476
FIX rogerwang/node-webkit#2773

Mac OS X uses the `isTemplate()` property of `NSImage` objects to ensure proper styling of icons in both `NSMenuItem`s and `NSStatusItem`s. When the property is set to true the images are treated as "templates" and the system automatically ensures proper styling according to the various states of the status item (e.g. dark menu, light menu, etc.).
Template images should consist only of black and clear colours and can use the
alpha channel in the image to adjust the opacity of black content.

See [Dark Menus in AppKit Release Notes for OS X v10.10](https://developer.apple.com/library/mac/releasenotes/AppKit/RN-AppKit/#10_10DarkMenus)
and [`NSImage setTemplate:`](https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ApplicationKit/Classes/NSImage_Class/index.html#//apple_ref/occ/instm/NSImage/setTemplate:).

Further Notes:
- In naming properties (e.g. `Tray.iconsAreTemplates`) a little verbosity has been traded over making the intent more clear.
- The property defaults to true (which is the behavoiur both wanted in most cases and suggested by Apple).
- A unique property has been added controlling the "template" behaviour of both `icon` and `alticon` (it's unlikely that an app uses two different strategies, either both the images are templates or either are not).
- The "template" properties are "persistent" accross icon/alticon changes; e.g if the user changes the `icon` property of a `Tray` item which has `iconsAreTemplates` set to `true` the new `icon` will be treated as a template image (without the need to setting again `Tray.iconsAreTemplates = true`).

Example usage:

var tray;
tray = new gui.Tray({ icon: 'path-to-icon.png', iconsAreTemplates: true });
// NOTE: iconsAreTemplates option defaults to true so is superflous

var trayMenu = new gui.Menu();
trayMenu.append(new gui.MenuItem({
type: 'normal',
label: 'Menu item 1',
icon: 'path-to-icon.png',
iconIsTemplate: true // this unnaccessary as it defaults to true
}));