- java.lang.Object
-
- java.awt.TrayIcon
-
public class TrayIcon extends Object
ATrayIconobject represents a tray icon that can be added to thesystem tray. ATrayIconcan have a tooltip (text), an image, a popup menu, and a set of listeners associated with it.A
TrayIconcan generate variousMouseEventsand supports adding corresponding listeners to receive notification of these events.TrayIconprocesses some of the events by itself. For example, by default, when the right-mouse click is performed on theTrayIconit displays the specified popup menu. When the mouse hovers over theTrayIconthe tooltip is displayed (this behaviour is platform dependent).Note: When the
MouseEventis dispatched to its registered listeners itscomponentproperty will be set tonull. (SeeComponentEvent.getComponent()) Thesourceproperty will be set to thisTrayIcon. (SeeEventObject.getSource())Note: A well-behaved
TrayIconimplementation will assign different gestures to showing a popup menu and selecting a tray icon.A
TrayIconcan generate anActionEvent. 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
accessSystemTraymust be granted in order to create aTrayIcon. Otherwise the constructor will throw a SecurityException.See the
SystemTrayclass overview for an example on how to use theTrayIconAPI.- Since:
- 1.6
- See Also:
SystemTray.add(java.awt.TrayIcon),ComponentEvent.getComponent(),EventObject.getSource()
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classTrayIcon.MessageTypeThe 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
Constructors Constructor Description TrayIcon(Image image)Creates aTrayIconwith the specified image.TrayIcon(Image image, String tooltip)Creates aTrayIconwith the specified image and tooltip text.TrayIcon(Image image, String tooltip, PopupMenu popup)Creates aTrayIconwith the specified image, tooltip and popup menu.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description voidaddActionListener(ActionListener listener)Adds the specified action listener to receiveActionEvents from thisTrayIcon.voidaddMouseListener(MouseListener listener)Adds the specified mouse listener to receive mouse events from thisTrayIcon.voidaddMouseMotionListener(MouseMotionListener listener)Adds the specified mouse listener to receive mouse-motion events from thisTrayIcon.voiddisplayMessage(String caption, String text, TrayIcon.MessageType messageType)Displays a popup message near the tray icon.StringgetActionCommand()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 thisTrayIcon.ImagegetImage()Returns the current image used for thisTrayIcon.MouseListener[]getMouseListeners()Returns an array of all the mouse listeners registered on thisTrayIcon.MouseMotionListener[]getMouseMotionListeners()Returns an array of all the mouse-motion listeners registered on thisTrayIcon.PopupMenugetPopupMenu()Returns the popup menu associated with thisTrayIcon.DimensiongetSize()Returns the size, in pixels, of the space that the tray icon occupies in the system tray.StringgetToolTip()Returns the tooltip string associated with thisTrayIcon.booleanisImageAutoSize()Returns the value of the auto-size property.voidremoveActionListener(ActionListener listener)Removes the specified action listener.voidremoveMouseListener(MouseListener listener)Removes the specified mouse listener.voidremoveMouseMotionListener(MouseMotionListener listener)Removes the specified mouse-motion listener.voidsetActionCommand(String command)Sets the command name for the action event fired by this tray icon.voidsetImage(Image image)Sets the image for thisTrayIcon.voidsetImageAutoSize(boolean autosize)Sets the auto-size property.voidsetPopupMenu(PopupMenu popup)Sets the popup menu for thisTrayIcon.voidsetToolTip(String tooltip)Sets the tooltip string for thisTrayIcon.
-
-
-
Constructor Detail
-
TrayIcon
public TrayIcon(Image image)
Creates aTrayIconwith the specified image.- Parameters:
image- theImageto be used- Throws:
IllegalArgumentException- ifimageisnullUnsupportedOperationException- if the system tray isn't supported by the current platformHeadlessException- ifGraphicsEnvironment.isHeadless()returnstrueSecurityException- ifaccessSystemTraypermission is not granted- See Also:
SystemTray.add(TrayIcon),TrayIcon(Image, String, PopupMenu),TrayIcon(Image, String),SecurityManager.checkPermission(java.security.Permission),AWTPermission
-
TrayIcon
public TrayIcon(Image image, String tooltip)
Creates aTrayIconwith the specified image and tooltip text. Tooltip may be not visible on some platforms.- Parameters:
image- theImageto be usedtooltip- the string to be used as tooltip text; if the value isnullno tooltip is shown- Throws:
IllegalArgumentException- ifimageisnullUnsupportedOperationException- if the system tray isn't supported by the current platformHeadlessException- ifGraphicsEnvironment.isHeadless()returnstrueSecurityException- ifaccessSystemTraypermission is not granted- See Also:
SystemTray.add(TrayIcon),TrayIcon(Image),TrayIcon(Image, String, PopupMenu),SecurityManager.checkPermission(java.security.Permission),AWTPermission
-
TrayIcon
public TrayIcon(Image image, String tooltip, PopupMenu popup)
Creates aTrayIconwith the specified image, tooltip and popup menu. Tooltip may be not visible on some platforms.- Parameters:
image- theImageto be usedtooltip- the string to be used as tooltip text; if the value isnullno tooltip is shownpopup- the menu to be used for the tray icon's popup menu; if the value isnullno popup menu is shown- Throws:
IllegalArgumentException- ifimageisnullUnsupportedOperationException- if the system tray isn't supported by the current platformHeadlessException- ifGraphicsEnvironment.isHeadless()returnstrueSecurityException- ifaccessSystemTraypermission is not granted- See Also:
SystemTray.add(TrayIcon),TrayIcon(Image, String),TrayIcon(Image),PopupMenu,MouseListener,addMouseListener(MouseListener),SecurityManager.checkPermission(java.security.Permission),AWTPermission
-
-
Method Detail
-
setImage
public void setImage(Image image)
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-nullImageto be used- Throws:
NullPointerException- ifimageisnull- See Also:
getImage(),Image,SystemTray.add(TrayIcon),TrayIcon(Image, String)
-
getImage
public Image getImage()
Returns the current image used for thisTrayIcon.- Returns:
- the image
- See Also:
setImage(Image),Image
-
setPopupMenu
public void setPopupMenu(PopupMenu popup)
Sets the popup menu for thisTrayIcon. Ifpopupisnull, no popup menu will be associated with thisTrayIcon.Note that this
popupmust not be added to any parent before or after it is set on the tray icon. If you add it to some parent, thepopupmay be removed from that parent.The
popupcan be set on oneTrayIcononly. Setting the same popup on multipleTrayIcons 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- aPopupMenuornullto remove any popup menu- Throws:
IllegalArgumentException- if thepopupis already set for anotherTrayIcon- See Also:
getPopupMenu()
-
getPopupMenu
public PopupMenu getPopupMenu()
Returns the popup menu associated with thisTrayIcon.- Returns:
- the popup menu or
nullif none exists - See Also:
setPopupMenu(PopupMenu)
-
setToolTip
public void setToolTip(String tooltip)
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 tonullremoves 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 isnullno tooltip is shown- See Also:
getToolTip()
-
getToolTip
public String getToolTip()
Returns the tooltip string associated with thisTrayIcon.- Returns:
- the tooltip string or
nullif none exists - See Also:
setToolTip(String)
-
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-trueto auto-size the image,falseotherwise- See Also:
isImageAutoSize()
-
isImageAutoSize
public boolean isImageAutoSize()
Returns the value of the auto-size property.- Returns:
trueif the image will be auto-sized,falseotherwise- See Also:
setImageAutoSize(boolean)
-
addMouseListener
public void addMouseListener(MouseListener listener)
Adds the specified mouse listener to receive mouse events from thisTrayIcon. Calling this method with anullvalue has no effect.Note: The
MouseEvent's coordinates (received from theTrayIcon) are relative to the screen, not theTrayIcon.Note: The
MOUSE_ENTEREDandMOUSE_EXITEDmouse events are not supported.Refer to AWT Threading Issues for details on AWT's threading model.
- Parameters:
listener- the mouse listener- See Also:
MouseEvent,MouseListener,removeMouseListener(MouseListener),getMouseListeners()
-
removeMouseListener
public void removeMouseListener(MouseListener listener)
Removes the specified mouse listener. Calling this method withnullor 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:
MouseEvent,MouseListener,addMouseListener(MouseListener),getMouseListeners()
-
getMouseListeners
public MouseListener[] getMouseListeners()
Returns an array of all the mouse listeners registered on thisTrayIcon.- Returns:
- all of the
MouseListenersregistered on thisTrayIconor an empty array if no mouse listeners are currently registered - See Also:
addMouseListener(MouseListener),removeMouseListener(MouseListener),MouseListener
-
addMouseMotionListener
public void addMouseMotionListener(MouseMotionListener listener)
Adds the specified mouse listener to receive mouse-motion events from thisTrayIcon. Calling this method with anullvalue has no effect.Note: The
MouseEvent's coordinates (received from theTrayIcon) are relative to the screen, not theTrayIcon.Note: The
MOUSE_DRAGGEDmouse event is not supported.Refer to AWT Threading Issues for details on AWT's threading model.
- Parameters:
listener- the mouse listener- See Also:
MouseEvent,MouseMotionListener,removeMouseMotionListener(MouseMotionListener),getMouseMotionListeners()
-
removeMouseMotionListener
public void removeMouseMotionListener(MouseMotionListener listener)
Removes the specified mouse-motion listener. Calling this method withnullor 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:
MouseEvent,MouseMotionListener,addMouseMotionListener(MouseMotionListener),getMouseMotionListeners()
-
getMouseMotionListeners
public MouseMotionListener[] getMouseMotionListeners()
Returns an array of all the mouse-motion listeners registered on thisTrayIcon.- Returns:
- all of the
MouseInputListenersregistered on thisTrayIconor an empty array if no mouse listeners are currently registered - See Also:
addMouseMotionListener(MouseMotionListener),removeMouseMotionListener(MouseMotionListener),MouseMotionListener
-
getActionCommand
public String getActionCommand()
Returns the command name of the action event fired by this tray icon.- Returns:
- the action command name, or
nullif none exists - See Also:
addActionListener(ActionListener),setActionCommand(String)
-
setActionCommand
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 tonull.- Parameters:
command- a string used to set the tray icon's action command.- See Also:
ActionEvent,addActionListener(ActionListener),getActionCommand()
-
addActionListener
public void addActionListener(ActionListener listener)
Adds the specified action listener to receiveActionEvents 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
nullvalue has no effect.Refer to AWT Threading Issues for details on AWT's threading model.
- Parameters:
listener- the action listener- See Also:
removeActionListener(java.awt.event.ActionListener),getActionListeners(),ActionListener,setActionCommand(String)
-
removeActionListener
public void removeActionListener(ActionListener listener)
Removes the specified action listener. Calling this method withnullor 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:
ActionEvent,ActionListener,addActionListener(ActionListener),getActionListeners(),setActionCommand(String)
-
getActionListeners
public ActionListener[] getActionListeners()
Returns an array of all the action listeners registered on thisTrayIcon.- Returns:
- all of the
ActionListenersregistered on thisTrayIconor an empty array if no action listeners are currently registered - See Also:
addActionListener(ActionListener),removeActionListener(ActionListener),ActionListener
-
displayMessage
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 anActionEvent.Either the caption or the text may be
null, but anNullPointerExceptionis 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 benulltext- the text displayed for the particular message; may benullmessageType- an enum indicating the message type- Throws:
NullPointerException- if bothcaptionandtextarenull
-
getSize
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 theSystemTray.getTrayIconSize().- Returns:
- the size of the tray icon, in pixels
- See Also:
setImageAutoSize(boolean),Image,getSize()
-
-