public class TrayIcon extends Object
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 ComponentEvent.getComponent()
) The source
property will be set to this TrayIcon
. (See 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.
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.Modifier and Type | Class | Description |
---|---|---|
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. |
Constructor | Description |
---|---|
TrayIcon |
Creates a TrayIcon with the specified image. |
TrayIcon |
Creates a TrayIcon with the specified image and tooltip text. |
TrayIcon |
Creates a TrayIcon with the specified image, tooltip and popup menu. |
Modifier and Type | Method | Description |
---|---|---|
void |
addActionListener |
Adds the specified action listener to receive ActionEvent s from this TrayIcon . |
void |
addMouseListener |
Adds the specified mouse listener to receive mouse events from this TrayIcon . |
void |
addMouseMotionListener |
Adds the specified mouse listener to receive mouse-motion events from this TrayIcon . |
void |
displayMessage |
Displays a popup message near the tray icon. |
String |
getActionCommand() |
Returns the command name of the action event fired by this tray icon. |
ActionListener[] |
getActionListeners() |
Returns an array of all the action listeners registered on this TrayIcon . |
Image |
getImage() |
Returns the current image used for this TrayIcon . |
MouseListener[] |
getMouseListeners() |
Returns an array of all the mouse listeners registered on this TrayIcon . |
MouseMotionListener[] |
getMouseMotionListeners() |
Returns an array of all the mouse-motion listeners registered on this TrayIcon . |
PopupMenu |
getPopupMenu() |
Returns the popup menu associated with this TrayIcon . |
Dimension |
getSize() |
Returns the size, in pixels, of the space that the tray icon occupies in the system tray. |
String |
getToolTip() |
Returns the tooltip string associated with this TrayIcon . |
boolean |
isImageAutoSize() |
Returns the value of the auto-size property. |
void |
removeActionListener |
Removes the specified action listener. |
void |
removeMouseListener |
Removes the specified mouse listener. |
void |
removeMouseMotionListener |
Removes the specified mouse-motion listener. |
void |
setActionCommand |
Sets the command name for the action event fired by this tray icon. |
void |
setImage |
Sets the image for this TrayIcon . |
void |
setImageAutoSize |
Sets the auto-size property. |
void |
setPopupMenu |
Sets the popup menu for this TrayIcon . |
void |
setToolTip |
Sets the tooltip string for this TrayIcon . |
public TrayIcon(Image image)
TrayIcon
with the specified image.image
- the Image
to be usedIllegalArgumentException
- if image
is null
UnsupportedOperationException
- if the system tray isn't supported by the current platformHeadlessException
- if GraphicsEnvironment.isHeadless()
returns true
SecurityException
- if accessSystemTray
permission is not grantedpublic TrayIcon(Image image, String tooltip)
TrayIcon
with the specified image and tooltip text. Tooltip may be not visible on some platforms.image
- the Image
to be usedtooltip
- the string to be used as tooltip text; if the value is null
no tooltip is shownIllegalArgumentException
- if image
is null
UnsupportedOperationException
- if the system tray isn't supported by the current platformHeadlessException
- if GraphicsEnvironment.isHeadless()
returns true
SecurityException
- if accessSystemTray
permission is not grantedpublic TrayIcon(Image image, String tooltip, PopupMenu popup)
TrayIcon
with the specified image, tooltip and popup menu. Tooltip may be not visible on some platforms.image
- the Image
to be usedtooltip
- the string to be used as tooltip text; if the value is null
no tooltip is shownpopup
- the menu to be used for the tray icon's popup menu; if the value is null
no popup menu is shownIllegalArgumentException
- if image
is null
UnsupportedOperationException
- if the system tray isn't supported by the current platformHeadlessException
- if GraphicsEnvironment.isHeadless()
returns true
SecurityException
- if accessSystemTray
permission is not grantedpublic void setImage(Image image)
TrayIcon
. The previous tray icon image is discarded without calling the 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.
image
- the non-null Image
to be usedNullPointerException
- if image
is null
public Image getImage()
TrayIcon
.public void setPopupMenu(PopupMenu popup)
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 TrayIcon
s 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.
popup
- a PopupMenu
or null
to remove any popup menuIllegalArgumentException
- if the popup
is already set for another TrayIcon
public PopupMenu getPopupMenu()
TrayIcon
.null
if none existspublic void setToolTip(String tooltip)
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.tooltip
- the string for the tooltip; if the value is null
no tooltip is shownpublic String getToolTip()
TrayIcon
.null
if none existspublic void setImageAutoSize(boolean autosize)
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.
autosize
- true
to auto-size the image, false
otherwisepublic boolean isImageAutoSize()
true
if the image will be auto-sized, false
otherwisepublic void addMouseListener(MouseListener listener)
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.
listener
- the mouse listenerpublic void removeMouseListener(MouseListener listener)
null
or an invalid value has no effect. Refer to AWT Threading Issues for details on AWT's threading model.
listener
- the mouse listenerpublic MouseListener[] getMouseListeners()
TrayIcon
.MouseListeners
registered on this TrayIcon
or an empty array if no mouse listeners are currently registeredpublic void addMouseMotionListener(MouseMotionListener listener)
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.
listener
- the mouse listenerpublic void removeMouseMotionListener(MouseMotionListener listener)
null
or an invalid value has no effect. Refer to AWT Threading Issues for details on AWT's threading model.
listener
- the mouse listenerpublic MouseMotionListener[] getMouseMotionListeners()
TrayIcon
.MouseInputListeners
registered on this TrayIcon
or an empty array if no mouse listeners are currently registeredpublic String getActionCommand()
null
if none existspublic void setActionCommand(String command)
null
.command
- a string used to set the tray icon's action command.public void addActionListener(ActionListener listener)
ActionEvent
s 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.
listener
- the action listenerpublic void removeActionListener(ActionListener listener)
null
or an invalid value has no effect. Refer to AWT Threading Issues for details on AWT's threading model.
listener
- the action listenerpublic ActionListener[] getActionListeners()
TrayIcon
.ActionListeners
registered on this TrayIcon
or an empty array if no action listeners are currently registeredpublic void displayMessage(String caption, String text, TrayIcon.MessageType messageType)
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.
caption
- the caption displayed above the text, usually in bold; may be null
text
- the text displayed for the particular message; may be null
messageType
- an enum indicating the message typeNullPointerException
- if both caption
and text
are null
public Dimension getSize()
SystemTray.getTrayIconSize()
.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/java/awt/TrayIcon.html