< Previous PageNext Page >

Hide TOC

User Interface Toolkits for Java

This article discusses how the Mac OS X implementation of the Swing, AWT, accessibility, and sound user interface toolkits differ from other platforms. Although there is some additional functionality in Mac OS X, for the most part these toolkits work as you would expect them to on other platforms. This chapter does not discuss user interface design issues that you should consider in Mac OS X. For that information see “Making User Interface Decisions.”

Swing

In Mac OS X, Swing uses apple.laf.AquaLookAndFeel as the default look and feel (LAF). Swing attempts to be platform neutral, but there are some parts of it that are at odds with the Aqua user interface. Apple has tried to bridge the gap with a common ground that provides both developers and users an experience that is not foreign. This section discusses a few details where the Aqua LAF differs from the default implementation on other platforms.

While testing your application, you might want to test it on the standard Java Metal LAF as well as Aqua. To run your application with Metal, pass the -Dswing.defaultlaf=javax.swing.plaf.metal.MetalLookAndFeel flag to java.

JMenuBars

Macintosh users expect to find their menus in the same spot – no matter what window they have open – at the top of the screen in the menu bar. In the default Metal LAF, as well as the Windows LAF, menus are applied on a per-frame basis inside the window under the title bar.

To get menus out of the window and into the menu bar you need only to set a single system property:

apple.laf.useScreenMenuBar

This property can have a value of true or false. By default it is false, which means menus are in the window instead of the menu bar. When set to true, the Java runtime moves any given JFrame’s JMenuBar to the top of the screen, where Macintosh users expect it. Since this is just a simple runtime property that only the Mac OS X VM looks for, there is no harm in putting it into your cross-platform code base.

Note that this setting does not work for JDialogs that have JMenus. A dialog should be informational or present the user with a simple decision, not provide complex choices. If users are performing actions in a dialog, it is not really a dialog and you should consider a JFrame instead of a JDialog.

JTabbedPanes

Another example of a difference in Mac OS X is with JTabbedPanes. With other LAFs, if you have JTabbedPane with too many tabs to fit in the parent window – they just get stacked on top of each other as shown in Figure 1.

Figure 1 A tabbed pane with multiple tabs on another platform

In the Aqua user interface of Mac OS X, tab controls are never stacked. The Aqua LAF implementation of multiple tabs includes a special tab on the right that exposes a pull-down menu to navigate to the tabbed panes not visible. This behavior, shown in Figure 2 allows you to program your application just as you would on any other platform, but provides users an experience that is more consistent with Mac OS X.

Figure 2 A tabbed pane with multiple tabs in Mac OS X

One other thing to keep in mind about JTabbedPanes in the Aqua look and feel is that they have a standard size. If you put an image in a tab, the image is scaled to fit the tab instead of the tab to the image.

Component Sizing

Aqua has very well-defined guidelines for the size of its widgets. Swing, on the other hand, does not. The Aqua LAF tries to find a common ground. Since any combo box larger than twenty pixels would look out of place in Mac OS X, that is all that is displayed, even if the actual size of the combo box is bigger. For example, Figure 3 shows a very large JComboBox in Windows XP. Note that the drop-down scrolling list appears at the bottom of the button. The same code yields quite a different look in Mac OS X, as can be seen in Figure 4. The visible button is sized to that of a standard Aqua combo box. The drop-down list appears at the bottom of the visible button. The entire area that is active on other platforms is still active, but the button itself doesn’t appear as large.

Figure 3 Oversize JComboBox in Windows

Figure 4 Oversize JComboBox in the Aqua LAF

Note that some other components have similar sizing adjustments to align with the standards set in Apple Human Interface Guidelines for example, scroller and sliders. The JComboBox example is an extreme example. Most are not as large, but this gives you an idea of how the Aqua LAF handles this type of situation.

Buttons

There are basically three button types in Mac OS X:

Push buttons which are rounded rectangles with text labels on them.
Radio buttons which are in sets of two to seven circular buttons. They are for making mutually exclusive, but related choices.
Bevel buttons which can display text, an icon, or a picture that can be either a standard push button or have a menu attached.
Bevel buttons normally have rounded corners. When displayed in a toolbar or when sizing constraints are tight, the corners are squared off.

To be consistent with these button types and their defined use in Mac OS X, there are a some nuances of Swing buttons that you should be aware of:

JButtons with images in them are rendered as bevel buttons by default.
A default JButton that contains only text is usually rendered as a push button. (Over a certain height, it is rendered as a bevel button, since Aqua push buttons are limited in their height.)
JButtons in a toolbar are rendered as bevel buttons with square, not rounded edges.

In addition to these default characteristics which are dependent on height and the contents of the button, you can also explicitly set the type of button with JButton.buttontype which accepts toolbar, icon, or text. toolbar gives you square bevel button, icon gives you a rounded bevel button, and text gives you a push button. Keep the Apple Human Interface Guidelines in mind if you explicitly set a button type.

AWT

By its nature, AWT is very different on every platform and there are a few high level things to keep in mind about AWT in Mac OS X. These details are explored in the following sections.

Accelerator Key

The value of the accelerator key can be determined by calling Toolkit.getDefaultToolkit().getMenuShortcutKeyMask(). This is further discussed in “ Accelerators (Keyboard Shortcuts).”

Font Encoding

The default font encoding in Mac OS X is MacRoman. The default font encoding on some other platforms is ISO-Latin-1 or WinLatin-1. These are subsets of UTF-8 which means that files or filenames can be turned into UTF-8 by just turning a byte into a char. Programs that assume this behavior cause problems in Mac OS X.

