'

Creating tray icons in Java

Lee Chuk-Munn shows you how to create tray icons which sit on the desktop computer's system tray.

A tray icon is a long-lived application that sits on your computer desktop's system tray. Figure 1 shows some examples of tray icons in the authors system tray.


Figure 1 Examples of tray icons in a system tray

Typical examples of tray icons are e-mail watcher, buddy notifier in a chatroom, alarm, weather, sticky-notes, and RSS. A typical tray icon has the following properties and behaviors:

  • It is represented by an image. The image may change to notify the user that an event has occured. For example, a Biff tray icon may change its icon to notify the user that new mail has arrived
  • A tooltip may appear when you place your mouse pointer over the tray icon as shown in Figure 2

  • Figure 2 A tray icon's tooltip

    Again, the tip may change depending on the event of the tray icon. Returning to our Biff example, the tip may indicate the status of an Inbox by either show the number of new mail received or empty, if there are no new mail.

  • The tray icon may also respond to a left or right mouse click; the mouse click may trigger different behavior in the tray icon. Using our Biff example again, a left mouse click may launch the e-mail client while a right click may trigger a popup menu.
  • Until recently, it has been quite difficult to create Java based tray icons applications. JavaSE 6 (aka Mustang) now supports tray icon development with the TrayIcon API. Here are the steps to create your first tray icon application:

    1. You will first need to check if the system tray functionality is supported on your operating system. SystemTray is currently supported on Sun's JDS, KDE, Gnome and Windows. Once we have verified that the system tray is supported, we get an instance of SystemTray via a factory method. The following is a code snippet to show you how this is done:

    //Check if SystemTray is supported. If not supported we exit
    if (!SystemTray.isSupported()) {
       System.err.println("Your operating system does not support SystemTray.");
       System.exit(-1);
    }
    SystemTray systemTray = SystemTray.getSystemTray();

    1. A TrayIcon is created with 3 pieces of information; you need to specify an image (Image) to represent it in the system tray. The image is mandatory. The second piece of information is the tooltip text, and the third piece of information is a popup menu (PopupMenu). The last two items are optional.

    //Load an image for the tray icon. loadImage() is a private method
    //not shown here
    Image iconImage = loadImage("some/image/resource/image.png");

    //Create the popup menu and add some menu item to it
    PopupMenu popupMenu = new PopupMenu("Actions");

    MenuItem menuItem = new MenuItem("Action 1");

    //Set a unique command name for this particular menu item
    menuItem.setActionCommand("Action1");

    //Assume that the class has implemented ActionListener
    menuItem.addActionListener(this /* handler */);

    //Add the menu item to the popup menu
    popupMenu.add(menuItem);
    ...

    //Create the TrayIcon
    TrayIcon trayIcon = new TrayIcon(iconImage, "My Tray Icon", popupMenu);

    1. Add an action listener to receive action event or left mouse click. The tray icon can receive mouse and mouse motion events as well. When you left click on your mouse on a tray icon, it will generate a ActionEvent. But if you are also planning to use the popup menu like we did above, then you need to name the generated ActionEvent with the setActionCommand() method.

    //Give a name for the left click ActionEvent
    trayIcon.setActionCommand("LeftClick");

    //Set the class that will handle the mouse click event
    //this implements ActionListener

    trayIcon.addActionListenr(this);

    1. The event handle method will look something like this:

    //Give a name for the left click ActionEvent
    public void actionPerformed(ActinEvent aEvt) {

       //Get the name of the event
       String cmd = aEvt.getActionCommand();

       //Now decide how we are going to handle this event
       if (cmd.equals("LeftClick") {
          //handle LeftClick
          ...
       } else if (cmd.equals("Action1") {
          //handle action from menu item
          ...
       } ...

    }

    1. Once we have completed the setup of our trayIcon instance, we can now install it on the system tray like so:

    systemTray.add (trayIcon);

    1. You can also display a popup message like informing the user that a high priority e-mail has arrived. This is different from tooltip in that for a tooltip to be displayed, you have to move your mouse over a tray icon. Popup messages are control programatically. Figure 3 shows how a system tray's message box looks like.


    Figure 3 Displaying a tray icon message

    For example to display a "Updating feeds..." message as information, do the following:

    displayMessage ("Update", "Updating feeds...", TrayIcon.INFO);

    The following is an example of an extremely simple RSS tray icon. The tray icon gets its feed from the planetnetbeans.org Web site. A left click will trigger the tray icon to retrieve the latest feed from the planetnetbeans.org Web site. A right click will list all the feeds. You can get the RSS tray icon source here. This is a NetBeans project directory (which is based on Ant). You can either use NetBeans--or any other editor or IDE--to open and build it .

    Unzip the source. To run the the RSS tray icon, change directory into rssfeed/dist directory and type the following:

    java -jar rssfeed.jar

    or the following if you are using Windows

    javaw -jar rssfeed.jar

    Note: rssfeed.jar is dependent on rome-0.8.jar and jdom.jar. which can be found in rssfeed/dist directory as well.

    Lee Chuk-Munn has been programming in the Java language since 1996, when he first joined Sun Microsystems in Hong Kong. He currently works as a senior developer consultant and technology evangelist for Technology Outreach at Sun in Singapore. Chuk's focus is in Java APIs, Java EE, Java SE, and Java ME. Chuk graduated in 1987 from the Royal Melbourne Institute of Technology in Melbourne, Australia, where his favorite subject was compiler theory.