/*
 * 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();
 }
 }
 }
}