Tutorial for Apple’s Java


Overview

This tutorial covers some Apple specific problems and features. It will show you how to utilize Mac specific features of Apple’s Java 6.

Summary

  • Basic Terms
  • Dock Menu
  • Dock icon badge and Image
  • Tray Icon
  • Changing Look and feel
  • Application adapter

Dock Menu

You can add custom items to application’s dock menu. For example, iTunes has following extra menu items: Pause, Next, Previous, etc. For adding some new items, you should create popup menu, attach it to some window and then register it.

Dock's menu - showing one extra menu item
Figure 1 - Extra menu item labeled as First item

Code is pretty simple:

// create Apple's Application object
com.apple.eawt.Application app = new Application();

// create menu and attach it to our frame
PopupMenu menu = new PopupMenu("Hello");
menu.add("First item");
jFrame.add(menu);

// set dock menu
app.setDockMenu(menu);

Don’t forget to add PopupMenu to some frame otherwise Application.setDockMenu() will throw exception. It is because every popup menu must have some parent.

Dock Icon Badge and Image

You can also add some badge to icon in the dock. It is small text in red star which informs user about count of unreaded mail, etc. Usage is pretty simple:

new Application().setDockIconBadge("3");

Text should not be more than 6 characters long. Otherwise rest of text will not be shown. If you want later to hide this text, just pass null in to method’s call. Next image shows custom icon badge:

Application's dock icon badge
Figure 2 - Custom icon badge

As you can see, application uses default icon in the dock. You can set default one using Info.plist inside application bundle (described later). If you want to change it in runtime, you can call:

new Application().setDockIconImage(image);

Don’t forget to properly load an image which should be big enough.

Tray Icon

Usage of tray icon is exactly the same as in the other OS’s. But there is a difference - image in tray icon is always in gray scale. That is because of consistent look and feel. Figure 2 shows how it looks really:

tray
Figure 3 - All icons in system tray are gray

Java honors this behavior, so you can make your icon colored without worry. In Mac OS X, it will always be gray as it should be.

You can put anything in tray icon’s menu, but there are some items which are useless in Mac. There are: quit (it is always part of system menu), settings (same as previous) and hide. Every item mentioned previously is uselss in system tray, because there are part of standart GUI. You should not add them to your tray icon’s menu, or can hide them in Mac OS X environment.

Changing Look and feel

Default look and feel (L&F) should be native. Its called Aqua in Mac OS X and it is set up by default. If you would like to use your own L&F, you should have good reason for doing that. Mac users are used to have only one (system) look. Anything that is using own L&F looks strange.

If you change L&F to different one (e. g. Ocean), you will not be able to have menu bar at correct position. Default position of Windows and Linux application is inside the frame, but on Mac, it is outside - at the top of the screen.

Menu bar at correct position - outside the window
Figure 4 - Custom Look and Feel (Ocean) with menu in correct position

You should use code listed below, otherwise the menu bar will be inside the frame, which is not correct:

// set up default l&f and remember Menu Bar UI
UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
String mbUI = UIManager.getString("MenuBarUI");

// set up our custom l&f, then override Menu Bar UI
UIManager.setLookAndFeel(new MetalLookAndFeel());
UIManager.put("MenuBarUI", mbUI);

As you can see, we must reset MenuBarUI. After doing that, you will be able to use your custom look and feel while still preserving correct position of menu bar.

Application Adapter

Applications in Mac OS X uses some set of standard actions which are not however covered in standard Java API from Sun. Those events are:
  • open application event
  • open file event
  • show preferences
  • show about dialog
  • print file event
  • quit event
  • re-open application event
As you can see, there are lot of events, but Mac OS X handles most of them gracefuly. But there are some cases which cannot be handled automaticaly. Those are Preferences... and About app dialog. Those items are standard part of every application’s menu in Mac OS X as you can see in next figure:

Standard application menu
Figure 5 - Standard application menu

You should handle first two items of this menu in your application. If you didn’t write handler (described later), Preferences menu item will not be visible and About item will only show basic about box.

The only thing you need to do is implement com.apple.eawt.ApplicationListener interface and register its implementation to com.apple.eawt.Application instance. For example:

new Application().addApplicationListener(this);

Last thing which is needed to do is getting know to Mac OS X that you have handled the event. It is very simple. For example, we have an application which has own preferences dialog and we would like to integrate it to Mac. Next example shows handler class (which implements com.apple.eawt.ApplicationListener) and one of its methods which handles opening preferences dialog.

@Override
public void handlePreferences(ApplicationEvent e) {
  e.setHandled(true);
  mainFrame.showConfigDialog();
}

As you can see we are setting handled flag to true so system know that we have handled the event by our selfs.