Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8255597

[macos11] java.awt.TrayIcon requires updates for template images

    XMLWordPrintable

    Details

    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Hide
      The only problematic case is a conflict of property names. The name of the new property is prefixed with `java.awt.` to minimize such possibility.

      Users explicitly set the property in order to enable new functionality; by default, there is no change to application behavior.
      Show
      The only problematic case is a conflict of property names. The name of the new property is prefixed with `java.awt.` to minimize such possibility. Users explicitly set the property in order to enable new functionality; by default, there is no change to application behavior.
    • Interface Kind:
      System or security property
    • Scope:
      Implementation

      Description

      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:

      Specification

      This new property will be mentioned in the javadoc for the class <code class="prettyprint" data-shared-secret="1620786826675-0.9842394638739607">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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              peterz Peter Zhelezniakov
              Reporter:
              webbuggrp Webbug Group
              Reviewed By:
              Alexandr Scherbatiy, Sergey Bylokhov
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: