java.lang.Object | |
↳ | java.awt.SystemTray |
The SystemTray
class represents the system tray for a
desktop. On Microsoft Windows it is referred to as the "Taskbar
Status Area", on Gnome it is referred to as the "Notification
Area", on KDE it is referred to as the "System Tray". The system
tray is shared by all applications running on the desktop.
On some platforms the system tray may not be present or may not
be supported, in this case getSystemTray()
throws UnsupportedOperationException
. To detect whether the
system tray is supported, use isSupported()
.
The SystemTray
may contain one or more TrayIcons
, which are added to the tray using the add(TrayIcon)
method, and removed when no longer needed, using the
remove(TrayIcon)
. TrayIcon
consists of an
image, a popup menu and a set of associated listeners. Please see
the TrayIcon
class for details.
Every Java application has a single SystemTray
instance that allows the app to interface with the system tray of
the desktop while the app is running. The SystemTray
instance can be obtained from the getSystemTray()
method.
An application may not create its own instance of
SystemTray
.
The following code snippet demonstrates how to access
and customize the system tray:
TrayIcon
trayIcon = null;
if (SystemTray.isSupported()) {
// get the SystemTray instance
SystemTray tray = SystemTray.getSystemTray()
;
// load an image
Image
image = Toolkit.getDefaultToolkit().getImage
(...);
// create a action listener to listen for default action executed on the tray icon
ActionListener
listener = new ActionListener
() {
public void actionPerformed
(ActionEvent
e) {
// execute default action of the application
// ...
}
};
// create a popup menu
PopupMenu
popup = new PopupMenu
();
// create menu item for the default action
MenuItem defaultItem = new MenuItem(...);
defaultItem.addActionListener(listener);
popup.add(defaultItem);
/// ... add other items
// construct a TrayIcon
trayIcon = new TrayIcon
(image, "Tray Demo", popup);
// set the TrayIcon properties
trayIcon.addActionListener
(listener);
// ...
// add the tray image
try {
tray.add
(trayIcon);
} catch (AWTException e) {
System.err.println(e);
}
// ...
} else {
// disable tray option in your application or
// perform other actions
...
}
// ...
// some time later
// the application state has changed - update the image
if (trayIcon != null) {
trayIcon.setImage
(updatedImage);
}
// ...
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Adds a
TrayIcon to the SystemTray . | |||||||||||
Adds a
PropertyChangeListener to the listener list for a
specific property. | |||||||||||
Returns an array of all the listeners that have been associated
with the named property.
| |||||||||||
Gets the
SystemTray instance that represents the
desktop's tray area. | |||||||||||
Returns the size, in pixels, of the space that a tray icon will
occupy in the system tray.
| |||||||||||
Returns an array of all icons added to the tray by this
application.
| |||||||||||
Returns whether the system tray is supported on the current
platform.
| |||||||||||
Removes the specified
TrayIcon from the
SystemTray . | |||||||||||
Removes a
PropertyChangeListener from the listener list
for a specific property. |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Adds a TrayIcon
to the SystemTray
.
The tray icon becomes visible in the system tray once it is
added. The order in which icons are displayed in a tray is not
specified - it is platform and implementation-dependent.
All icons added by the application are automatically
removed from the SystemTray
upon application exit
and also when the desktop system tray becomes unavailable.
trayIcon | the TrayIcon to be added |
---|
NullPointerException | if trayIcon is
null |
---|---|
IllegalArgumentException | if the same instance of
a TrayIcon is added more than once |
AWTException | if the desktop system tray is missing |
Adds a PropertyChangeListener
to the listener list for a
specific property. Currently supported property:
trayIcons
This SystemTray
's array of TrayIcon
s.
The array is accessed via getTrayIcons()
.
This property is changed when a TrayIcon
is added to
(or removed from) the SystemTray
.
For example, this property
is changed when the native SystemTray
becomes unavailable on the
desktop
and the TrayIcon
s are automatically removed.
The listener
listens to property changes only in this context.
If listener
is null
, no exception is thrown
and no action is performed.
propertyName | the specified property |
---|---|
listener | the property change listener to be added |
Returns an array of all the listeners that have been associated with the named property.
Only the listeners in this context are returned.
propertyName | the specified property |
---|
PropertyChangeListener
s associated with
the named property; if no such listeners have been added or
if propertyName
is null
or invalid, an empty
array is returnedGets the SystemTray
instance that represents the
desktop's tray area. This always returns the same instance per
application. On some platforms the system tray may not be
supported. You may use the isSupported()
method to
check if the system tray is supported.
If a SecurityManager is installed, the AWTPermission
accessSystemTray
must be granted in order to get the
SystemTray
instance. Otherwise this method will throw a
SecurityException.
SystemTray
instance that represents
the desktop's tray areaUnsupportedOperationException | if the system tray isn't supported by the current platform |
---|---|
HeadlessException | if
GraphicsEnvironment.isHeadless() returns true |
SecurityException | if accessSystemTray permission
is not granted |
Returns the size, in pixels, of the space that a tray icon will
occupy in the system tray. Developers may use this methods to
acquire the preferred size for the image property of a tray icon
before it is created. For convenience, there is a similar
method getSize()
in the TrayIcon
class.
Returns an array of all icons added to the tray by this application. You can't access the icons added by another application. Some browsers partition applets in different code bases into separate contexts, and establish walls between these contexts. In such a scenario, only the tray icons added from this context will be returned.
The returned array is a copy of the actual array and may be
modified in any way without affecting the system tray. To
remove a TrayIcon
from the
SystemTray
, use the remove(TrayIcon)
method.
Returns whether the system tray is supported on the current
platform. In addition to displaying the tray icon, minimal
system tray support includes either a popup menu (see setPopupMenu(PopupMenu)
) or an action event (see
addActionListener(ActionListener)
).
Developers should not assume that all of the system tray
functionality is supported. To guarantee that the tray icon's
default action is always accessible, add the default action to
both the action listener and the popup menu. See the example
for an example of how to do this.
Note: When implementing SystemTray
and
TrayIcon
it is strongly recommended that
you assign different gestures to the popup menu and an action
event. Overloading a gesture for both purposes is confusing
and may prevent the user from accessing one or the other.
false
if no system tray access is supported; this
method returns true
if the minimal system tray access is
supported but does not guarantee that all system tray
functionality is supported for the current platform
Removes the specified TrayIcon
from the
SystemTray
.
All icons added by the application are automatically
removed from the SystemTray
upon application exit
and also when the desktop system tray becomes unavailable.
If trayIcon
is null
or was not
added to the system tray, no exception is thrown and no action
is performed.
trayIcon | the TrayIcon to be removed |
---|
Removes a PropertyChangeListener
from the listener list
for a specific property.
The PropertyChangeListener
must be from this context.
If propertyName
or listener
is null
or invalid,
no exception is thrown and no action is taken.
propertyName | the specified property |
---|---|
listener | the PropertyChangeListener to be removed |