OpenJDK 27 · java.awt.SystemTray · APIdia, the JavaDoc alternative

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 add method, and removed when no longer needed, using the remove. 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 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.getSystemTray;
        // load an image
        java.awt.Image image = Toolkit.getDefaultToolkit().getImage(...);
        // create a action listener to listen for default action executed on the tray icon
        java.awt.event.ActionListener listener = new ActionListener() {
            public void actionPerformed(java.awt.event.ActionEvent e) {
                // execute default action of the application
                // ...
            }
        };
        // create a popup menu
        java.awt.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);
    }
    // ...

Field Summary

Modifier and Type	Field and Description
private PropertyChangeSupport	changeSupport
private int	currentIconID
private static final TrayIcon[]	EMPTY_TRAY_ARRAY
private Vector<TrayIcon>	icons
private transient SystemTrayPeer	peer
private static SystemTray	systemTray

Constructor Summary

Access	Constructor and Description
private	SystemTray() Private `SystemTray` constructor.

Method Summary

Modifier and Type	Method and Description
public void	add(TrayIcon the `TrayIcon` to be added trayIcon) Adds a `TrayIcon` to the `SystemTray`.
pack-priv synchronized void	addNotify()
public synchronized void	addPropertyChangeListener(String the specified property propertyName, PropertyChangeListener the property change listener to be added listener) Adds a `PropertyChangeListener` to the list of listeners for the specific property.
private void	firePropertyChange(String the property whose value has changed propertyName, Object the property's previous value oldValue, Object the property's new value newValue) Support for reporting bound property changes for Object properties.
private synchronized PropertyChangeSupport	Returns: the current PropertyChangeSupport for this `SystemTray` getCurrentChangeSupport() Returns the current PropertyChangeSupport instance
public synchronized PropertyChangeListener[]	Returns: all of the `PropertyChangeListener`s associated with the named property; if no such listeners have been added or if `propertyName` is `null` or invalid, an empty array is returned getPropertyChangeListeners(String the specified property propertyName) Returns an array of all the listeners that have been associated with the named property.
public static SystemTray	Returns: the `SystemTray` instance that represents the desktop's tray area getSystemTray() Gets the `SystemTray` instance that represents the desktop's tray area.
public TrayIcon[]	Returns: an array of all tray icons added to this tray, or an empty array if none has been added getTrayIcons() Returns an array of all icons added to the tray by this application.
public Dimension	Returns: the default size of a tray icon, in pixels getTrayIconSize() Returns the size, in pixels, of the space that a tray icon will occupy in the system tray.
private static void	initializeSystemTrayIfNeeded()
public static boolean	Returns: `false` if no system tray access is supported; this method returns `true` if the minimal system tray access is supported but does not guarantee that all system tray functionality is supported for the current platform isSupported() Returns whether the system tray is supported on the current platform.
public void	remove(TrayIcon the `TrayIcon` to be removed trayIcon) Removes the specified `TrayIcon` from the `SystemTray`.
public synchronized void	removePropertyChangeListener(String the specified property propertyName, PropertyChangeListener the PropertyChangeListener to be removed listener) Removes a `PropertyChangeListener` from the listener list for a specific property.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

changeSupport	back to summary
private PropertyChangeSupport changeSupport

currentIconID	back to summary
private int currentIconID

EMPTY_TRAY_ARRAY	back to summary
private static final TrayIcon[] EMPTY_TRAY_ARRAY

icons	back to summary
private Vector<TrayIcon> icons

peer	back to summary
private transient SystemTrayPeer peer

systemTray	back to summary
private static SystemTray systemTray

Constructor Detail

SystemTray	back to summary
private SystemTray() Private `SystemTray` constructor.

Method Detail

add back to summary

add	back to summary
public void add(TrayIcon trayIcon) throws AWTException 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:TrayIcon the `TrayIcon` to be added Exceptions AWTException: if the desktop system tray is missing NullPointerException: if `trayIcon` is `null` IllegalArgumentException: if the same instance of a `TrayIcon` is added more than once See Also `remove(TrayIcon)`, `getSystemTray`, `TrayIcon`, `java.awt.Image`

public void add(TrayIcon trayIcon) throws AWTException

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:TrayIcon: the TrayIcon to be added