The simplest way to work around this problem is to specify a font encoding explicitly rather than assuming one.

If you do not specify a font encoding explicitly, recognize that:

In the conversion from Unicode to MacRoman you may lose information.
Filenames are not stored on disk in the default font encoding, but in UTF-8. Usually this isn’t a problem, since most files are handled in Java as java.io.Files, though it is good to be aware of.
Although filenames are stored on disk as UTF-8, they are stored decomposed. This means certain characters, like e-acute (é) are store as two characters, “e”, followed by “´” (acute accent). The default HFS+ filesystem of Mac OS X enforces this behavior. SMB enforces composed Unicode characters. UFS and NFS do not specify whether filenames are stored composed or decomposed, so they can do either.

Minimum Window Size

Mac OS X does not specify a default minimum size for windows. To avoid a 0 by 0 (0x0) pixel window being opened, the following default minimum sizes for Java windows are enforced:

Borderless windows have a minimum size of 1 by 1 (1x1).
Windows with a title bar have a minimum size of 128 by 32 (128x32).

Full-Screen Exclusive Mode

In J2SE 5.0 and Java 1.4, java.awt.GraphicsDevice includes methods for controlling the full screen of a client computer through Java. In addition to these standard tools, Mac OS X provides a few system properties that may be useful for development of full-screen Java applications. These are discussed in Java System Properties.

Accessibility

With some other platforms, the use of the Java Accessibility API requires the use of a native bridge. This is not necessary in Mac OS X. The code needed to bridge the Accessibility API to the native operating system is built in. Users can configure the accessibility features of Mac OS X through the Universal Access pane of System Preferences. If you are using the Accessibility API, your application can use devices that the user has configured there.

Beginning with Mac OS X v10.4, a screen reader call VoiceOver is included with the operating system. Your Java application automatically utilizes this technology.

Security

In Mac OS X v10.4, Java applications that utilize Kerberos automaticially access the system credentials cache and tickets.

Apple also includes a cryptographic service provider based on the Java Cryptography Architecture. Currently, the following algorithms are supported:

Mac: MD5, SHA1
Message Digest: MD5, SHA1
Secure Random: YarrowPRNG

Java on Mac OS X v10.4 features an implementation of KeyStore that uses the Mac OS X Keychain as its permanent store. You can get an instance of this implementation by using code like this:

keyStore = KeyStore.getInstance("KeychainStore", "Apple");

See the reference documentation on java.security.KeyStore for more usage information.

Sound

Java sound input is supported only at a frame rate of 44100 (in PCM encoding, mono or stereo, 8 or 16 bits per sample) by the Core Audio framework. If you need a different frame rate, you can easily resample in your application.

By default, the Java sound engine in Mac OS X uses the midsize sound bank from http://java.sun.com/products/java-media/sound/soundbanks.html.

Input Methods

Mac OS X supports Java input methods. The utility application Input Method Hot Key, installed in /Applications/Utilities/Java/, allows you to configure a trigger for input methods. You can download sample input methods from http://java.sun.com/products/jfc/tsc/articles/InputMethod/inputmethod.html.

Java 2D

As with Java on other platforms, the Java2D API takes advantage of the native platform to provide behavior that is as close as possible to the behavior of a native application. In Mac OS X, the Java2D API is based on Apple’s Quartz graphics engine. (See http://developer.apple.com/graphicsimaging/quartz/ for more information.) This results in some general differences between Java in Mac OS X and on some other platforms.

In Mac OS X, Java windows are double-buffered. The Java implementation itself attempts to flush the buffer to the screen often enough to have good drawing behavior without compromising performance. If for some reason you need to force window buffers to be flushed immediately, you may do so with Toolkit.sync.

Normally Quartz displays text anti-aliased. Therefore by default, Java2D renders text in the Aqua LAF for Swing with KEY_ANTIALIASING set to VALUE_ANTIALIAS_ON. It can be turned off using the properties described in Java System Properties, or by calling java.awt.Graphics.setRenderingHint within your Java application. Note that in applets, anti-aliasing is turned off be default.

Since anti-aliasing is handled by Quartz, whether it is on or off does not noticeably affect the graphics performance of your Java code. One reason for turning it off might be to try to get a closer pixel-for-pixel match of your images and text with what you are using on other platforms. Recognize that if you turn off anti-aliasing haphazardly in your application, it can make it look out of place in the Mac OS X environment, and even with anti-aliasing off, you still will not see an exact pixel-for-pixel match across platforms.

On any platform, anti-aliased text and graphics look different from aliased images or text. If the native platform supports and encourages it, you should design your code so that you do not depend on an exact pixel-for-pixel match between platforms regardless of whether or not anti-aliasing is on. Quartz, for example, takes advantage of both colors and transparency for its anti-aliasing instead of just color; differences between it and other platforms are therefore very distinct. Note the differences illustrated in Figure 5 and Figure 6.

Figure 5 Anti-aliased text in Mac OS X

Figure 6 Anti-aliased text in Windows XP

The algorithms used to determine anti-aliasing take many variables into account which means you cannot erase a line by just drawing over it with a line of a different color. For example, drawing a white line on top of a black line does not completely erase the line; the compositing rules leave some pixels around the edges. You end up with a blurred outline of your original image. Also, drawing text multiple times in the same place causes the partially covered pixels along the edges to get darker and darker, making the text look smudged as can be seen in Figure 7. Similarly, do not count on using XOR mode to repaint images. Whenever you are using anti-aliasing, as you often do by default in Mac OS X, repaint the graphics context if you need to replace text or an image.

Figure 7 Painting the same image multiple times