java.lang.Object | |
↳ | java.awt.TrayIcon |
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.
Note: When the MouseEvent
is
dispatched to its registered listeners its component
property will be set to null
. (See getComponent()
) The
source
property will be set to this
TrayIcon
. (See 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.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
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. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Creates a
TrayIcon with the specified image. | |||||||||||
Creates a
TrayIcon with the specified image and
tooltip text. | |||||||||||
Creates a
TrayIcon with the specified image,
tooltip and popup menu. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Adds the specified action listener to receive
ActionEvent s from this TrayIcon . | |||||||||||
Adds the specified mouse listener to receive mouse events from
this
TrayIcon . | |||||||||||
Adds the specified mouse listener to receive mouse-motion
events from this
TrayIcon . | |||||||||||
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 this
TrayIcon . | |||||||||||
Returns the current image used for this
TrayIcon . | |||||||||||
Returns an array of all the mouse listeners
registered on this
TrayIcon . | |||||||||||
Returns an array of all the mouse-motion listeners
registered on this
TrayIcon . | |||||||||||
Returns the popup menu associated with this
TrayIcon . | |||||||||||
Returns the size, in pixels, of the space that the tray icon
occupies in the system tray.
| |||||||||||
Returns the tooltip string associated with this
TrayIcon . | |||||||||||
Returns the value of the auto-size property.
| |||||||||||
Removes the specified action listener.
| |||||||||||
Removes the specified mouse listener.
| |||||||||||
Removes the specified mouse-motion listener.
| |||||||||||
Sets the command name for the action event fired by this tray
icon.
| |||||||||||
Sets the image for this
TrayIcon . | |||||||||||
Sets the auto-size property.
| |||||||||||
Sets the popup menu for this
TrayIcon . | |||||||||||
Sets the tooltip string for this
TrayIcon . |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Creates a TrayIcon
with the specified image.
image | the Image to be used |
---|
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 |
Creates a TrayIcon
with the specified image and
tooltip text.
image | the Image to be used |
---|---|
tooltip | the string to be used as tooltip text; if the
value is null no tooltip is shown |
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 |
Creates a TrayIcon
with the specified image,
tooltip and popup menu.
image | the Image to be used |
---|---|
tooltip | the string to be used as tooltip text; if the
value is null no tooltip is shown |
popup | the menu to be used for the tray icon's popup
menu; if the value is null no popup menu is shown |
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 |
Adds the specified action listener to receive
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 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.
listener | the mouse 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.
listener | the mouse listener |
---|
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.
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 type |
NullPointerException | if both caption
and text are null
|
---|
Returns the command name of the action event fired by this tray icon.
null
if none existsReturns an array of all the action listeners
registered on this TrayIcon
.
ActionListeners
registered on
this TrayIcon
or an empty array if no action
listeners are currently registeredReturns an array of all the mouse listeners
registered on this TrayIcon
.
MouseListeners
registered on
this TrayIcon
or an empty array if no mouse
listeners are currently registeredReturns an array of all the mouse-motion listeners
registered on this TrayIcon
.
MouseInputListeners
registered on
this TrayIcon
or an empty array if no mouse
listeners are currently registeredReturns the popup menu associated with this TrayIcon
.
null
if none existsReturns 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 getTrayIconSize()
.
Returns the tooltip string associated with this
TrayIcon
.
null
if none existsReturns the value of the auto-size property.
true
if the image will be auto-sized,
false
otherwiseRemoves 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.
listener | the action 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.
listener | the mouse 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.
listener | the mouse listener |
---|
Sets the command name for the action event fired by this tray
icon. By default, this action command is set to
null
.
command | a string used to set the tray icon's action command. |
---|
Sets the image for this TrayIcon
. The previous
tray icon image is discarded without calling the 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 used |
---|
NullPointerException | if image is null |
---|
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.
autosize | true to auto-size the image,
false otherwise |
---|
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 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 menu |
---|
IllegalArgumentException | if the popup is already
set for another TrayIcon |
---|
Sets the tooltip string for this TrayIcon
. The
tooltip is displayed automatically when the mouse hovers over
the icon. 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 shown |
---|