java.awt
类 TrayIcon

java.lang.Object
  java.awt.TrayIcon

public class TrayIcon
extends Object

TrayIcon 对象表示可以添加到系统托盘的托盘图标。TrayIcon 可以包含工具提示（文本）、图像、弹出菜单和一组与之关联的侦听器。

TrayIcon 可以生成各种 MouseEvent，并支持添加相应的侦听器，以接收这些事件的通知。TrayIcon 可以自己处理一些事件。例如，默认情况下，在 TrayIcon 上单击鼠标右键时，它将显示指定的弹出菜单。当鼠标悬停到 TrayIcon 上时，它将显示工具提示。

注：在将 MouseEvent 指派给它的注册侦听器时，其 component 属性将被设置为 null。（请参阅 ComponentEvent.getComponent()）；source 属性将被设置为此 TrayIcon（请参阅 EventObject.getSource()）。

注： 行为良好的 TrayIcon 实现将分配不同的动作来显示弹出菜单并选择托盘图标。

TrayIcon 可以生成一个 ActionEvent。在某些平台上，当用户使用鼠标或键盘选择托盘图标时，会出现这种情况。

如果已经安装了 SecurityManager，则必须授予 AWTPermission accessSystemTray 才能创建 TrayIcon。否则，构造方法将抛出 SecurityException。

有关如何使用 TrayIcon API 的示例，请参阅 SystemTray 类概述。

从以下版本开始：

1.6

另请参见：

SystemTray.add(java.awt.TrayIcon), ComponentEvent.getComponent(), EventObject.getSource()

嵌套类摘要

static class

TrayIcon.MessageType MessageType 确定哪个图标将显示在消息标题中，以及消息根据显示生成的可能的系统声音。

构造方法摘要

TrayIcon(Image image)
创建带有指定图像的 TrayIcon。

TrayIcon(Image image, String tooltip)
创建带有指定图像和工具提示文本的 TrayIcon。

TrayIcon(Image image, String tooltip, PopupMenu popup)
创建带指定图像、工具提示和弹出菜单的 TrayIcon。

方法摘要

void	addActionListener(ActionListener listener) 添加指定的动作侦听器，以接收发自此 TrayIcon 的 ActionEvent。
void	addMouseListener(MouseListener listener) 添加指定的鼠标侦听器，以接收发自此 TrayIcon 的鼠标事件。
void	addMouseMotionListener(MouseMotionListener listener) 添加指定的鼠标侦听器，以接收发自此 TrayIcon 的鼠标移动事件。
void	displayMessage(String caption, String text, TrayIcon.MessageType messageType) 在托盘图标附近显示弹出消息。
String	getActionCommand() 返回由此托盘图标触发的动作事件的命令名。
ActionListener[]	getActionListeners() 返回在已此 TrayIcon 上注册的所有动作侦听器的数组。
Image	getImage() 返回用于此 TrayIcon 的当前图像。
MouseListener[]	getMouseListeners() 返回已在此 TrayIcon 上注册的所有鼠标侦听器的数组。
MouseMotionListener[]	getMouseMotionListeners() 返回已在此 TrayIcon 上注册的所有鼠标移动侦听器的数组。
PopupMenu	getPopupMenu() 返回与此 TrayIcon 关联的弹出菜单。
Dimension	getSize() 返回托盘图标在系统托盘上占用的空间大小（以像素为单位）。
String	getToolTip() 返回与此 TrayIcon 关联的工具提示字符串。
boolean	isImageAutoSize() 返回自动调整大小属性的值。
void	removeActionListener(ActionListener listener) 移除指定的动作侦听器。
void	removeMouseListener(MouseListener listener) 移除指定的鼠标侦听器。
void	removeMouseMotionListener(MouseMotionListener listener) 移除指定的鼠标移动侦听器。
void	setActionCommand(String command) 设置由此托盘图标触发的动作事件的命令名。
void	setImage(Image image) 设置此 TrayIcon 的图像。
void	setImageAutoSize(boolean autosize) 设置自动调整大小的属性。
void	setPopupMenu(PopupMenu popup) 设置此 TrayIcon 的弹出菜单。
void	setToolTip(String tooltip) 设置此 TrayIcon 的工具提示字符串。

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

