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

Technologies: Java 5+, Mac OS X 10.5+

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.


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.

NSComputer icon
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( "" ).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 ) );
Scaled versions of an image
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.

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

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

System icons
Figure 4. System entity icons.

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

Preferences icons
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.

Toolbar icons
Figure 6. Toolbar icons.

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

User icons
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.

File 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.

Example with bordered buttons
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.

View templates
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.

Template pairs
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.

Misc templates
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).

Freestanding templates
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.

Menu images
Figure 14. Menu images (enlarged).

Further reading

Related articles at

Web articles and specifications


Post new comment

The content of this field is kept private and will not be shown publicly.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.
  • Web page addresses and e-mail addresses turn into links automatically.

More information about formatting options

Nadeau software consulting
Nadeau software consulting