/*
* Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*/
package java.awt;
import java.util.
Vector;
import java.awt.peer.
SystemTrayPeer;
import java.beans.
PropertyChangeListener;
import java.beans.
PropertyChangeSupport;
import sun.awt.
AppContext;
import sun.awt.
SunToolkit;
import sun.awt.
HeadlessToolkit;
import sun.security.util.
SecurityConstants;
import sun.awt.
AWTAccessor;
/**
* The <code>SystemTray</code> 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.
*
* <p> 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}.
*
* <p>The <code>SystemTray</code> 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}. <code>TrayIcon</code> consists of an
* image, a popup menu and a set of associated listeners. Please see
* the {@link TrayIcon} class for details.
*
* <p>Every Java application has a single <code>SystemTray</code>
* instance that allows the app to interface with the system tray of
* the desktop while the app is running. The <code>SystemTray</code>
* instance can be obtained from the {@link #getSystemTray} method.
* An application may not create its own instance of
* <code>SystemTray</code>.
*
* <p>The following code snippet demonstrates how to access
* and customize the system tray:
* <pre>
* <code>
* {@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);
* }
* // ...
* </code>
* </pre>
*
* @since 1.6
* @see TrayIcon
*
* @author Bino George
* @author Denis Mikhalkin
* @author Sharon Zakhour
* @author Anton Tarasov
*/
public class
SystemTray {
private static
SystemTray systemTray;
private int
currentIconID = 0; // each TrayIcon added gets a unique ID
transient private
SystemTrayPeer peer;
private static final
TrayIcon[]
EMPTY_TRAY_ARRAY = new
TrayIcon[0];
static {
AWTAccessor.
setSystemTrayAccessor(
new
AWTAccessor.
SystemTrayAccessor() {
public void
firePropertyChange(
SystemTray tray,
String propertyName,
Object oldValue,
Object newValue) {
tray.
firePropertyChange(
propertyName,
oldValue,
newValue);
}
});
}
/**
* Private <code>SystemTray</code> constructor.
*
*/
private
SystemTray() {
addNotify();
}
/**
* Gets the <code>SystemTray</code> 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.
*
* <p>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 <code>SystemTray</code> instance that represents
* the desktop's tray area
* @throws UnsupportedOperationException if the system tray isn't
* supported by the current platform
* @throws HeadlessException if
* <code>GraphicsEnvironment.isHeadless()</code> returns <code>true</code>
* @throws SecurityException if {@code accessSystemTray} permission
* is not granted
* @see #add(TrayIcon)
* @see TrayIcon
* @see #isSupported
* @see SecurityManager#checkPermission
* @see AWTPermission
*/
public static
SystemTray getSystemTray() {
checkSystemTrayAllowed();
if (
GraphicsEnvironment.
isHeadless()) {
throw new
HeadlessException();
}
initializeSystemTrayIfNeeded();
if (!
isSupported()) {
throw new
UnsupportedOperationException(
"The system tray is not supported on the current platform.");
}
return
systemTray;
}
/**
* 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)}).
*
* <p>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.
*
* <p><b>Note</b>: When implementing <code>SystemTray</code> and
* <code>TrayIcon</code> it is <em>strongly recommended</em> 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 <code>false</code> if no system tray access is supported; this
* method returns <code>true</code> if the minimal system tray access is
* supported but does not guarantee that all system tray
* functionality is supported for the current platform
*/
public static boolean
isSupported() {
Toolkit toolkit =
Toolkit.
getDefaultToolkit();
if (
toolkit instanceof
SunToolkit) {
// connecting tray to native resource
initializeSystemTrayIfNeeded();
return ((
SunToolkit)
toolkit).
isTraySupported();
} else if (
toolkit instanceof
HeadlessToolkit) {
// skip initialization as the init routine
// throws HeadlessException
return ((
HeadlessToolkit)
toolkit).
isTraySupported();
} else {
return false;
}
}
/**
* Adds a <code>TrayIcon</code> to the <code>SystemTray</code>.
* 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.
*
* <p> All icons added by the application are automatically
* removed from the <code>SystemTray</code> upon application exit
* and also when the desktop system tray becomes unavailable.
*
* @param trayIcon the <code>TrayIcon</code> to be added
* @throws NullPointerException if <code>trayIcon</code> is
* <code>null</code>
* @throws IllegalArgumentException if the same instance of
* a <code>TrayIcon</code> 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
*/
public void
add(
TrayIcon trayIcon) throws
AWTException {
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);
}
/**
* Removes the specified <code>TrayIcon</code> from the
* <code>SystemTray</code>.
*
* <p> All icons added by the application are automatically
* removed from the <code>SystemTray</code> upon application exit
* and also when the desktop system tray becomes unavailable.
*
* <p> If <code>trayIcon</code> is <code>null</code> or was not
* added to the system tray, no exception is thrown and no action
* is performed.
*
* @param trayIcon the <code>TrayIcon</code> to be removed
* @see #add(TrayIcon)
* @see TrayIcon
*/
public void
remove(
TrayIcon 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);
}
/**
* 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.
*
* <p> 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 <code>TrayIcon</code> from the
* <code>SystemTray</code>, 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
*/
public
TrayIcon[]
getTrayIcons() {
Vector<
TrayIcon>
icons = (
Vector<
TrayIcon>)
AppContext.
getAppContext().
get(
TrayIcon.class);
if (
icons != null) {
return (
TrayIcon[])
icons.
toArray(new
TrayIcon[
icons.
size()]);
}
return
EMPTY_TRAY_ARRAY;
}
/**
* 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 <code>TrayIcon</code> class.
*
* @return the default size of a tray icon, in pixels
* @see TrayIcon#setImageAutoSize(boolean)
* @see java.awt.Image
* @see TrayIcon#getSize()
*/
public
Dimension getTrayIconSize() {
return
peer.
getTrayIconSize();
}
/**
* Adds a {@code PropertyChangeListener} to the list of listeners for the
* specific property. The following properties are currently supported:
*
* <table border=1 summary="SystemTray properties">
* <tr>
* <th>Property</th>
* <th>Description</th>
* </tr>
* <tr>
* <td>{@code trayIcons}</td>
* <td>The {@code SystemTray}'s array of {@code TrayIcon} objects.
* The array is accessed via the {@link #getTrayIcons} method.<br>
* This property is changed when a tray icon is added to (or removed
* from) the system tray.<br> For example, this property is changed
* when the system tray becomes unavailable on the desktop<br>
* and the tray icons are automatically removed.</td>
* </tr>
* <tr>
* <td>{@code systemTray}</td>
* <td>This property contains {@code SystemTray} instance when the system tray
* is available or <code>null</code> otherwise.<br> This property is changed
* when the system tray becomes available or unavailable on the desktop.<br>
* The property is accessed by the {@link #getSystemTray} method.</td>
* </tr>
* </table>
* <p>
* The {@code listener} listens to property changes only in this context.
* <p>
* 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
*/
public synchronized void
addPropertyChangeListener(
String propertyName,
PropertyChangeListener listener)
{
if (
listener == null) {
return;
}
getCurrentChangeSupport().
addPropertyChangeListener(
propertyName,
listener);
}
/**
* Removes a {@code PropertyChangeListener} from the listener list
* for a specific property.
* <p>
* The {@code PropertyChangeListener} must be from this context.
* <p>
* 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
*/
public synchronized void
removePropertyChangeListener(
String propertyName,
PropertyChangeListener listener)
{
if (
listener == null) {
return;
}
getCurrentChangeSupport().
removePropertyChangeListener(
propertyName,
listener);
}
/**
* Returns an array of all the listeners that have been associated
* with the named property.
* <p>
* 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
*/
public synchronized
PropertyChangeListener[]
getPropertyChangeListeners(
String propertyName) {
return
getCurrentChangeSupport().
getPropertyChangeListeners(
propertyName);
}
// ***************************************************************
// ***************************************************************
/**
* 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
*/
private void
firePropertyChange(
String propertyName,
Object oldValue,
Object newValue)
{
if (
oldValue != null &&
newValue != null &&
oldValue.
equals(
newValue)) {
return;
}
getCurrentChangeSupport().
firePropertyChange(
propertyName,
oldValue,
newValue);
}
/**
* Returns the current PropertyChangeSupport instance for the
* calling thread's context.
*
* @return this thread's context's PropertyChangeSupport
*/
private synchronized
PropertyChangeSupport getCurrentChangeSupport() {
PropertyChangeSupport changeSupport =
(
PropertyChangeSupport)
AppContext.
getAppContext().
get(
SystemTray.class);
if (
changeSupport == null) {
changeSupport = new
PropertyChangeSupport(this);
AppContext.
getAppContext().
put(
SystemTray.class,
changeSupport);
}
return
changeSupport;
}
synchronized void
addNotify() {
if (
peer == null) {
Toolkit toolkit =
Toolkit.
getDefaultToolkit();
if (
toolkit instanceof
SunToolkit) {
peer = ((
SunToolkit)
Toolkit.
getDefaultToolkit()).
createSystemTray(this);
} else if (
toolkit instanceof
HeadlessToolkit) {
peer = ((
HeadlessToolkit)
Toolkit.
getDefaultToolkit()).
createSystemTray(this);
}
}
}
static void
checkSystemTrayAllowed() {
SecurityManager security =
System.
getSecurityManager();
if (
security != null) {
security.
checkPermission(
SecurityConstants.
AWT.
ACCESS_SYSTEM_TRAY_PERMISSION);
}
}
private static void
initializeSystemTrayIfNeeded() {
synchronized (
SystemTray.class) {
if (
systemTray == null) {
systemTray = new
SystemTray();
}
}
}
}