Mac Java tip: How to access Mac-specific "NSImage" icons

Part of the Mac look and feel is the use of standard icons across many applications, like the color wheel for the color picker, or the gear for advanced settings. To promote uniformity across Mac applications, Apple provides these icons via their NSImage class in the AppKit toolkit for Objective C. This article shows how to get at these same standard icons using Java on a Mac.

Introduction

In Apple's AppKit framework for Objective C, NSImage is a principal class for manipulating image data. The class also provides lots of standard icons, such as "NSComputer" for the generic Mac computer icon. These icons are documented in the NSImage Class Reference, and listed in the System-Provided Images chapter in the Apple Human Interface Guidelines.

Figure 1. The standard "NSComputer" icon on a Mac.

Getting NSImage icons

Standard icons are available to any Java application running on a Mac. To load one, call Java's getImage( ) method on the default AWT Toolkit. Instead of an image file name, pass a special pseudo-URL "NSImage://" followed by the name of the image to load. For example, to load the computer icon, use "NSImage://NSComputer". (See the Resolution Independence section of the User Interface Toolkits for Java chapter of the Java Development Guide for Mac OS X.)

Toolkit toolkit = Toolkit.getDefaultToolkit( );
Image image = toolkit.getImage( "NSImage://NSComputer" );
JLabel icon = new JLabel( new ImageIcon( image ) );

Using NSImage icons

The standard icons have conventional meanings on the Mac. If you use them, make sure that you use them with the same meanings or your users may be confused.

Also beware of assuming that a named image will always look the same. As the OS is upgraded, icons change. For example, prior to Mac OS X 10.5, the "NSDotMac" icon was a glowing blue network ball. As of Mac OS X 10.5, the icon changed to white clouds in a blue sky (the new icon for Dot Mac rebranded as Mobile Me). If you use these icons for the item they are intended to represent, then OS and icon upgrades will keep your application current. But if you use them for something else just because you like the picture, then icon changes could leave your application looking odd.

Naturally, all of these images and the "NSImage://" pseudo-URL are only available when your Java application is running on a Mac. If you are writing cross-platform code, your application will need to check the name of the platform before getting NSImages, or using images appropriate for some other platform. (See Apple's Identifying Java on Mac OS X.)

if ( System.getSystemProperty( "os.name" ).toLowerCase( ).startsWith( "mac os x" ) )
{
    // On a Mac
}

Scaling NSImage icons

Most NSImage icons are 32 x 32 pixels or smaller. A few are much larger. To use these images at a uniform size in your application, scale them up or down using getScaledInstance( ) on the image.

Toolkit toolkit = Toolkit.getDefaultToolkit( );
Image image = toolkit.getImage( "NSImage://NSApplicationIcon" );
Image scaled = image.getScaledInstance( 32, 32, Image.SCALE_SMOOTH );
JLabel icon = new JLabel( new ImageIcon( scaled ) );

Figure 2. The standard "NSApplicationIcon" icon on a Mac, scaled down from its 128x128 pixel size.

Using preferences and tool bar images

Apple provides shaded icons intended for use within preferences panes or as borderless buttons on a toolbar.

Figure 3. Shaded icons are intended for borderless buttons on toolbars and preferences panes.

Apple's system entity images represent items in the Finder.

Figure 4. System entity icons.

Apple's common preferences images are standard icons for dealing with application preferences and user accounts.

Figure 5. Preferences icons.

Apple's standard toolbar images are used on a toolbar or inspector to show or hide the Mac's color or font picker, or to show or hide an application's inspector or information window.

Figure 6. Toolbar icons.

Apple's privileges images are intended to represent "user", "group", and "all" categories of file permissions and access control lists.

Figure 7. Privileges icons.

Using generic document images

Apple's generic document images have a few standard uses. The "NSMultipleDocuments" icon is intended as a drag image used during a drag of multiple documents. The "NSApplicationIcon" and "NSMysteryDocument" icons are used for applications and files without their own icons.

Figure 8. Miscellaneous file icons.

Using template images

A template is a monochrome image intended for use within a bordered button, such as those on a toolbar. All of these can be used to generate disabled and pressed button variants. Most of these images are easily recognized from their use in the Finder and Safari.

Figure 9. Template images are intended for bordered buttons on toolbars or in inspector windows.

The four view type templates select the four viewing styles in the Finder.

Figure 10. View templates (enlarged).

Paired templates include icons for add and remove, lock and unlock, go left and go right, and so on. Note that "NSGoLeftTemplate" and "NSLeftFacingTriangleTemplate" are both left-pointing triangles. While the second one is guaranteed to always be a left-pointing triangle, in a future OS upgrade the first one might become some other shape that still means "go left". The same applies to the right-pointing triangles.

Figure 11. Template pairs (enlarged).

Apple's general-purpose templates include more familiar icons used throughout Mac OS X. Note that "NSActionTemplate" and "NSSmartBadgeTemplate" both currently use a gear icon. In a future OS upgrade, these might diverge. Such changes won't be a problem as long as you use the icons with their intended meanings.

Figure 12. Miscellaneous templates (enlarged).

Using freestanding template images

Apple's freestanding template images are intended to be used stand-alone, without a border button. For instance, the "NSFollowLinkFreestandingTemplate" may mark items that offer additional information (such as songs in iTunes that have further information in the iTunes store). The "NSStopProgressFreestandingTemplate" can be used to cancel an action (such as the cancel icon on the right side of a search text field).

Figure 13. Freestanding templates (enlarged).

Using menu images

Apple's menu images are used within menus to indicate submenus to the left and right, and menus that scroll up and down.

Figure 14. Menu images (enlarged).

Further reading

Related articles at NadeauSoftware.com

• Mac Java tip: How to create Aqua single and segmented buttons discusses Mac-specific client properties used to create different types of shaded buttons, including those used by Safari and the Finder. Using these button types along with template images creates very Mac-like user interfaces.

Web articles and specifications

• Apple's Human Interface Guidelines goes in to great depth explaining user interface components, layout, and behavior for applications on the Mac.
• Apple's Identifying Java on Mac OS X explains how to get the OS name and JDK version from system properties.
• NSImage Class Reference is the developer document page for the NSImage class in AppKit. Part of the documentation lists the icons available.
• Apple's Java Development Guide for Mac OS X discusses special considerations for Java development for the Mac. This includes a few do's and don'ts for Swing components.