Exceptions

AWTException:: if the desktop system tray is missing
NullPointerException:: if trayIcon is null
IllegalArgumentException:: if the same instance of a TrayIcon is added more than once

addNotify	back to summary
pack-priv synchronized void addNotify()

addPropertyChangeListener back to summary

public synchronized void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)

Adds a PropertyChangeListener to the list of listeners for the specific property. The following properties are currently supported:

SystemTray properties
Property	Description
`trayIcons`	The `SystemTray`'s array of `TrayIcon` objects. The array is accessed via the `getTrayIcons` method. This property is changed when a tray icon is added to (or removed from) the system tray. For example, this property is changed when the system tray becomes unavailable on the desktop and the tray icons are automatically removed.
`systemTray`	This property contains `SystemTray` instance when the system tray is available or `null` otherwise. This property is changed when the system tray becomes available or unavailable on the desktop. The property is accessed by the `getSystemTray` method.

If listener is null, no exception is thrown and no action is performed.

Parameters

propertyName:String: the specified property
listener:PropertyChangeListener: the property change listener to be added

firePropertyChange	back to summary
private void firePropertyChange(String propertyName, Object oldValue, Object newValue) Support for reporting bound property changes for Object properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners. Parameters propertyName:String the property whose value has changed oldValue:Object the property's previous value newValue:Object the property's new value

firePropertyChange

back to summary

private void firePropertyChange(String propertyName, Object oldValue, Object newValue)

Support for reporting bound property changes for Object properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.

Parameters

propertyName:String: the property whose value has changed
oldValue:Object: the property's previous value
newValue:Object: the property's new value

getCurrentChangeSupport back to summary

getCurrentChangeSupport	back to summary
private synchronized PropertyChangeSupport getCurrentChangeSupport() Returns the current PropertyChangeSupport instance Returns:PropertyChangeSupport the current PropertyChangeSupport for this `SystemTray`

private synchronized PropertyChangeSupport getCurrentChangeSupport()

Returns the current PropertyChangeSupport instance

Returns:PropertyChangeSupport: the current PropertyChangeSupport for this SystemTray

getPropertyChangeListeners back to summary

getPropertyChangeListeners	back to summary
public synchronized PropertyChangeListener[] getPropertyChangeListeners(String propertyName) Returns an array of all the listeners that have been associated with the named property. Parameters propertyName:String the specified property Returns:PropertyChangeListener[] all of the `PropertyChangeListener`s associated with the named property; if no such listeners have been added or if `propertyName` is `null` or invalid, an empty array is returned See Also `addPropertyChangeListener`, `removePropertyChangeListener`

public synchronized PropertyChangeListener[] getPropertyChangeListeners(String propertyName)

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

Parameters

propertyName:String: the specified property

Returns:PropertyChangeListener[]

all of the PropertyChangeListeners associated with the named property; if no such listeners have been added or if propertyName is null or invalid, an empty array is returned

getSystemTray back to summary

getSystemTray	back to summary
public static SystemTray getSystemTray() 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 `isSupported` method to check if the system tray is supported. Returns:SystemTray the `SystemTray` instance that represents the desktop's tray area Exceptions UnsupportedOperationException: if the system tray isn't supported by the current platform HeadlessException: if `GraphicsEnvironment.isHeadless()` returns `true` See Also `add(TrayIcon)`, `TrayIcon`, `isSupported`

public static SystemTray getSystemTray()

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 isSupported method to check if the system tray is supported.

Returns:SystemTray

the SystemTray instance that represents the desktop's tray area

Exceptions

UnsupportedOperationException:: if the system tray isn't supported by the current platform
HeadlessException:: if GraphicsEnvironment.isHeadless() returns true

getTrayIcons back to summary

getTrayIcons	back to summary
public TrayIcon[] getTrayIcons() Returns an array of all icons added to the tray by this application. You can't access the icons added by another application. The returned array is a copy of the actual array and may be modified in any way without affecting the system tray. To remove a `TrayIcon` from the `SystemTray`, use the `remove(TrayIcon)` method. Returns:TrayIcon[] an array of all tray icons added to this tray, or an empty array if none has been added See Also `add(TrayIcon)`, `TrayIcon`

