Top Description Inners Fields Constructors Methods
java.awt

public Class TrayIcon

extends Object
Class Inheritance
Imports
java.awt.event.*, java.awt.peer.TrayIconPeer, sun.awt.AppContext, .SunToolkit, .AWTAccessor, .HeadlessToolkit, java.util.EventObject, java.security.AccessControlContext, .AccessController
A TrayIcon object represents a tray icon that can be added to the system tray. A TrayIcon can have a tooltip (text), an image, a popup menu, and a set of listeners associated with it.

A TrayIcon can generate various MouseEvents and supports adding corresponding listeners to receive notification of these events. TrayIcon processes some of the events by itself. For example, by default, when the right-mouse click is performed on the TrayIcon it displays the specified popup menu. When the mouse hovers over the TrayIcon the tooltip is displayed (this behaviour is platform dependent).

Note

When the MouseEvent is dispatched to its registered listeners its component property will be set to null. (See java.awt.event.ComponentEvent#getComponent) The source property will be set to this TrayIcon. (See java.util.EventObject#getSource)

Note

A well-behaved TrayIcon implementation will assign different gestures to showing a popup menu and selecting a tray icon.

A TrayIcon can generate an ActionEvent. On some platforms, this occurs when the user selects the tray icon using either the mouse or keyboard.

If a SecurityManager is installed, the AWTPermission accessSystemTray must be granted in order to create a TrayIcon. Otherwise the constructor will throw a SecurityException.

See the SystemTray class overview for an example on how to use the TrayIcon API.

Implementation Note

When the apple.awt.enableTemplateImages property is set, all images associated with instances of this class are treated as template images by the native desktop system. This means all color information is discarded, and the image is adapted automatically to be visible when desktop theme and/or colors change. This property only affects MacOSX.

Authors
Bino George, Denis Mikhalkin, Sharon Zakhour, Anton Tarasov
Since
1.6
See Also
SystemTray#add, java.awt.event.ComponentEvent#getComponent, java.util.EventObject#getSource

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
TrayIcon.MessageType

The message type determines which icon will be displayed in the caption of the message, and a possible system sound a message may generate upon showing.

Field Summary

Modifier and TypeField and Description
private final AccessControlContext
acc

Deprecated as a consequence of AccessControlContext being deprecated.
private String
actionCommand

pack-priv transient ActionListener
actionListener

private boolean
autosize

private int
id

private Image
image

pack-priv transient MouseListener
mouseListener

pack-priv transient MouseMotionListener
mouseMotionListener

private transient TrayIconPeer
peer

private PopupMenu
popup

private String
tooltip

Constructor Summary

AccessConstructor and Description
private
TrayIcon()

public
TrayIcon(Image
the Image to be used
image)

Creates a TrayIcon with the specified image.

public
TrayIcon(Image
the Image to be used
image, String
the string to be used as tooltip text; if the value is null no tooltip is shown
tooltip)

Creates a TrayIcon with the specified image and tooltip text.

public
TrayIcon(Image
the Image to be used
image, String
the string to be used as tooltip text; if the value is null no tooltip is shown
tooltip, PopupMenu
the menu to be used for the tray icon's popup menu; if the value is null no popup menu is shown
popup)

Creates a TrayIcon with the specified image, tooltip and popup menu.

Method Summary

Modifier and TypeMethod and Description
public synchronized void
addActionListener(ActionListener
the action listener
listener)

Adds the specified action listener to receive ActionEvents from this TrayIcon.

public synchronized void
addMouseListener(MouseListener
the mouse listener
listener)

Adds the specified mouse listener to receive mouse events from this TrayIcon.

public synchronized void
addMouseMotionListener(MouseMotionListener
the mouse listener
listener)

Adds the specified mouse listener to receive mouse-motion events from this TrayIcon.

pack-priv void
addNotify()

pack-priv void
dispatchEvent(AWTEvent e)

public void
displayMessage(String
the caption displayed above the text, usually in bold; may be null
caption, String
the text displayed for the particular message; may be null
text, TrayIcon.MessageType
an enum indicating the message type
messageType)

Displays a popup message near the tray icon.

pack-priv final AccessControlContext
getAccessControlContext()

Deprecated as a consequence of AccessControlContext being deprecated.
public String

Returns:

the action command name, or null if none exists
getActionCommand()

Returns the command name of the action event fired by this tray icon.

public synchronized ActionListener[]

Returns:

all of the ActionListeners registered on this TrayIcon or an empty array if no action listeners are currently registered
getActionListeners()

Returns an array of all the action listeners registered on this TrayIcon.

pack-priv int
getID()

public Image

Returns:

the image
getImage()

Returns the current image used for this TrayIcon.

public synchronized MouseListener[]

Returns:

all of the MouseListeners registered on this TrayIcon or an empty array if no mouse listeners are currently registered
getMouseListeners()

Returns an array of all the mouse listeners registered on this TrayIcon.

public synchronized MouseMotionListener[]

Returns:

all of the MouseInputListeners registered on this TrayIcon or an empty array if no mouse listeners are currently registered
getMouseMotionListeners()

Returns an array of all the mouse-motion listeners registered on this TrayIcon.

public PopupMenu

Returns:

the popup menu or null if none exists
getPopupMenu()

Returns the popup menu associated with this TrayIcon.

public Dimension

Returns:

the size of the tray icon, in pixels
getSize()

Returns the size, in pixels, of the space that the tray icon occupies in the system tray.

public String

Returns:

the tooltip string or null if none exists
getToolTip()

Returns the tooltip string associated with this TrayIcon.

private static native void
initIDs()

public boolean

Returns:

true if the image will be auto-sized, false otherwise
isImageAutoSize()

Returns the value of the auto-size property.

pack-priv void
processActionEvent(ActionEvent e)

pack-priv void
processEvent(AWTEvent e)

pack-priv void
processMouseEvent(MouseEvent e)

pack-priv void
processMouseMotionEvent(MouseEvent e)

public synchronized void
removeActionListener(ActionListener
the action listener
listener)

Removes the specified action listener.

public synchronized void
removeMouseListener(MouseListener
the mouse listener
listener)

Removes the specified mouse listener.

public synchronized void
removeMouseMotionListener(MouseMotionListener
the mouse listener
listener)

Removes the specified mouse-motion listener.

pack-priv void
removeNotify()

public void
setActionCommand(String
a string used to set the tray icon's action command.
command)

Sets the command name for the action event fired by this tray icon.

pack-priv void
setID(int id)

public void
setImage(Image
the non-null Image to be used
image)

Sets the image for this TrayIcon.

public void
setImageAutoSize(boolean
true to auto-size the image, false otherwise
autosize)

Sets the auto-size property.

public void
setPopupMenu(PopupMenu
a PopupMenu or null to remove any popup menu
popup)

Sets the popup menu for this TrayIcon.

public void
setToolTip(String
the string for the tooltip; if the value is null no tooltip is shown
tooltip)

Sets the tooltip string for this TrayIcon.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

accback to summary
private final AccessControlContext acc

Deprecated

as a consequence of AccessControlContext being deprecated. See corresponding docs for further information.

Annotations
@SuppressWarnings:removal
actionCommandback to summary
private String actionCommand
actionListenerback to summary
pack-priv transient ActionListener actionListener
autosizeback to summary
private boolean autosize
idback to summary
private int id
imageback to summary
private Image image
mouseListenerback to summary
pack-priv transient MouseListener mouseListener
mouseMotionListenerback to summary
pack-priv transient MouseMotionListener mouseMotionListener
peerback to summary
private transient TrayIconPeer peer
tooltipback to summary
private String tooltip

Constructor Detail

TrayIconback to summary
private TrayIcon() throws UnsupportedOperationException, HeadlessException, SecurityException
TrayIconback to summary
public TrayIcon(Image image)

Creates a TrayIcon with the specified image.

Parameters
image:Image

the Image to be used

Exceptions
IllegalArgumentException:
if image is null
UnsupportedOperationException:
if the system tray isn't supported by the current platform
HeadlessException:
if GraphicsEnvironment.isHeadless() returns true
SecurityException:
if accessSystemTray permission is not granted
See Also
SystemTray#add(TrayIcon), TrayIcon#TrayIcon(Image, String, PopupMenu), TrayIcon#TrayIcon(Image, String), SecurityManager#checkPermission, AWTPermission
TrayIconback to summary
public TrayIcon(Image image, String tooltip)

Creates a TrayIcon with the specified image and tooltip text. Tooltip may be not visible on some platforms.

Parameters
image:Image

the Image to be used

tooltip:String

the string to be used as tooltip text; if the value is null no tooltip is shown

Exceptions
IllegalArgumentException:
if image is null
UnsupportedOperationException:
if the system tray isn't supported by the current platform
HeadlessException:
if GraphicsEnvironment.isHeadless() returns true
SecurityException:
if accessSystemTray permission is not granted
See Also
SystemTray#add(TrayIcon), TrayIcon#TrayIcon(Image), TrayIcon#TrayIcon(Image, String, PopupMenu), SecurityManager#checkPermission, AWTPermission
TrayIconback to summary
public TrayIcon(Image image, String tooltip, PopupMenu popup)

Creates a TrayIcon with the specified image, tooltip and popup menu. Tooltip may be not visible on some platforms.

Parameters
image:Image

the Image to be used

tooltip:String

the string to be used as tooltip text; if the value is null no tooltip is shown

popup:PopupMenu

the menu to be used for the tray icon's popup menu; if the value is null no popup menu is shown

Exceptions
IllegalArgumentException:
if image is null
UnsupportedOperationException:
if the system tray isn't supported by the current platform
HeadlessException:
if GraphicsEnvironment.isHeadless() returns true
SecurityException:
if accessSystemTray permission is not granted
See Also
SystemTray#add(TrayIcon), TrayIcon#TrayIcon(Image, String), TrayIcon#TrayIcon(Image), PopupMenu, MouseListener, addMouseListener(MouseListener), SecurityManager#checkPermission, AWTPermission

Method Detail

addActionListenerback to summary
public synchronized void addActionListener(ActionListener listener)

Adds the specified action listener to receive ActionEvents from this TrayIcon. Action events usually occur when a user selects the tray icon, using either the mouse or keyboard. The conditions in which action events are generated are platform-dependent.

Calling this method with a null value has no effect.

Refer to AWT Threading Issues for details on AWT's threading model.

Parameters
listener:ActionListener

the action listener

See Also
removeActionListener, getActionListeners, java.awt.event.ActionListener, setActionCommand(String)
addMouseListenerback to summary
public synchronized void addMouseListener(MouseListener listener)

Adds the specified mouse listener to receive mouse events from this TrayIcon. Calling this method with a null value has no effect.

Note

The MouseEvent's coordinates (received from the TrayIcon) are relative to the screen, not the TrayIcon.

Note

The MOUSE_ENTERED and MOUSE_EXITED mouse events are not supported.

Refer to AWT Threading Issues for details on AWT's threading model.

Parameters
listener:MouseListener

the mouse listener

See Also
java.awt.event.MouseEvent, java.awt.event.MouseListener, removeMouseListener(MouseListener), getMouseListeners
addMouseMotionListenerback to summary
public synchronized void addMouseMotionListener(MouseMotionListener listener)

Adds the specified mouse listener to receive mouse-motion events from this TrayIcon. Calling this method with a null value has no effect.

Note

The MouseEvent's coordinates (received from the TrayIcon) are relative to the screen, not the TrayIcon.

Note

The MOUSE_DRAGGED mouse event is not supported.

Refer to AWT Threading Issues for details on AWT's threading model.

Parameters
listener:MouseMotionListener

the mouse listener

See Also
java.awt.event.MouseEvent, java.awt.event.MouseMotionListener, removeMouseMotionListener(MouseMotionListener), getMouseMotionListeners
addNotifyback to summary
pack-priv void addNotify() throws AWTException
dispatchEventback to summary
pack-priv void dispatchEvent(AWTEvent e)
displayMessageback to summary
public void displayMessage(String caption, String text, TrayIcon.MessageType messageType)

Displays a popup message near the tray icon. The message will disappear after a time or if the user clicks on it. Clicking on the message may trigger an ActionEvent.

Either the caption or the text may be null, but an NullPointerException is thrown if both are null. When displayed, the caption or text strings may be truncated on some platforms; the number of characters that may be displayed is platform-dependent.

Note

Some platforms may not support showing a message.

Parameters
caption:String

the caption displayed above the text, usually in bold; may be null

text:String

the text displayed for the particular message; may be null

messageType:TrayIcon.MessageType

an enum indicating the message type

Exceptions
NullPointerException:
if both caption and text are null
getAccessControlContextback to summary
pack-priv final AccessControlContext getAccessControlContext()

Deprecated

as a consequence of AccessControlContext being deprecated. See corresponding docs for further information.

Annotations
@SuppressWarnings:removal
getActionCommandback to summary
public String getActionCommand()

Returns the command name of the action event fired by this tray icon.

Returns:String

the action command name, or null if none exists

See Also
addActionListener(ActionListener), setActionCommand(String)
getActionListenersback to summary
public synchronized ActionListener[] getActionListeners()

Returns an array of all the action listeners registered on this TrayIcon.

Returns:ActionListener[]

all of the ActionListeners registered on this TrayIcon or an empty array if no action listeners are currently registered

See Also
addActionListener(ActionListener), removeActionListener(ActionListener), java.awt.event.ActionListener
getIDback to summary
pack-priv int getID()
getImageback to summary
public Image getImage()

Returns the current image used for this TrayIcon.

Returns:Image

the image

See Also
setImage(Image), Image
getMouseListenersback to summary
public synchronized MouseListener[] getMouseListeners()

Returns an array of all the mouse listeners registered on this TrayIcon.

Returns:MouseListener[]

all of the MouseListeners registered on this TrayIcon or an empty array if no mouse listeners are currently registered

See Also
addMouseListener(MouseListener), removeMouseListener(MouseListener), java.awt.event.MouseListener
getMouseMotionListenersback to summary
public synchronized MouseMotionListener[] getMouseMotionListeners()

Returns an array of all the mouse-motion listeners registered on this TrayIcon.

Returns:MouseMotionListener[]

all of the MouseInputListeners registered on this TrayIcon or an empty array if no mouse listeners are currently registered

See Also
addMouseMotionListener(MouseMotionListener), removeMouseMotionListener(MouseMotionListener), java.awt.event.MouseMotionListener
getPopupMenuback to summary
public PopupMenu getPopupMenu()

Returns the popup menu associated with this TrayIcon.

Returns:PopupMenu

the popup menu or null if none exists

See Also
setPopupMenu(PopupMenu)
getSizeback to summary
public Dimension getSize()

Returns the size, in pixels, of the space that the tray icon occupies in the system tray. For the tray icon that is not yet added to the system tray, the returned size is equal to the result of the SystemTray#getTrayIconSize.

Returns:Dimension

the size of the tray icon, in pixels

See Also
TrayIcon#setImageAutoSize(boolean), java.awt.Image, TrayIcon#getSize()
getToolTipback to summary
public String getToolTip()

Returns the tooltip string associated with this TrayIcon.

Returns:String

the tooltip string or null if none exists

See Also
setToolTip(String)
initIDsback to summary
private static native void initIDs()
isImageAutoSizeback to summary
public boolean isImageAutoSize()

Returns the value of the auto-size property.

Returns:boolean

true if the image will be auto-sized, false otherwise

See Also
setImageAutoSize(boolean)
processActionEventback to summary
pack-priv void processActionEvent(ActionEvent e)
processEventback to summary
pack-priv void processEvent(AWTEvent e)
processMouseEventback to summary
pack-priv void processMouseEvent(MouseEvent e)
processMouseMotionEventback to summary
pack-priv void processMouseMotionEvent(MouseEvent e)
removeActionListenerback to summary
public synchronized void removeActionListener(ActionListener listener)

Removes the specified action listener. Calling this method with null or an invalid value has no effect.

Refer to AWT Threading Issues for details on AWT's threading model.

Parameters
listener:ActionListener

the action listener

See Also
java.awt.event.ActionEvent, java.awt.event.ActionListener, addActionListener(ActionListener), getActionListeners, setActionCommand(String)
removeMouseListenerback to summary
public synchronized void removeMouseListener(MouseListener listener)

Removes the specified mouse listener. Calling this method with null or an invalid value has no effect.

Refer to AWT Threading Issues for details on AWT's threading model.

Parameters
listener:MouseListener

the mouse listener

See Also
java.awt.event.MouseEvent, java.awt.event.MouseListener, addMouseListener(MouseListener), getMouseListeners
removeMouseMotionListenerback to summary
public synchronized void removeMouseMotionListener(MouseMotionListener listener)

Removes the specified mouse-motion listener. Calling this method with null or an invalid value has no effect.

Refer to AWT Threading Issues for details on AWT's threading model.

Parameters
listener:MouseMotionListener

the mouse listener

See Also
java.awt.event.MouseEvent, java.awt.event.MouseMotionListener, addMouseMotionListener(MouseMotionListener), getMouseMotionListeners
removeNotifyback to summary
pack-priv void removeNotify()
setActionCommandback to summary
public void setActionCommand(String command)

Sets the command name for the action event fired by this tray icon. By default, this action command is set to null.

Parameters
command:String

a string used to set the tray icon's action command.

See Also
java.awt.event.ActionEvent, addActionListener(ActionListener), getActionCommand
setIDback to summary
pack-priv void setID(int id)
setImageback to summary
public void setImage(Image image)

Sets the image for this TrayIcon. The previous tray icon image is discarded without calling the java.awt.Image#flush method — you will need to call it manually.

If the image represents an animated image, it will be animated automatically.

See the setImageAutoSize(boolean) property for details on the size of the displayed image.

Calling this method with the same image that is currently being used has no effect.

Parameters
image:Image

the non-null Image to be used

Exceptions
NullPointerException:
if image is null
See Also
getImage, Image, SystemTray#add(TrayIcon), TrayIcon#TrayIcon(Image, String)
setImageAutoSizeback to summary
public void setImageAutoSize(boolean autosize)

Sets the auto-size property. Auto-size determines whether the tray image is automatically sized to fit the space allocated for the image on the tray. By default, the auto-size property is set to false.

If auto-size is false, and the image size doesn't match the tray icon space, the image is painted as-is inside that space — if larger than the allocated space, it will be cropped.

If auto-size is true, the image is stretched or shrunk to fit the tray icon space.

Parameters
autosize:boolean

true to auto-size the image, false otherwise

See Also
isImageAutoSize
setPopupMenuback to summary
public void setPopupMenu(PopupMenu popup)

Sets the popup menu for this TrayIcon. If popup is null, no popup menu will be associated with this TrayIcon.

Note that this popup must not be added to any parent before or after it is set on the tray icon. If you add it to some parent, the popup may be removed from that parent.

The popup can be set on one TrayIcon only. Setting the same popup on multiple TrayIcons will cause an IllegalArgumentException.

Note

Some platforms may not support showing the user-specified popup menu component when the user right-clicks the tray icon. In this situation, either no menu will be displayed or, on some systems, a native version of the menu may be displayed.

Parameters
popup:PopupMenu

a PopupMenu or null to remove any popup menu

Exceptions
IllegalArgumentException:
if the popup is already set for another TrayIcon
See Also
getPopupMenu
setToolTipback to summary
public void setToolTip(String tooltip)

Sets the tooltip string for this TrayIcon. The tooltip is displayed automatically when the mouse hovers over the icon. Tooltip may be not visible on some platforms. Setting the tooltip to null removes any tooltip text. When displayed, the tooltip string may be truncated on some platforms; the number of characters that may be displayed is platform-dependent.

Parameters
tooltip:String

the string for the tooltip; if the value is null no tooltip is shown

See Also
getToolTip
java.awt back to summary

public final Enum TrayIcon.MessageType

extends Enum<TrayIcon.MessageType>
Class Inheritance
The message type determines which icon will be displayed in the caption of the message, and a possible system sound a message may generate upon showing.
Since
1.6
See Also
TrayIcon, TrayIcon#displayMessage(String, String, MessageType)

Field Summary

Modifier and TypeField and Description
public static final TrayIcon.MessageType
ERROR

An error message

public static final TrayIcon.MessageType
INFO

An information message

public static final TrayIcon.MessageType
NONE

Simple message

public static final TrayIcon.MessageType
WARNING

A warning message

Constructor Summary

AccessConstructor and Description
private
MessageType()

Method Summary

Modifier and TypeMethod and Description
public static TrayIcon.MessageType
valueOf(String name)

public static TrayIcon.MessageType[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

ERRORback to summary
public static final TrayIcon.MessageType ERROR

An error message

INFOback to summary
public static final TrayIcon.MessageType INFO

An information message

NONEback to summary
public static final TrayIcon.MessageType NONE

Simple message

WARNINGback to summary
public static final TrayIcon.MessageType WARNING

A warning message

Constructor Detail

MessageTypeback to summary
private MessageType()

Method Detail

valueOfback to summary
public static TrayIcon.MessageType valueOf(String name)
valuesback to summary
public static TrayIcon.MessageType[] values()