File	Doc	Category	Size	Date	Package
SystemTray.java	API Doc	Java SE 6 API	18007	Tue Jun 10 00:25:18 BST 2008	java.awt

SystemTray

• java.lang.Object

{@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);
}
// ...

Fields Summary
private static SystemTray	systemTray
private int	currentIconID
private transient SystemTrayPeer	peer

Constructors Summary
private SystemTray() Private SystemTray constructor. addNotify();

Methods Summary
public void	add(java.awt.TrayIcon trayIcon) 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. param trayIcon the TrayIcon to be added throws NullPointerException if trayIcon is null throws IllegalArgumentException if the same instance of a TrayIcon is added more than once throws AWTException if the desktop system tray is missing see #remove(TrayIcon) see #getSystemTray see TrayIcon see java.awt.Image if (trayIcon == null) { throw new NullPointerException("adding null TrayIcon"); } TrayIcon[] oldArray = null, newArray = null; Vector<TrayIcon> icons = null; synchronized (this) { oldArray = systemTray.getTrayIcons(); icons = (Vector<TrayIcon>)AppContext.getAppContext().get(TrayIcon.class); if (icons == null) { icons = new Vector<TrayIcon>(3); AppContext.getAppContext().put(TrayIcon.class, icons); } else if (icons.contains(trayIcon)) { throw new IllegalArgumentException("adding TrayIcon that is already added"); } icons.add(trayIcon); newArray = systemTray.getTrayIcons(); trayIcon.setID(++currentIconID); } try { trayIcon.addNotify(); } catch (AWTException e) { icons.remove(trayIcon); throw e; } firePropertyChange("trayIcons", oldArray, newArray);
synchronized void	addNotify() if (peer == null) { peer = ((SunToolkit)Toolkit.getDefaultToolkit()).createSystemTray(this); }
public synchronized void	addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Adds a {@code PropertyChangeListener} to the listener list for a specific property. Currently supported property: {@code trayIcons} This {@code SystemTray}'s array of {@code TrayIcon}s. The array is accessed via {@link SystemTray#getTrayIcons}. This property is changed when a {@code TrayIcon} is added to (or removed from) the {@code SystemTray}. For example, this property is changed when the native {@code SystemTray} becomes unavailable on the desktop and the {@code TrayIcon}s are automatically removed. 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. param propertyName the specified property param listener the property change listener to be added see #removePropertyChangeListener see #getPropertyChangeListeners if (listener == null) { return; } getCurrentChangeSupport().addPropertyChangeListener(propertyName, listener);
static void	checkSystemTrayAllowed() SecurityManager security = System.getSecurityManager(); if (security != null) { security.checkPermission(SecurityConstants.ACCESS_SYSTEM_TRAY_PERMISSION); }
private void	firePropertyChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.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. param propertyName the property whose value has changed param oldValue the property's previous value param newValue the property's new value if (oldValue != null && newValue != null && oldValue.equals(newValue)) { return; } getCurrentChangeSupport().firePropertyChange(propertyName, oldValue, newValue);
private synchronized java.beans.PropertyChangeSupport	getCurrentChangeSupport() Returns the current PropertyChangeSupport instance for the calling thread's context. return this thread's context's PropertyChangeSupport PropertyChangeSupport changeSupport = (PropertyChangeSupport)AppContext.getAppContext().get(SystemTray.class); if (changeSupport == null) { changeSupport = new PropertyChangeSupport(this); AppContext.getAppContext().put(SystemTray.class, changeSupport); } return changeSupport;
public synchronized java.beans.PropertyChangeListener[]	getPropertyChangeListeners(java.lang.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. param propertyName the specified property return 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 see #addPropertyChangeListener see #removePropertyChangeListener return getCurrentChangeSupport().getPropertyChangeListeners(propertyName);
public static java.awt.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. return the SystemTray instance that represents the desktop's tray area throws UnsupportedOperationException if the system tray isn't supported by the current platform throws HeadlessException if GraphicsEnvironment.isHeadless() returns true throws SecurityException if {@code accessSystemTray} permission is not granted see #add(TrayIcon) see TrayIcon see #isSupported see SecurityManager#checkPermission see AWTPermission checkSystemTrayAllowed(); if (GraphicsEnvironment.isHeadless()) { throw new HeadlessException(); } if (!isSupported()) { throw new UnsupportedOperationException( "The system tray is not supported on the current platform."); } synchronized (SystemTray.class) { if (systemTray == null) { systemTray = new SystemTray(); } } return systemTray;
public java.awt.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. return the default size of a tray icon, in pixels see TrayIcon#setImageAutoSize(boolean) see java.awt.Image see TrayIcon#getSize() return peer.getTrayIconSize();
public java.awt.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. return an array of all tray icons added to this tray, or an empty array if none has been added see #add(TrayIcon) see TrayIcon Vector<TrayIcon> icons = (Vector<TrayIcon>)AppContext.getAppContext().get(TrayIcon.class); if (icons != null) { return (TrayIcon[])icons.toArray(new TrayIcon[icons.size()]); } return new TrayIcon[0];
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. see #getSystemTray return 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 if (Toolkit.getDefaultToolkit() instanceof SunToolkit) { return ((SunToolkit)Toolkit.getDefaultToolkit()).isTraySupported(); } else if (Toolkit.getDefaultToolkit() instanceof HeadlessToolkit) { return ((HeadlessToolkit)Toolkit.getDefaultToolkit()).isTraySupported(); } return false;
public void	remove(java.awt.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. param trayIcon the TrayIcon to be removed see #add(TrayIcon) see TrayIcon if (trayIcon == null) { return; } TrayIcon[] oldArray = null, newArray = null; synchronized (this) { oldArray = systemTray.getTrayIcons(); Vector<TrayIcon> icons = (Vector<TrayIcon>)AppContext.getAppContext().get(TrayIcon.class); // TrayIcon with no peer is not contained in the array. if (icons == null || !icons.remove(trayIcon)) { return; } trayIcon.removeNotify(); newArray = systemTray.getTrayIcons(); } firePropertyChange("trayIcons", oldArray, newArray);
public synchronized void	removePropertyChangeListener(java.lang.String propertyName, java.beans.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. param propertyName the specified property param listener the PropertyChangeListener to be removed see #addPropertyChangeListener see #getPropertyChangeListeners if (listener == null) { return; } getCurrentChangeSupport().removePropertyChangeListener(propertyName, listener);