TrayIcon

public TrayIcon(Image image)

创建带有指定图像的 TrayIcon。

参数：

image - 要使用的 Image

抛出：

IllegalArgumentException - 如果 image 为 null

UnsupportedOperationException - 如果当前平台不支持系统托盘

HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true

SecurityException - 如果未授予 accessSystemTray 权限

另请参见：

SystemTray.add(TrayIcon), TrayIcon(Image, String, PopupMenu), TrayIcon(Image, String), SecurityManager.checkPermission(java.security.Permission), AWTPermission

TrayIcon

public TrayIcon(Image image,
                String tooltip)

创建带有指定图像和工具提示文本的 TrayIcon。

参数：

image - 要使用的 Image

tooltip - 将用作工具提示文本的字符串；如果值为 null，则不显示工具提示

抛出：

IllegalArgumentException - 如果 image 为 null

UnsupportedOperationException - 如果当前平台不支持系统托盘

HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true

SecurityException - 如果未授予 accessSystemTray 权限

另请参见：

SystemTray.add(TrayIcon), TrayIcon(Image), TrayIcon(Image, String, PopupMenu), SecurityManager.checkPermission(java.security.Permission), AWTPermission

TrayIcon

public TrayIcon(Image image,
                String tooltip,
                PopupMenu popup)

创建带指定图像、工具提示和弹出菜单的 TrayIcon。

参数：

image - 要使用的 Image

tooltip - 将用作工具提示文本的字符串；如果值为 null ，则不显示工具提示

popup - 将用于托盘图标的弹出菜单的菜单；如果值为 null，则不显示弹出菜单

抛出：

IllegalArgumentException - 如果 image 为 null

UnsupportedOperationException - 如果当前平台不支持系统托盘

HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true

SecurityException - 如果未授予 accessSystemTray 权限

另请参见：

SystemTray.add(TrayIcon), TrayIcon(Image, String), TrayIcon(Image), PopupMenu, MouseListener, addMouseListener(MouseListener), SecurityManager.checkPermission(java.security.Permission), AWTPermission

方法详细信息

setImage

public void setImage(Image image)

设置此 TrayIcon 的图像。若想在不调用 Image.flush() 方法的情况下舍弃以前的托盘图标图像，则需要手动调用它。

如果该图像表示一幅动画图像，则将自动显示动画。

有关显示图像大小的详细信息，请参阅 setImageAutoSize(boolean) 属性。

用与当前正在使用的图像相同的图像调用此方法无效。

参数：

image - 要使用的非 null Image

抛出：

NullPointerException - 如果 image 为 null

另请参见：

getImage(), Image, SystemTray.add(TrayIcon), TrayIcon(Image, String)

getImage

public Image getImage()

返回用于此 TrayIcon 的当前图像。

返回：

图像

另请参见：

setImage(Image), Image

setPopupMenu

public void setPopupMenu(PopupMenu popup)

设置此 TrayIcon 的弹出菜单。如果 popup 为 null，则没有任何弹出菜单与此 TrayIcon 关联。

注意，在托盘图标上设置此 popup 之前或之后，都不得将它添加到任何父级弹出菜单。如果将它添加到某个父级弹出菜单，则可能从该父级弹出菜单中移除 popup。

popup 只能设置在一个 TrayIcon 上。在多个 TrayIcon 上设置同一个 popup 将导致 IllegalArgumentException。

注： 一些平台可能不支持在用户右键单击托盘图标时显示用户指定的弹出菜单组件。在这种情况下，可能不显示任何菜单，在某些系统中，也可能显示菜单的本地版本。

参数：

