java.awt

接口
异常
错误
java.lang.Object
  继承者 java.awt.SystemTray

public class SystemTray
     
extends Object

SystemTray 类表示桌面的系统托盘。在 Microsoft Windows 上,它被称为“任务栏状态区域 (Taskbar Status Area)”,在 Gnome 上,它被称为“通知区域 (Notification Area)”,在 KDE 上,它被成为“系统托盘 (System Tray)”。系统托盘由运行在桌面上的所有应用程序共享。

在某些平台上,可能不存在或不支持系统托盘,在这种情况下,getSystemTray() 将抛出 UnsupportedOperationException。要检查系统托盘是否受支持,可以使用 isSupported()

SystemTray 可以包含一个或多个 TrayIcon,可以使用 add(java.awt.TrayIcon) 方法将它们添加到托盘,当不再需要托盘时,使用 remove(java.awt.TrayIcon) 移除它。TrayIcon 由图像、弹出菜单和一组相关侦听器组成。有关详细信息,请参阅 TrayIcon 类。

每个 Java 应用程序都有一个 SystemTray 实例,在应用程序运行时,它允许应用程序与桌面系统托盘建立连接。SystemTray 实例可以通过 getSystemTray() 方法获得。应用程序不能创建自己的 SystemTray 实例。

以下代码片段演示了如何访问和自定义系统托盘:


TrayIcon trayIcon = null;
if (SystemTray.isSupported()) {
// get the SystemTray instance
SystemTray tray = SystemTray.getSystemTray();
// load an image
Image image = Toolkit.getDefaultToolkit.getImage(...);
// create a action listener to listen for default action executed on the tray icon
ActionListener listener = new ActionListener() {
public void actionPerformed(ActionEvent e) {
// execute default action of the application
                 // ...
             }
         };
// create a popup menu
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);
     }
     // ...
 

从以下版本开始:
1.6
另请参见:
TrayIcon

方法摘要
 void add(TrayIcon trayIcon)
          将 TrayIcon 添加到 SystemTray
 void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)
          将 PropertyChangeListener 添加到特定属性的侦听器列表中。
 PropertyChangeListener[] getPropertyChangeListeners(String propertyName)
          返回与指定属性关联的所有侦听器的数组。
static SystemTray getSystemTray()
          获取表示桌面托盘区的 SystemTray 实例。
 TrayIcon[] getTrayIcons()
          返回由此应用程序添加到托盘中的所有图标的数组。
 Dimension getTrayIconSize()
          返回托盘图标在系统托盘中占用的空间大小(以像素为单位)。
static boolean isSupported()
          返回当前平台是否支持系统托盘。
 void remove(TrayIcon trayIcon)
          从 SystemTray 中移除指定的 TrayIcon
 void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)
          从特定属性的侦听器列表中移除 PropertyChangeListener
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

方法详细信息

getSystemTray

public static SystemTray getSystemTray()
获取表示桌面托盘区的 SystemTray 实例。它总是对每个应用程序返回相同的实例。在一些平台上,可能不支持系统托盘。可以使用 isSupported() 方法检查系统托盘是否受支持。

如果安装了 SecurityManager,则必须授予 AWTPermission accessSystemTray 才能获取 SystemTray 实例。否则,此方法将抛出 SecurityException。

返回:
表示桌面托盘区的 SystemTray 实例
抛出:
UnsupportedOperationException - 如果当前平台不支持系统托盘
HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true
SecurityException - 如果未授予 accessSystemTray 权限
另请参见:
add(TrayIcon), TrayIcon, isSupported(), SecurityManager.checkPermission(java.security.Permission), AWTPermission

isSupported

public static boolean isSupported()
返回当前平台是否支持系统托盘。除了显示托盘图标之外,最小系统托盘支持还包括弹出菜单(请参阅 TrayIcon.setPopupMenu(PopupMenu))或操作事件(请参阅 TrayIcon.addActionListener(ActionListener))。

开发人员不应假定所有系统托盘功能都是受支持的。要保证始终可以访问托盘图标的默认动作,则应将默认动作同时添加到动作侦听器和弹出菜单。有关如何执行此操作的示例,请参阅 example

