SystemTray JDK 1.6)

Description

public class SystemTray

The SystemTray class represents the system tray for a desktop.

The SystemTray class represents the system tray for a desktop. On Microsoft Windows it is referred to as the "Taskbar Status Area", on Gnome it is referred to as the "Notification Area", on KDE it is referred to as the "System Tray". The system tray is shared by all applications running on the desktop.

On some platforms the system tray may not be present or may not be supported, in this case SystemTray.getSystemTray() throws UnsupportedOperationException. To detect whether the system tray is supported, use SystemTray.isSupported().

The SystemTray may contain one or more TrayIcons, which are added to the tray using the SystemTray.add(java.awt.TrayIcon) method, and removed when no longer needed, using the SystemTray.remove(java.awt.TrayIcon). TrayIcon consists of an image, a popup menu and a set of associated listeners. Please see the TrayIcon class for details.

Every Java application has a single SystemTray instance that allows the app to interface with the system tray of the desktop while the app is running. The SystemTray instance can be obtained from the SystemTray.getSystemTray() method. An application may not create its own instance of SystemTray.

The following code snippet demonstrates how to access and customize the system tray:

     TrayIcon trayIcon = null;
     if (SystemTray.isSupported()) {
         // get the SystemTray instance
         SystemTray tray = SystemTray.SystemTray.getSystemTray();
         // load an image
         Image image = Toolkit.getDefaultToolkit.getImage(...);
         // create a action listener to listen for default action executed on the tray icon
         ActionListener listener = new ActionListener() {
             public void actionPerformed(ActionEvent e) {
                 // execute default action of the application
                 // ...
             }
         };
         // create a popup menu
         PopupMenu popup = new PopupMenu();
         // create menu item for the default action
         MenuItem defaultItem = new MenuItem(...);
         defaultItem.addActionListener(listener);
         popup.add(defaultItem);
         /// ... add other items
         // construct a TrayIcon
         trayIcon = new TrayIcon(image, "Tray Demo", popup);
         // set the TrayIcon properties
         trayIcon.addActionListener(listener);
         // ...
         // add the tray image
         try {
             tray.add(trayIcon);
         } catch (AWTException e) {
             System.err.println(e);
         }
         // ...
     } else {
         // disable tray option in your application or
         // perform other actions
         ...
     }
     // ...
     // some time later
     // the application state has changed - update the image
     if (trayIcon != null) {
         trayIcon.setImage(updatedImage);
     }
     // ...

See also: TrayIcon

Methods

Hide/Show inherited methods

public void add (TrayIcon trayIcon) throws AWTException

Adds a TrayIcon to the SystemTray.

Adds a TrayIcon to the SystemTray. 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.

All icons added by the application are automatically removed from the SystemTray upon application exit and also when the desktop system tray becomes unavailable.
Parameters:
- trayIcon - the TrayIcon to be added
Throws:
- NullPointerException - if trayIcon is null
- IllegalArgumentException - if the same instance of a TrayIcon is added more than once
- AWTException - if the desktop system tray is missing
See Also: SystemTray.remove(TrayIcon), SystemTray.getSystemTray(), TrayIcon, Image,

pack-privatesynchronized void addNotify ()

publicsynchronized void addPropertyChangeListener (String propertyName, PropertyChangeListener listener)

Adds a PropertyChangeListener to the listener list for a specific property.

Adds a PropertyChangeListener to the listener list for a specific property. Currently supported property:

trayIcons

This SystemTray's array of TrayIcons. The array is accessed via SystemTray.getTrayIcons().
This property is changed when a TrayIcon is added to (or removed from) the SystemTray.
For example, this property is changed when the native SystemTray becomes unavailable on the desktop
and the TrayIcons are automatically removed.

The listener listens to property changes only in this context.

If listener is null, no exception is thrown and no action is performed.
Parameters:
- propertyName - the specified property
- listener - the property change listener to be added
See Also: SystemTray.removePropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener), SystemTray.getPropertyChangeListeners(java.lang.String),

pack-privatestatic void checkSystemTrayAllowed ()

publicsynchronized PropertyChangeListener getPropertyChangeListeners (String propertyName)

Returns an array of all the listeners that have been associated with the named property.

publicstatic SystemTray getSystemTray ()

Gets the SystemTray instance that represents the desktop's tray area.

Gets the SystemTray instance that represents the desktop's tray area. This always returns the same instance per application. On some platforms the system tray may not be supported. You may use the SystemTray.isSupported() method to check if the system tray is supported.

If a SecurityManager is installed, the AWTPermission accessSystemTray must be granted in order to get the SystemTray instance. Otherwise this method will throw a SecurityException.
Returns: the SystemTray instance that represents the desktop's tray area
Throws:
- UnsupportedOperationException - if the system tray isn't supported by the current platform
- HeadlessException - if GraphicsEnvironment.isHeadless() returns true
- SecurityException - if {@code accessSystemTray} permission is not granted
See Also: SystemTray.add(TrayIcon), TrayIcon, SystemTray.isSupported(), SecurityManager.checkPermission(java.security.Permission), AWTPermission,

public TrayIcon getTrayIcons ()

Returns an array of all icons added to the tray by this application.

public Dimension getTrayIconSize ()

Returns the size, in pixels, of the space that a tray icon will occupy in the system tray.

Returns the size, in pixels, of the space that a tray icon will
occupy in the system tray. Developers may use this methods to
acquire the preferred size for the image property of a tray icon
before it is created. For convenience, there is a similar
method TrayIcon.getSize() in the TrayIcon class.
Returns: the default size of a tray icon, in pixels
See Also: TrayIcon.setImageAutoSize(boolean), Image, TrayIcon.getSize(),

publicstatic boolean isSupported ()

Returns whether the system tray is supported on the current platform.

public void remove (TrayIcon trayIcon)

Removes the specified TrayIcon from the SystemTray.

All icons added by the application are automatically removed from the SystemTray upon application exit and also when the desktop system tray becomes unavailable.

If trayIcon is null or was not added to the system tray, no exception is thrown and no action is performed.
Parameters:
- trayIcon - the TrayIcon to be removed
See Also: SystemTray.add(TrayIcon), TrayIcon,

publicsynchronized void removePropertyChangeListener (String propertyName, PropertyChangeListener listener)

Removes a PropertyChangeListener from the listener list for a specific property.

The PropertyChangeListener must be from this context.

If propertyName or listener is null or invalid, no exception is thrown and no action is taken.
Parameters:
- propertyName - the specified property
- listener - the PropertyChangeListener to be removed
See Also: SystemTray.addPropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener), SystemTray.getPropertyChangeListeners(java.lang.String),