popup - 一个 PopupMenu，如果该参数为 null，则移除所有弹出菜单

抛出：

IllegalArgumentException - 如果已经为另一个 TrayIcon 设置 popup

另请参见：

getPopupMenu()

getPopupMenu

public PopupMenu getPopupMenu()

返回与此 TrayIcon 关联的弹出菜单。

返回：

弹出菜单；如果不存在弹出菜单，则返回 null

另请参见：

setPopupMenu(PopupMenu)

setToolTip

public void setToolTip(String tooltip)

设置此 TrayIcon 的工具提示字符串。当鼠标悬停在图标上时，自动显示工具提示。将工具提示设置为 null 将移除所有工具提示文本。 在某些平台上显示时，工具提示字符串可能被截断；可以显示的字符数与平台有关。

参数：

tooltip - 工具提示的字符串；如果值为 null，则不显示任何工具提示

另请参见：

getToolTip()

getToolTip

public String getToolTip()

返回与此 TrayIcon 关联的工具提示字符串。

返回：

工具提示字符串；如果不存在，则返回 null

另请参见：

setToolTip(String)

setImageAutoSize

public void setImageAutoSize(boolean autosize)

设置自动调整大小的属性。自动调整大小属性将确定托盘图像是否能自动调整大小以适合托盘上为图像分配的空间。默认情况下，自动调整大小属性被设置为 false。

如果自动调整大小属性为 false，且图像大小与托盘图标空间不匹配，则图像将按照原样绘制在该空间中，如果图像大小大于分配的空间，那么它将被裁剪。

如果自动调整大小属性为 true，则将拉伸或缩小图像以适合托盘图标空间。

参数：

autosize - 如果自动调整图像大小，则为 true；否则为 false

另请参见：

isImageAutoSize()

isImageAutoSize

public boolean isImageAutoSize()

返回自动调整大小属性的值。

返回：

如果自动调整图像大小，则返回 true；否则返回 false

另请参见：

setImageAutoSize(boolean)

addMouseListener

public void addMouseListener(MouseListener listener)

添加指定的鼠标侦听器，以接收发自此 TrayIcon 的鼠标事件。用 null 值调用此方法无效。

注：MouseEvent 的坐标（从 TrayIcon 接收）是相对于屏幕的，而不是相对于 TrayIcon 的。

注： 不支持 MOUSE_ENTERED 和 MOUSE_EXITED 鼠标事件。

有关 AWT 线程模型的详细信息，请参阅 AWT 线程问题。

参数：

listener - 鼠标侦听器

另请参见：

MouseEvent, MouseListener, removeMouseListener(MouseListener), getMouseListeners()

removeMouseListener

public void removeMouseListener(MouseListener listener)

移除指定的鼠标侦听器。用 null 或无效值调用此方法无效。

有关 AWT 线程模型的详细信息，请参阅 AWT 线程问题。

参数：

listener - 鼠标侦听器

另请参见：

MouseEvent, MouseListener, addMouseListener(MouseListener), getMouseListeners()

getMouseListeners

public MouseListener[] getMouseListeners()

返回已在此 TrayIcon 上注册的所有鼠标侦听器的数组。

返回：

所有已在此 TrayIcon 上注册的 MouseListeners；如果当前没有已注册的鼠标侦听器，则返回空数组

另请参见：

addMouseListener(MouseListener), removeMouseListener(MouseListener), MouseListener

addMouseMotionListener

public void addMouseMotionListener(MouseMotionListener listener)

添加指定的鼠标侦听器，以接收发自此 TrayIcon 的鼠标移动事件。用 null 值调用此方法无效。

注：MouseEvent 的坐标（从 TrayIcon 接收）是相对于屏幕的，而不是相对于 TrayIcon 的。

注： 不支持 MOUSE_DRAGGED 鼠标事件。

有关 AWT 线程模型的详细信息，请参阅 AWT 线程问题。

参数：

listener - 鼠标侦听器

