Class TrayIcon
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.
- 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. - Since:
- 1.6
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic enum
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 Summary
ConstructorDescriptionCreates aTrayIcon
with the specified image.Creates aTrayIcon
with the specified image and tooltip text.Creates aTrayIcon
with the specified image, tooltip and popup menu. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addActionListener
(ActionListener listener) Adds the specified action listener to receiveActionEvent
s from thisTrayIcon
.void
addMouseListener
(MouseListener listener) Adds the specified mouse listener to receive mouse events from thisTrayIcon
.void
addMouseMotionListener
(MouseMotionListener listener) Adds the specified mouse listener to receive mouse-motion events from thisTrayIcon
.void
displayMessage
(String caption, String text, TrayIcon.MessageType messageType) Displays a popup message near the tray icon.Returns the command name of the action event fired by this tray icon.Returns an array of all the action listeners registered on thisTrayIcon
.getImage()
Returns the current image used for thisTrayIcon
.Returns an array of all the mouse listeners registered on thisTrayIcon
.Returns an array of all the mouse-motion listeners registered on thisTrayIcon
.Returns the popup menu associated with thisTrayIcon
.getSize()
Returns the size, in pixels, of the space that the tray icon occupies in the system tray.Returns the tooltip string associated with thisTrayIcon
.boolean
Returns the value of the auto-size property.void
removeActionListener
(ActionListener listener) Removes the specified action listener.void
removeMouseListener
(MouseListener listener) Removes the specified mouse listener.void
removeMouseMotionListener
(MouseMotionListener listener) Removes the specified mouse-motion listener.void
setActionCommand
(String command) Sets the command name for the action event fired by this tray icon.void
Sets the image for thisTrayIcon
.void
setImageAutoSize
(boolean autosize) Sets the auto-size property.void
setPopupMenu
(PopupMenu popup) Sets the popup menu for thisTrayIcon
.void
setToolTip
(String tooltip) Sets the tooltip string for thisTrayIcon
.
-
Constructor Details
-
TrayIcon
Creates aTrayIcon
with the specified image.- Parameters:
image
- theImage
to be used- Throws:
IllegalArgumentException
- ifimage
isnull
UnsupportedOperationException
- if the system tray isn't supported by the current platformHeadlessException
- ifGraphicsEnvironment.isHeadless()
returnstrue
SecurityException
- ifaccessSystemTray
permission is not granted- See Also:
-
TrayIcon
Creates aTrayIcon
with the specified image and tooltip text. Tooltip may be not visible on some platforms.- Parameters:
image
- theImage
to be usedtooltip
- the string to be used as tooltip text; if the value isnull
no tooltip is shown- Throws:
IllegalArgumentException
- ifimage
isnull
UnsupportedOperationException
- if the system tray isn't supported by the current platformHeadlessException
- ifGraphicsEnvironment.isHeadless()
returnstrue
SecurityException
- ifaccessSystemTray
permission is not granted- See Also:
-
TrayIcon
Creates aTrayIcon
with the specified image, tooltip and popup menu. Tooltip may be not visible on some platforms.- Parameters:
image
- theImage
to be usedtooltip
- the string to be used as tooltip text; if the value isnull
no tooltip is shownpopup
- the menu to be used for the tray icon's popup menu; if the value isnull
no popup menu is shown- Throws:
IllegalArgumentException
- ifimage
isnull
UnsupportedOperationException
- if the system tray isn't supported by the current platformHeadlessException
- ifGraphicsEnvironment.isHeadless()
returnstrue
SecurityException
- ifaccessSystemTray
permission is not granted- See Also:
-
-
Method Details
-
setImage
Sets the image for thisTrayIcon
. The previous tray icon image is discarded without calling theImage.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
- the non-nullImage
to be used- Throws:
NullPointerException
- ifimage
isnull
- See Also:
-
getImage
Returns the current image used for thisTrayIcon
.- Returns:
- the image
- See Also:
-
setPopupMenu
Sets the popup menu for thisTrayIcon
. Ifpopup
isnull
, no popup menu will be associated with thisTrayIcon
.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, thepopup
may be removed from that parent.The
popup
can be set on oneTrayIcon
only. Setting the same popup on multipleTrayIcon
s will cause anIllegalArgumentException
.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
- aPopupMenu
ornull
to remove any popup menu- Throws:
IllegalArgumentException
- if thepopup
is already set for anotherTrayIcon
- See Also:
-
getPopupMenu
Returns the popup menu associated with thisTrayIcon
.- Returns:
- the popup menu or
null
if none exists - See Also:
-
setToolTip
Sets the tooltip string for thisTrayIcon
. The tooltip is displayed automatically when the mouse hovers over the icon. Tooltip may be not visible on some platforms. Setting the tooltip tonull
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
- the string for the tooltip; if the value isnull
no tooltip is shown- See Also:
-
getToolTip
Returns the tooltip string associated with thisTrayIcon
.- Returns:
- the tooltip string or
null
if none exists - See Also:
-
setImageAutoSize
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 tofalse
.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
-true
to auto-size the image,false
otherwise- See Also:
-
isImageAutoSize
public boolean isImageAutoSize()Returns the value of the auto-size property.- Returns:
true
if the image will be auto-sized,false
otherwise- See Also:
-
addMouseListener
Adds the specified mouse listener to receive mouse events from thisTrayIcon
. Calling this method with anull
value has no effect.Note: The
MouseEvent
's coordinates (received from theTrayIcon
) are relative to the screen, not theTrayIcon
.Note: The
MOUSE_ENTERED
andMOUSE_EXITED
mouse events are not supported.Refer to AWT Threading Issues for details on AWT's threading model.
- Parameters:
listener
- the mouse listener- See Also:
-
removeMouseListener
Removes the specified mouse listener. Calling this method withnull
or an invalid value has no effect.Refer to AWT Threading Issues for details on AWT's threading model.
- Parameters:
listener
- the mouse listener- See Also:
-
getMouseListeners
Returns an array of all the mouse listeners registered on thisTrayIcon
.- Returns:
- all of the
MouseListeners
registered on thisTrayIcon
or an empty array if no mouse listeners are currently registered - See Also:
-
addMouseMotionListener
Adds the specified mouse listener to receive mouse-motion events from thisTrayIcon
. Calling this method with anull
value has no effect.Note: The
MouseEvent
's coordinates (received from theTrayIcon
) are relative to the screen, not theTrayIcon
.Note: The
MOUSE_DRAGGED
mouse event is not supported.Refer to AWT Threading Issues for details on AWT's threading model.
- Parameters:
listener
- the mouse listener- See Also:
-
removeMouseMotionListener
Removes the specified mouse-motion listener. Calling this method withnull
or an invalid value has no effect.Refer to AWT Threading Issues for details on AWT's threading model.
- Parameters:
listener
- the mouse listener- See Also:
-
getMouseMotionListeners
Returns an array of all the mouse-motion listeners registered on thisTrayIcon
.- Returns:
- all of the
MouseInputListeners
registered on thisTrayIcon
or an empty array if no mouse listeners are currently registered - See Also:
-
getActionCommand
Returns the command name of the action event fired by this tray icon.- Returns:
- the action command name, or
null
if none exists - See Also:
-
setActionCommand
Sets the command name for the action event fired by this tray icon. By default, this action command is set tonull
.- Parameters:
command
- a string used to set the tray icon's action command.- See Also:
-
addActionListener
Adds the specified action listener to receiveActionEvent
s from thisTrayIcon
. 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
- the action listener- See Also:
-
removeActionListener
Removes the specified action listener. Calling this method withnull
or an invalid value has no effect.Refer to AWT Threading Issues for details on AWT's threading model.
- Parameters:
listener
- the action listener- See Also:
-
getActionListeners
Returns an array of all the action listeners registered on thisTrayIcon
.- Returns:
- all of the
ActionListeners
registered on thisTrayIcon
or an empty array if no action listeners are currently registered - See Also:
-
displayMessage
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 anActionEvent
.Either the caption or the text may be
null
, but anNullPointerException
is thrown if both arenull
. 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
- the caption displayed above the text, usually in bold; may benull
text
- the text displayed for the particular message; may benull
messageType
- an enum indicating the message type- Throws:
NullPointerException
- if bothcaption
andtext
arenull
-
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 theSystemTray.getTrayIconSize()
.- Returns:
- the size of the tray icon, in pixels
- See Also:
-