Summary

Add a new system property to indicate that template images are being used by tray icons. This would help desktop apps look more like native (currently on MacOSX only).

Problem

According to Apple's human interface guidelines, developers should use template images for tray icons. This way icons stay visible when desktop theme or wallpaper change. On the API level, this means setting the NSImage::isTemplate flag.

Currently there's no way in Java to set this flag. Even if one uses a template (black and transparent pixels only) image, MacOS will not recognize it as such. As a result, the image may not be visible when using dark theme.

Solution

Add a new property, apple.awt.enableTemplateImages. When the value of this property is true, all tray icon images are treated as template images. It is the developers' responsibility to ensure their images are indeed templates. The default value is false.

This setting currently affects MacOSX only. In Windows 10, they apparently use template images for system applets such as network and input language chooser, but there is no external API so far.

References:

• Apple Developer Guidelines page describing the policy
• AWT Dev thread discussing the issue
• Yet another discussion provides more technical details

Specification

This new property will be mentioned in the javadoc for the class <code class="prettyprint" data-shared-secret="1745025122782-0.7274583365044156">java.awt.TrayIcon</code>:

@@ -69,10 +69,19 @@ import java.security.AccessController;
  * <p>If a SecurityManager is installed, the AWTPermission
  * {@code accessSystemTray} must be granted in order to create
  * a {@code TrayIcon}. Otherwise the constructor will throw a
  * SecurityException.
  *
+ * <p>
+ * @implnote
+ * When the {@systemProperty apple.awt.enableTemplateImages} property is
+ * set, all images associated with instances of this class are treated
+ * as template images by the native desktop system. This means all color
+ * information is discarded, and the image is adapted automatically to
+ * be visible when desktop theme and/or colors change. This property
+ * only affects MacOSX.
+ *
  * <p> See the {@link SystemTray} class overview for an example on how
  * to use the {@code TrayIcon} API.
  *
  * @since 1.6
  * @see SystemTray#add