How to Use the System Tray

The system tray is a specialized area of the desktop where users can access currently running programs. This area may be referred to differently on various operating systems. On Microsoft Windows, the system tray is referred to as the Taskbar Status Area, while on the GNU Network Object Model Environment (GNOME) Desktop it is referred to as the Notification Area. On K Desktop Environment (KDE) this area is referred to as the System Tray. However, on each system the tray area is shared by all applications running on the desktop.

The java.awt.SystemTray class introduced in Java™ SE version 6 represents the system tray for a desktop. The system tray can be accessed by calling the static SystemTray.getSystemTray() method. Before calling this method, use the static method isSupported() to check that the system tray is supported. If the system tray is not supported on this platform, the isSupported() method returns false. If the application attempts to call the getSystemTray() method in such a case, the method will throw a java.lang.UnsupportedOperationException.

An application cannot create an instance of the SystemTray class. Only a single instance created within this class can exist, and this instance can be obtained using the getSystemTray() method.

The system tray contains one or more tray icons which are added to the tray using the add(java.awt.TrayIcon) method. They can be removed when they are no longer needed with the remove(java.awt.TrayIcon) method.

The TrayIcon class functionality goes beyond the icon that is displayed in the tray. It also includes a text tooltip, a pop-up menu, ballon messages, and a set of listeners associated with it. A TrayIcon object generates various mouse events and supports the addition of corresponding listeners to receive notification of these events. The TrayIcon class processes some of the events itself. For example, by default, when a right-click is performed on the tray icon, it displays the specified pop-up menu. When a double-click is performed, the TrayIcon object generates an ActionEvent to launch an application. When the mouse pointer hovers over the tray icon, the tooltip is displayed. The icon image is automatically resized to fit the space allocated for the image on the tray.

The following demo, developed using the AWT package, demonstrates the features of SystemTray and TrayIcon classes.

Unfortunately, the current implementation of the TrayIcon class provides limited support of the Swing pop-up menu (the JPopupMenu class) and does not enable an application to use all of the capabilities of the javax.swing package. The workaround proposal for this issue is described in the Bug Database, see Bug ID 6285881.

The following code snippet shows how to add a tray icon to the system tray and apply a pop-up menu:

...
        //Check the SystemTray is supported
        if (!SystemTray.isSupported()) {
            System.out.println("SystemTray is not supported");
            return;
        }
        final PopupMenu popup = new PopupMenu();
        final TrayIcon trayIcon =
                new TrayIcon(createImage("images/bulb.gif", "tray icon"));
        final SystemTray tray = SystemTray.getSystemTray();
       
        // Create a pop-up menu components
        MenuItem aboutItem = new MenuItem("About");
        CheckboxMenuItem cb1 = new CheckboxMenuItem("Set auto size");
        CheckboxMenuItem cb2 = new CheckboxMenuItem("Set tooltip");
        Menu displayMenu = new Menu("Display");
        MenuItem errorItem = new MenuItem("Error");
        MenuItem warningItem = new MenuItem("Warning");
        MenuItem infoItem = new MenuItem("Info");
        MenuItem noneItem = new MenuItem("None");
        MenuItem exitItem = new MenuItem("Exit");
       
        //Add components to pop-up menu
        popup.add(aboutItem);
        popup.addSeparator();
        popup.add(cb1);
        popup.add(cb2);
        popup.addSeparator();
        popup.add(displayMenu);
        displayMenu.add(errorItem);
        displayMenu.add(warningItem);
        displayMenu.add(infoItem);
        displayMenu.add(noneItem);
        popup.add(exitItem);
       
        trayIcon.setPopupMenu(popup);
       
        try {
            tray.add(trayIcon);
        } catch (AWTException e) {
            System.out.println("TrayIcon could not be added.");
        }
...

The complete code for this demo is available in the TrayIconDemo.java file. This demo also uses the bulb.gif image file.

Removing the current limitations on applying Swing components will enable developers to add such components as JMenuItem (with image), JRadioButtonMenuItem, and JCheckBoxMenuItem.

The SystemTray API

Only a single instance created within SystemTray class can exist.

The TrayIcon API

A TrayIcon object represents a tray icon that can be added to the system tray. A TrayIcon object can have a tooltip (text), an image, a pop-up menu, and a set of listeners associated with it.

Examples That Use the SystemTray API