:在实现 SystemTrayTrayIcon 时,强烈建议 为弹出菜单和动作事件分配不同的动作。为两种目的重载一个动作时会产生混淆,并可能阻止用户访问它们其中的一个或另一个。

返回:
如果不支持系统托盘访问,则返回 false;如果当前平台支持最小系统托盘访问,但不保证支持所有系统托盘功能,则此方法返回 true
另请参见:
getSystemTray()

add

public void add(TrayIcon trayIcon)
         throws AWTException
TrayIcon 添加到 SystemTray。一旦添加了托盘图标,就可以在系统托盘中看到它。图标在托盘中的显示顺序未指定——它与平台和实现有关。

在应用程序退出时,应用程序添加的所有图标都将自动从 SystemTray 移除,在桌面系统托盘不可用时也一样。

参数:
trayIcon - 要添加的 TrayIcon
抛出:
NullPointerException - 如果 trayIconnull
IllegalArgumentException - 如果多次添加 TrayIcon 的同一实例
AWTException - 如果桌面系统托盘不可用
另请参见:
remove(TrayIcon), getSystemTray(), TrayIcon, Image

remove

public void remove(TrayIcon trayIcon)
SystemTray 中移除指定的 TrayIcon

在应用程序退出时,应用程序添加的所有图标都将自动从 SystemTray 移除,在桌面系统托盘不可用时也一样。

如果 trayIconnull 或未添加到系统托盘,则不抛出任何异常且不执行任何动作。

参数:
trayIcon - 要移除的 TrayIcon
另请参见:
add(TrayIcon), TrayIcon

getTrayIcons

public TrayIcon[] getTrayIcons()
返回由此应用程序添加到托盘中的所有图标的数组。用户无法访问由另一个应用程序添加的图标。有些浏览器将使用不同代码基的 applet 划分为单独的上下文,并在这些上下文之间建墙分隔。在这种情形下,只返回从此上下文中添加的托盘图标。

返回的数组是实际数组的副本,可以以任意方式修改它,而不会影响系统托盘。要从 SystemTray 中移除 TrayIcon,可以使用 remove(TrayIcon) 方法。

返回:
添加到此托盘的所有托盘图标的数组;如果未添加托盘图标,则返回空数组
另请参见:
add(TrayIcon), TrayIcon

getTrayIconSize

public Dimension getTrayIconSize()
返回托盘图标在系统托盘中占用的空间大小(以像素为单位)。开发人员可以使用这种方法在创建托盘图标之前获取图像属性的首选大小。为方便起见,在 TrayIcon 类中有一个类似的方法 TrayIcon.getSize()

返回:
托盘图标的默认大小(以像素为单位)
另请参见:
TrayIcon.setImageAutoSize(boolean), Image, TrayIcon.getSize()

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      PropertyChangeListener listener)
PropertyChangeListener 添加到特定属性的侦听器列表中。当前支持的属性:
  • trayIcons

    SystemTrayTrayIcon 数组。通过 getTrayIcons() 可以访问该数组。
    在将 TrayIcon 添加到 SystemTray(或从中移除 TrayIcon)时,此属性将发生更改。
    例如,当本机 SystemTray 在桌面上不可用时,此属性将被更改
    且自动移除 TrayIcon

listener 仅在此上下文中侦听属性更改。

如果 listenernull,则不抛出任何异常且不执行任何动作。

参数:
propertyName - 指定的属性
listener - 要添加的属性更改侦听器
另请参见:
removePropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener), getPropertyChangeListeners(java.lang.String)

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener listener)
从特定属性的侦听器列表中移除 PropertyChangeListener

PropertyChangeListener 必须来自于此上下文。

如果 propertyNamelistenernull 或无效,则不抛出任何异常且不执行任何动作。

参数:
propertyName - 指定的属性
listener - 要移除的 PropertyChangeListener
另请参见:
addPropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener), getPropertyChangeListeners(java.lang.String)

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners(String propertyName)
返回与指定属性关联的所有侦听器的数组。

只返回此上下文中的侦听器。

参数:
propertyName - 指定的属性
返回:
与指定属性关联的所有 PropertyChangeListener;如果未添加此类侦听器或者 propertyNamenull 或无效,则返回空数组
另请参见:
addPropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener), removePropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)