Download the JDK
Search the Tutorials
Hide the TOC
Trail: Creating a GUI with JFC/Swing
Lesson: Using Other Swing Features
Using Other Swing Features
How to Integrate with the Desktop Class
How to Use Actions
How to Use Swing Timers
How to Support Assistive Technologies
How to Use the Focus Subsystem
How to Use Key Bindings
How to Use Modality in Dialogs
How to Print Tables
How to Print Text
How to Create a Splash Screen
How to Use the System Tray
Solving Common Problems Using Other Swing Features
Home Page > Creating a GUI with JFC/Swing > Using Other Swing Features
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.

> > Note: The `add()` method can throw an `AWTException` if the operating system or the Java runtime determines that the icon cannot be added to the system tray. For example, an `AWTException` will be thrown by X-Window desktops if the system tray does not exist on the desktop.

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

> > Try this:
> > 1. Place the `bulb.gif` image file in the `image` directory. Compile and run the example, consult the example index.
> > 2. The tray icon will appear in the system tray.

> > 3. Double-click the tray icon to launch the corresponding application. The dialog box will be displayed.
> > 4. Hover the mouse pointer over the tray icon and click the right mouse button. The pop-up menu appears.
> > 5. Select the Set auto size checkbox menu item. Notice that the icon appearance is changed as follows.

> > 6. Select the Set tooltip checkbox menu item. Hover the mouse pointer over the tray icon. The tooltip appears.
> > 7. Choose the About menu item. The dialog box appears. Close the dialog box.
> > 8. Choose any of the Display submenu items. Each of these items displays a message dialog box of a particular type: error, warning, info, or standard.
> > 9. Use the Exit menu item to quit the application.

> 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 pop-up = 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
>             pop-up.add(aboutItem);
>             pop-up.addSeparator();
>             pop-up.add(cb1);
>             pop-up.add(cb2);
>             pop-up.addSeparator();
>             pop-up.add(displayMenu);
>             displayMenu.add(errorItem);
>             displayMenu.add(warningItem);
>             displayMenu.add(infoItem);
>             displayMenu.add(noneItem);
>             pop-up.add(exitItem);

>             trayIcon.setPopupMenu(pop-up);

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

> > Method | Purpose
> > --- | ---
> > add | Adds a tray icon to the system tray. The tray icon becomes visible in the system tray once it is added. The order in which icons are displayed in a tray is not specified — it is platform- and implementation-dependent.
> > getSystemTray | Gets the `SystemTray` instance that represents the desktop's tray area. This method always returns the same instance per application. On some platforms the system tray may not be supported. Use the `isSupported()` method to check if the system tray is supported.
> > isSupported | Returns information as to whether the system tray is supported on the current platform. In addition to displaying the tray icon, minimal system tray support includes either a pop-up menu (see the `TrayIcon.setPopupMenu(PopupMenu)` method) or an action event (see the `TrayIcon.addActionListener(ActionListener)`).

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

> > Method | Purpose
> > --- | ---
> > setImageAutoSize | Sets the auto-size property. Auto-size determines whether the tray image is automatically sized to fit the space allocated for the image on the tray. By default, the auto-size property is set to `false`.
> > setPopupMenu | Sets the pop-up menu for this `TrayIcon` object. If pop-up is `null`, no pop-up menu will be associated with this `TrayIcon` object.
> > setToolTip | Sets the tooltip string for this `TrayIcon` object. The tooltip is displayed automatically when the mouse hovers over the icon. Setting the tooltip to `null` removes any tooltip text. When displayed, the tooltip string may be truncated on some platforms; the number of characters that may be displayed is platform-dependent.

> ### Examples That Use the SystemTray API

> > The following table lists the example that uses tray icons added to the system tray.

> > Example | Where Described | Notes
> > --- | --- | ---
> > `TrayIconDemo` | This section | Creates the tray icon in the system tray, adds a pop-up menu to the tray icon.

Previous page: How to Create a Splash Screen
Next page: Solving Common Problems Using Other Swing Features