This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.


java.awt
class SystemTray

java.lang.Object extended by java.awt.SystemTray

Most common way to construct:

SystemTray tray = SystemTray.getSystemTray();

Based on 148 examples


public class SystemTray
extends Object

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 {@link SystemTray#getSystemTray()} throws {@link UnsupportedOperationException}. To detect whether the system tray is supported, use {@link SystemTray#isSupported}.

The SystemTray may contain one or more {@link TrayIcon TrayIcons}, which are added to the tray using the {@link #add} method, and removed when no longer needed, using the {@link #remove}. TrayIcon consists of an image, a popup menu and a set of associated listeners. Please see the {@link 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 {@link #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:

     {@link TrayIcon} trayIcon = null;
     if (SystemTray.isSupported()) {
         // get the SystemTray instance
         SystemTray tray = SystemTray.{@link #getSystemTray};
         // load an image
         {@link java.awt.Image} image = {@link java.awt.Toolkit#getImage(String) Toolkit.getDefaultToolkit.getImage}(...);
         // create a action listener to listen for default action executed on the tray icon
         {@link java.awt.event.ActionListener} listener = new {@link java.awt.event.ActionListener ActionListener}() {
             public void {@link java.awt.event.ActionListener#actionPerformed actionPerformed}({@link java.awt.event.ActionEvent} e) {
                 // execute default action of the application
                 // ...
             }
         };
         // create a popup menu
         {@link java.awt.PopupMenu} popup = new {@link java.awt.PopupMenu#PopupMenu 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 {@link TrayIcon#TrayIcon(java.awt.Image, String, java.awt.PopupMenu) TrayIcon}(image, "Tray Demo", popup);
         // set the TrayIcon properties
         trayIcon.{@link TrayIcon#addActionListener(java.awt.event.ActionListener) addActionListener}(listener);
         // ...
         // add the tray image
         try {
             tray.{@link SystemTray#add(TrayIcon) 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.{@link TrayIcon#setImage(java.awt.Image) setImage}(updatedImage);
     }
     // ...
 


Method Summary
 void
add(TrayIcon trayIcon)

          Adds a TrayIcon to the SystemTray.
 void

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

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

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

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

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

          Returns whether the system tray is supported on the current platform.
 void
remove(TrayIcon trayIcon)

          Removes the specified TrayIcon from the SystemTray.
 void

          Removes a from the listener list for a specific property.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

add

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 - the TrayIcon to be added
Throws:
AWTException - if the desktop system tray is missing

addPropertyChangeListener

public synchronized void addPropertyChangeListener(String propertyName,
                                                   PropertyChangeListener listener)
Adds a {@code PropertyChangeListener} to the listener list for a specific property. Currently supported property:

The {@code listener} listens to property changes only in this context.

If {@code listener} is {@code null}, no exception is thrown and no action is performed.

Parameters:
propertyName - the specified property
listener - the property change listener to be added

getPropertyChangeListeners

public synchronized PropertyChangeListener[] getPropertyChangeListeners(String propertyName)
Returns an array of all the listeners that have been associated with the named property.

Only the listeners in this context are returned.

Parameters:
propertyName - the specified property
Returns:
all of the {@code PropertyChangeListener}s associated with the named property; if no such listeners have been added or if {@code propertyName} is {@code null} or invalid, an empty array is returned

getSystemTray

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 {@link #isSupported} method to check if the system tray is supported.

If a SecurityManager is installed, the AWTPermission {@code accessSystemTray} must be granted in order to get the {@code SystemTray} instance. Otherwise this method will throw a SecurityException.

Returns:
the SystemTray instance that represents the desktop's tray area

getTrayIcons

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. Some browsers partition applets in different code bases into separate contexts, and establish walls between these contexts. In such a scenario, only the tray icons added from this context will be returned.

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 {@link #remove(TrayIcon)} method.

Returns:
an array of all tray icons added to this tray, or an empty array if none has been added

getTrayIconSize

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 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 {@link TrayIcon#getSize} in the TrayIcon class.

Returns:
the default size of a tray icon, in pixels

isSupported

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 {@link TrayIcon#setPopupMenu(PopupMenu)}) or an action event (see {@link 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 {@link SystemTray 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:
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

remove

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

removePropertyChangeListener

public synchronized void removePropertyChangeListener(String propertyName,
                                                      PropertyChangeListener listener)
Removes a {@code PropertyChangeListener} from the listener list for a specific property.

The {@code PropertyChangeListener} must be from this context.

If {@code propertyName} or {@code listener} is {@code null} or invalid, no exception is thrown and no action is taken.

Parameters:
propertyName - the specified property
listener - the PropertyChangeListener to be removed


This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.
This page displays the Jadeite version of the documention, which is derived from the offical documentation that contains this copyright notice:
Copyright 2008 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.
The official Sun™ documentation can be found here at http://java.sun.com/javase/6/docs/api/.