另请参见：

MouseEvent, MouseMotionListener, removeMouseMotionListener(MouseMotionListener), getMouseMotionListeners()

removeMouseMotionListener

public void removeMouseMotionListener(MouseMotionListener listener)

移除指定的鼠标移动侦听器。用 null 或无效值调用此方法无效。

有关 AWT 线程模型的详细信息，请参阅 AWT 线程问题。

参数：

listener - 鼠标侦听器

另请参见：

MouseEvent, MouseMotionListener, addMouseMotionListener(MouseMotionListener), getMouseMotionListeners()

getMouseMotionListeners

public MouseMotionListener[] getMouseMotionListeners()

返回已在此 TrayIcon 上注册的所有鼠标移动侦听器的数组。

返回：

所有已在此 TrayIcon 上注册的 MouseInputListeners；如果当前没有注册的鼠标侦听器，则返回空数组

另请参见：

addMouseMotionListener(MouseMotionListener), removeMouseMotionListener(MouseMotionListener), MouseMotionListener

getActionCommand

public String getActionCommand()

返回由此托盘图标触发的动作事件的命令名。

返回：

动作命令名；如果不存在，则返回 null

另请参见：

addActionListener(ActionListener), setActionCommand(String)

setActionCommand

public void setActionCommand(String command)

设置由此托盘图标触发的动作事件的命令名。默认情况下，此动作命令被设置为 null。

参数：

command - 用于设置托盘图标动作命令的字符串。

另请参见：

ActionEvent, addActionListener(ActionListener), getActionCommand()

addActionListener

public void addActionListener(ActionListener listener)

添加指定的动作侦听器，以接收发自此 TrayIcon 的 ActionEvent。当用户使用鼠标或键盘选择托盘图标时，通常会发生动作事件。动作事件生成的条件与平台有关。

用 null 值调用此方法无效。

有关 AWT 线程模型的详细信息，请参阅 AWT 线程问题。

参数：

listener - 动作侦听器

另请参见：

removeActionListener(java.awt.event.ActionListener), getActionListeners(), ActionListener, setActionCommand(String)

removeActionListener

public void removeActionListener(ActionListener listener)

移除指定的动作侦听器。用 null 或无效值调用此方法无效。

有关 AWT 线程模型的详细信息，请参阅 AWT 线程问题。

参数：

listener - 动作侦听器

另请参见：

ActionEvent, ActionListener, addActionListener(ActionListener), getActionListeners(), setActionCommand(String)

getActionListeners

public ActionListener[] getActionListeners()

返回在已此 TrayIcon 上注册的所有动作侦听器的数组。

返回：

所有已在此 TrayIcon 上注册的 ActionListeners；如果当前没有注册的动作侦听器，则返回空数组

另请参见：

addActionListener(ActionListener), removeActionListener(ActionListener), ActionListener

displayMessage

public void displayMessage(String caption,
                           String text,
                           TrayIcon.MessageType messageType)

在托盘图标附近显示弹出消息。消息将在一段时间之后或用户在消息上单击时消失。单击消息可能触发 ActionEvent。

标题或文本可以为 null，但如果两者都为 null，则抛出 NullPointerException。 在某些平台上显示时，标题或文本字符串可能被截取；可以显示的字符数与平台有关。

注： 一些平台可能不支持显示消息。

参数：

caption - 显示在文本上面的标题，通常为粗体；可以为 null

text - 显示特定消息的文本；可以为 null

messageType - 指示消息类型的枚举

抛出：

NullPointerException - 如果 caption 和 text 都为 null

getSize

public Dimension getSize()

返回托盘图标在系统托盘上占用的空间大小（以像素为单位）。对于尚未添加到系统托盘上的托盘图标，返回的大小等于 SystemTray.getTrayIconSize() 的结果。

返回：

托盘图标的大小（以像素为单位）

另请参见：

setImageAutoSize(boolean), Image, getSize()