public TrayIcon[] getTrayIcons()

Returns an array of all icons added to the tray by this application. You can't access the icons added by another application.

The returned array is a copy of the actual array and may be modified in any way without affecting the system tray. To remove a TrayIcon from the SystemTray, use the remove(TrayIcon) method.

Returns:TrayIcon[]: an array of all tray icons added to this tray, or an empty array if none has been added
See Also: add(TrayIcon), TrayIcon

getTrayIconSize back to summary

getTrayIconSize	back to summary
public Dimension getTrayIconSize() Returns the size, in pixels, of the space that a tray icon will occupy in the system tray. Developers may use this method to acquire the preferred size for the tray icon before it is created. For convenience, there is a similar method `TrayIcon#getSize` in the `TrayIcon` class. Returns:Dimension the default size of a tray icon, in pixels See Also `TrayIcon#setImageAutoSize(boolean)`, `java.awt.Image`, `TrayIcon#getSize()`

public Dimension getTrayIconSize()

Returns the size, in pixels, of the space that a tray icon will occupy in the system tray. Developers may use this method to acquire the preferred size for the tray icon before it is created. For convenience, there is a similar method TrayIcon#getSize in the TrayIcon class.

Returns:Dimension: the default size of a tray icon, in pixels
See Also: TrayIcon#setImageAutoSize(boolean), java.awt.Image, TrayIcon#getSize()

initializeSystemTrayIfNeeded	back to summary
private static void initializeSystemTrayIfNeeded()

isSupported back to summary

isSupported	back to summary
public static boolean isSupported() Returns whether the system tray is supported on the current platform. In addition to displaying the tray icon, minimal system tray support includes either a popup menu (see `TrayIcon#setPopupMenu(PopupMenu)`) or an action event (see `TrayIcon#addActionListener(ActionListener)`). Developers should not assume that all of the system tray functionality is supported. To guarantee that the tray icon's default action is always accessible, add the default action to both the action listener and the popup menu. See the `example` for an example of how to do this. Note When implementing `SystemTray` and `TrayIcon` it is strongly recommended that you assign different gestures to the popup menu and an action event. Overloading a gesture for both purposes is confusing and may prevent the user from accessing one or the other. Returns:boolean `false` if no system tray access is supported; this method returns `true` if the minimal system tray access is supported but does not guarantee that all system tray functionality is supported for the current platform See Also `getSystemTray`

public static boolean isSupported()

Returns whether the system tray is supported on the current platform. In addition to displaying the tray icon, minimal system tray support includes either a popup menu (see TrayIcon#setPopupMenu(PopupMenu)) or an action event (see TrayIcon#addActionListener(ActionListener)).

Developers should not assume that all of the system tray functionality is supported. To guarantee that the tray icon's default action is always accessible, add the default action to both the action listener and the popup menu. See the example for an example of how to do this.

Note

When implementing SystemTray and TrayIcon it is strongly recommended that you assign different gestures to the popup menu and an action event. Overloading a gesture for both purposes is confusing and may prevent the user from accessing one or the other.

Returns:boolean: false if no system tray access is supported; this method returns true if the minimal system tray access is supported but does not guarantee that all system tray functionality is supported for the current platform
See Also: getSystemTray

remove back to summary

remove	back to summary
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:TrayIcon the `TrayIcon` to be removed See Also `add(TrayIcon)`, `TrayIcon`

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:TrayIcon: the TrayIcon to be removed

See Also

add(TrayIcon), TrayIcon

removePropertyChangeListener back to summary

removePropertyChangeListener	back to summary
public synchronized void removePropertyChangeListener(String propertyName, PropertyChangeListener listener) Removes a `PropertyChangeListener` from the listener list for a specific property. If `propertyName` or `listener` is `null` or invalid, no exception is thrown and no action is taken. Parameters propertyName:String the specified property listener:PropertyChangeListener the PropertyChangeListener to be removed See Also `addPropertyChangeListener`, `getPropertyChangeListeners`

public synchronized void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)

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

If propertyName or listener is null or invalid, no exception is thrown and no action is taken.

Parameters

propertyName:String: the specified property
listener:PropertyChangeListener: the PropertyChangeListener to be removed

public Class SystemTray

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail