com.jpackages.jtray
Class JTrayIcon

java.lang.Object
  com.jpackages.jtray.JTrayIcon

public class JTrayIcon
extends java.lang.Object

This class provides all functionality to an icon for display in the System Tray.

Example:

 // specify your registration key if you have purchased a registered version
 JTrayIcon.setRegistrationKey("AAAA-BBBB-CCCC-DDDD-EEEE-FFFF");

 JTrayIcon jTrayIcon = new JTrayIcon("icon1.gif", ImageFileType.JAVA_SUPPORTED);

 // define a JPopupMenu
 JPopupMenu jPopupMenu = new JPopupMenu();
 jPopupMenu.add("item 1");
 jPopupMenu.add("item 2");
 jPopupMenu.add("item 3");

 // specify the popup menu as the right click target
 // it will be displayed when a right click on the icon occurs
 jTrayIcon.setRightClickTarget(jPopupMenu);

 // show the icon
 jTrayIcon.setVisible(true);
 

Note: Popup targets will not function properly while a modal dialog box is being displayed in the same application instance. Before displaying a modal dialog box, the targets should be disabled. They should then be enabled afterwards as follows:

 // need to disable targets before showing a modal dialog box
 jTrayIcon.disableTargets();
 JOptionPane.showMessageDialog(null, "Dialog message");
 // enable targets after showing a modal dialog box
 jTrayIcon.enableTargets();
 

Copyright (c) 2001-2008

Version:

1.7

Author:

JPackages.com

Constructor Summary

JTrayIcon(java.awt.Image i)
Constructs a JTrayIcon with the specified Image as the icon.

JTrayIcon(javax.swing.ImageIcon i)
Constructs a JTrayIcon with the specified ImageIcon.

JTrayIcon(java.lang.String filePath, int file_type)
Constructs a JTrayIcon with the specified icon.

JTrayIcon(java.lang.String filePath, int file_type, int index)
Constructs a JTrayIcon with the specified icon.

Method Summary

void	addJTrayListener(JTrayListener jTrayListener) Adds a JTrayListener which will be notifed of mouse events for the JTrayIcon.
void	addNoHideComponent(java.awt.Component component) Specifies a component that should not cause a right or left click target to hide when it is clicked.
static void	disableTargets() Disables both right and left click targets for all JTrayIcon instances.
static void	enableTargets() Enables both right and left click targets for all JTrayIcon instances.
java.lang.String	getIconFilePath() Retrieves the file path for the icon file of this JTrayIcon if this icon was set with an icon with a file path.
java.awt.Image	getIconImage() Retrieves the Image of this JTrayIcon if this icon was set with an Image or ImageIcon.
int	getLeftHideDelay() Retrieves the current delay (in milliseconds) for hiding the left click target component.
int	getRightHideDelay() Retrieves the current delay (in milliseconds) for hiding the right click target component.
java.lang.String	getToolTipText() Retrieves the tool tip text of this JTrayIcon.
boolean	hide() Hides this JTrayIcon.
void	hideLeftClickTarget() Hides the left click target Java component if it is visible.
void	hideRightClickTarget() Hides the right click target Java component if it is visible.
boolean	isAnimating() Is this JTrayIcon displaying animation?
boolean	isVisible() Is this JTrayIcon visible?
static void	releaseIcon(java.awt.Image i) Releases resources associated with this Image.
static void	releaseIcon(javax.swing.ImageIcon i) Releases resources associated with this ImageIcon.
static void	releaseIcon(java.lang.String filePath, int file_type) Releases resources associated with this icon.
static void	releaseIcon(java.lang.String filePath, int file_type, int index) Releases resources associated with this icon.
void	removeJTrayListener(JTrayListener jTrayListener) Removes a JTrayListener.
void	removeLeftClickTarget() Removes the left click target if one has been set.
void	removeNoHideComponent(java.awt.Component component) Removes a component that should not cause a right or left click target to hide when it is clicked.
void	removeRightClickTarget() Removes the right click target if one has been set.
void	resetIcon() Resets the icon displayed to the current icon set for this JTrayIcon.
boolean	setAnimation(IconAnimation iconAnimation) Specifies the IconAnimation to use for animation.
boolean	setAnimationFrameDelay(int frame_delay) Specifies the delay (in milliseconds) between showing animation frames.
boolean	setIcon(java.awt.Image i) Sets the icon to display with the specified Image as the icon.
boolean	setIcon(javax.swing.ImageIcon i) Sets the icon to display with the specified ImageIcon.
boolean	setIcon(java.lang.String filePath, int file_type) Sets the icon to display for this JTrayIcon.
boolean	setIcon(java.lang.String filePath, int file_type, int index) Sets the icon to display for this JTrayIcon.
boolean	setLeftClickTarget(java.awt.Component component) Sets the left click target component.
boolean	setLeftClickTarget(java.awt.Component component, boolean auto_hide) Sets the left click target component.
boolean	setLeftClickTarget(JTrayNativeMenu menu) Sets the left click target native popup menu.
void	setLeftHideDelay(int delay) Sets the delay (in milliseconds) for hiding the left click target component after it should be hidden.
static void	setRegistrationKey(java.lang.String key) When you purchase a registered version of JTray, you must programmatically specify your registration key by passing it to this method.
boolean	setRightClickTarget(java.awt.Component component) Sets the right click target component.
boolean	setRightClickTarget(java.awt.Component component, boolean auto_hide) Sets the right click target component.
boolean	setRightClickTarget(JTrayNativeMenu menu) Sets the right click target native popup menu.
void	setRightHideDelay(int delay) Sets the delay (in milliseconds) for hiding the right click target component after it should be hidden.
boolean	setToolTipText(java.lang.String toolTipText) Sets the tool tip text to be displayed for this JTrayIcon.
boolean	setVisible(boolean b) Shows or hides this JTrayIcon.
boolean	show() Shows this JTrayIcon.
boolean	showAnimationOnce() Shows an IconAnimation one time and then reverts to the last icon defined by setIcon or the icon defined in the constructor.
boolean	showAnimationOnce(int frame_delay) Shows an IconAnimation one time and then reverts to the last icon defined by setIcon or the icon defined in the constructor.
boolean	showBalloonMessage(java.lang.String title, java.lang.String text) Shows a balloon message at this JTrayIcon.
boolean	showBalloonMessage(java.lang.String title, java.lang.String text, int type) Shows a balloon message at this JTrayIcon.
boolean	startAnimation() Starts an animation with the previous frame delay set/used or the default frame delay.
boolean	startAnimation(int frame_delay) Starts an animation with the specified frame delay.
boolean	stopAnimation() Stops animation for this JTrayIcon if it is in progress.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JTrayIcon

public JTrayIcon(java.lang.String filePath,
                 int file_type)
          throws JTrayLibraryLoadFailedException

Constructs a JTrayIcon with the specified icon.

Parameters:

filePath - The file path to a file that contains an icon. (Such as "icons\\icon1.ico")

file_type - The type of the file. Types are listed in ImageFileType. set file_type to ImageFileType.ICO.

Throws:

JTrayLibraryLoadFailedException

JTrayIcon

public JTrayIcon(java.lang.String filePath,
                 int file_type,
                 int index)
          throws JTrayLibraryLoadFailedException

Constructs a JTrayIcon with the specified icon.

Parameters:

filePath - The file path to a file that contains an icon. (Such as "icons\\icon1.ico")

file_type - The type of the file. Types are listed in ImageFileType.

index - The index of the icon to use. DLLs and EXEs can contain multiple icons accessed by this index. To use this, set file_type to ImageFileType.ICO.

Throws:

JTrayLibraryLoadFailedException

JTrayIcon

public JTrayIcon(java.awt.Image i)
          throws JTrayLibraryLoadFailedException

Constructs a JTrayIcon with the specified Image as the icon.

The Image should have a 1:1 aspect ratio. Recommended image size is 32x32 or 16x16. Color limitations depend on the OS.

Parameters:

i - The image to display.

Throws:

JTrayLibraryLoadFailedException

JTrayIcon

public JTrayIcon(javax.swing.ImageIcon i)
          throws JTrayLibraryLoadFailedException

Constructs a JTrayIcon with the specified ImageIcon.

The ImageIcon should have a 1:1 aspect ratio. Recommended image size is 32x32 or 16x16. Color limitations depend on the OS.

Parameters:

i - The image to display.

Throws:

JTrayLibraryLoadFailedException

Method Detail

releaseIcon

public static void releaseIcon(javax.swing.ImageIcon i)

Releases resources associated with this ImageIcon.

To improve performance, JTray keeps references to icons used. If you use a great number of icons that won't get used again, you should release them with this method to free up memory resources.

This primarily is an issue for dynamic animation creation. If each icon shown is a dynamically created Image, the same Image won't be reused so you should release it after displaying it.

Parameters:

i - The ImageIcon to release.

releaseIcon

public static void releaseIcon(java.awt.Image i)

Releases resources associated with this Image.

To improve performance, JTray keeps references to icons used. If you use a great number of icons that won't get used again, you should release them with this method to free up memory resources.

This primarily is an issue for dynamic animation creation. If each icon shown is a dynamically created Image, the same Image won't be reused so you should release it after displaying it.

Parameters:

i - The Image to release.

releaseIcon

public static void releaseIcon(java.lang.String filePath,
                               int file_type,
                               int index)

Releases resources associated with this icon.

To improve performance, JTray keeps references to icons used. If you use a great number of icons that won't get used again, you should release them with this method to free up memory resources.

This primarily is an issue for dynamic animation creation. If each icon shown is a dynamically created Image, the same Image won't be reused so you should release it after displaying it.

Parameters:

filePath - The file path to a file that contains an icon. (Such as "icons\\icon1.ico")

file_type - The type of the file. Types are listed in ImageFileType.

index - The index of the icon to use. DLLs and EXEs can contain multiple icons accessed by this index. To use this, set file_type to ImageFileType.ICO.

releaseIcon

public static void releaseIcon(java.lang.String filePath,
                               int file_type)

Releases resources associated with this icon.

To improve performance, JTray keeps references to icons used. If you use a great number of icons that won't get used again, you should release them with this method to free up memory resources.

This primarily is an issue for dynamic animation creation. If each icon shown is a dynamically created Image, the same Image won't be reused so you should release it after displaying it.

Parameters:

filePath - The file path to a file that contains an icon. (Such as "icons\\icon1.gif")

file_type - The type of the file. Types are listed in ImageFileType.

setRegistrationKey

public static final void setRegistrationKey(java.lang.String key)

When you purchase a registered version of JTray, you must programmatically specify your registration key by passing it to this method.

This static method should be called before anything else is done with this API as follows:

 JTrayIcon.setRegistrationKey("AAAA-BBBB-CCCC-DDDD-EEEE-FFFF");
 

Parameters:

key - Registration Key

addJTrayListener

public void addJTrayListener(JTrayListener jTrayListener)

Adds a JTrayListener which will be notifed of mouse events for the JTrayIcon.

Parameters:

jTrayListener - The JTrayListener.

removeJTrayListener

public void removeJTrayListener(JTrayListener jTrayListener)

Removes a JTrayListener.

Parameters:

jTrayListener - The JTrayListener.

setAnimation

public boolean setAnimation(IconAnimation iconAnimation)

Specifies the IconAnimation to use for animation.

If an animation is in progress, it must be stopped before setting a different animation.

Parameters:

iconAnimation - The animation to display.

Returns:

true if successful, false otherwise. False will be returned if animation is already in progress.

resetIcon

public void resetIcon()

Resets the icon displayed to the current icon set for this JTrayIcon. This should be called after stopAnimation() to redisplay the appropriate icon.

isAnimating

public boolean isAnimating()

Is this JTrayIcon displaying animation?

Returns:

true if animation is in progress, false otherwise.

stopAnimation

public boolean stopAnimation()

Stops animation for this JTrayIcon if it is in progress.

Returns:

true if successful, false otherwise. False will be returned if there is no animation in progress.

setAnimationFrameDelay

public boolean setAnimationFrameDelay(int frame_delay)

Specifies the delay (in milliseconds) between showing animation frames.

The minimum pause is 30ms.

The default frame delay is 100ms.

Parameters:

frame_delay - The delay between animation frames.

Returns:

true if successful, false otherwise. False will be returned if frame_delay is less than 30.

showAnimationOnce

public boolean showAnimationOnce()

Shows an IconAnimation one time and then reverts to the last icon defined by setIcon or the icon defined in the constructor.

Returns:

true if successful, false otherwise. False will be returned if animation is currently in progress.

showAnimationOnce

public boolean showAnimationOnce(int frame_delay)

Shows an IconAnimation one time and then reverts to the last icon defined by setIcon or the icon defined in the constructor.

Parameters:

frame_delay - The delay between animation frames.

Returns:

true if successful, false otherwise. False will be returned if animation is currently in progress.

startAnimation

public boolean startAnimation()

Starts an animation with the previous frame delay set/used or the default frame delay.

The animation used must be specified with SetAnimation.

Returns:

true if successful, false otherwise. False will be returned if animation is already in progress, if no animation has been set, or if this JTrayIcon is not being shown.

startAnimation

public boolean startAnimation(int frame_delay)

Starts an animation with the specified frame delay.

The animation used must be specified with SetAnimation.

Parameters:

frame_delay - The frame delay for animation.

Returns:

true if successful, false otherwise. False will be returned if animation is already in progress, if no animation has been set, or if this JTrayIcon is not being shown.

showBalloonMessage

public boolean showBalloonMessage(java.lang.String title,
                                  java.lang.String text)

Shows a balloon message at this JTrayIcon.

Balloon messages can only be shown on Windows 2000 and Windows XP.

Parameters:

title - The title of the balloon message.

text - The text message of this balloon message.

Returns:

true if successful, false otherwise. False will be returned if this feature is not supported on the OS.

showBalloonMessage

public boolean showBalloonMessage(java.lang.String title,
                                  java.lang.String text,
                                  int type)

Shows a balloon message at this JTrayIcon.

Balloon messages can only be shown on Windows 2000 and Windows XP.

Parameters:

title - The title of the balloon message.

text - The text message of this balloon message.

type - The balloon type to display. Types are listed in the BalloonType class.

Returns:

true if successful, false otherwise. False will be returned if this feature is not supported on the OS.

setToolTipText

public boolean setToolTipText(java.lang.String toolTipText)

Sets the tool tip text to be displayed for this JTrayIcon.

Parameters:

toolTipText - The tool tip text to display.

Returns:

true if successful, false otherwise.

setIcon

public boolean setIcon(javax.swing.ImageIcon i)

Sets the icon to display with the specified ImageIcon.

The Image should have a 1:1 aspect ratio. Recommended image size is 32x32 or 16x16. Color limitations depend on the OS.

Parameters:

i - The image to display.

Returns:

true if successful, false otherwise.

Throws:

JTrayLibraryLoadFailedException

setIcon

public boolean setIcon(java.awt.Image i)

Sets the icon to display with the specified Image as the icon.

The Image should have a 1:1 aspect ratio. Recommended image size is 32x32 or 16x16. Color limitations depend on the OS.

Parameters:

i - The image to display.

Returns:

true if successful, false otherwise.

Throws:

JTrayLibraryLoadFailedException

setIcon

public boolean setIcon(java.lang.String filePath,
                       int file_type)

Sets the icon to display for this JTrayIcon. If this JTrayIcon is showing, this will change the icon displayed.

Parameters:

filePath - The file path to a file that contains an icon. (Such as "icons\\icon1.ico")

Returns:

true if successful, false otherwise.

setIcon

public boolean setIcon(java.lang.String filePath,
                       int file_type,
                       int index)

Sets the icon to display for this JTrayIcon. If this JTrayIcon is showing, this will change the icon displayed.

Parameters:

filePath - The file path to a file that contains an icon. (Such as "icons\\icon1.ico")

index - The index of the icon to use. DLLs and EXEs can contain multiple icons accessed by this index.

Returns:

true if successful, false otherwise.

setVisible

public boolean setVisible(boolean b)

Shows or hides this JTrayIcon.

Parameters:

b - Set true to show, set false to hide.

Returns:

true if successful, false otherwise.

show

public boolean show()

Shows this JTrayIcon. Same as setVisible(true)

Returns:

true if successful, false otherwise.

hide

public boolean hide()

Hides this JTrayIcon. Same as setVisible(false)

Returns:

true if successful, false otherwise.

isVisible

public boolean isVisible()

Is this JTrayIcon visible?

Returns:

true if visible, false otherwise.

removeLeftClickTarget

public void removeLeftClickTarget()

Removes the left click target if one has been set.

Left clicks on this JTrayIcon will no longer display the target that was set since this removes it.

removeRightClickTarget

public void removeRightClickTarget()

Removes the right click target if one has been set.

Right clicks on this JTrayIcon will no longer display the target that was set since this removes it.

setLeftClickTarget

public boolean setLeftClickTarget(java.awt.Component component)

Sets the left click target component. The component will be displayed when a left click on this JTrayIcon occurs.

If the component is a JPopupMenu or Window, it will display it as is. If the component is a MenuElement, a JPopupMenu is created and the MenuElement is added to it. Otherwise, a Window is created and the component is added to it. The window will set its size based on the preferred size of the component.

This component will auto hide when its clicked on or if something else is clicked on.

If the target is a Container and its contents change, you should recall this function to ensure proper behavior.

Parameters:

component - The component to display.

Returns:

true if successful, false otherwise.

setLeftClickTarget

public boolean setLeftClickTarget(java.awt.Component component,
                                  boolean auto_hide)

Sets the left click target component. The component will be displayed when a left click on this JTrayIcon occurs.

If the component is a JPopupMenu or Window, it will display it as is. If the component is a MenuElement, a JPopupMenu is created and the MenuElement is added to it. Otherwise, a Window is created and the component is added to it. The window will set its size based on the preferred size of the component.

Parameters:

component - The component to display.

This component will auto hide when its clicked on or if something else is clicked on.

If the target is a Container and its contents change, you should recall this function to ensure proper behavior.

auto_hide - If true, this component will hide when clicked on or if something else is clicked on. If false, this component will not disappear automatically. In that case, it should be hidden manually when required using hideLeftClickTarget().

Returns:

true if successful, false otherwise.

setRightClickTarget

public boolean setRightClickTarget(java.awt.Component component)

Sets the right click target component. The component will be displayed when a right click on this JTrayIcon occurs.

If the component is a JPopupMenu or Window, it will display it as is. If the component is a MenuElement, a JPopupMenu is created and the MenuElement is added to it. Otherwise, a Window is created and the component is added to it. The window will set its size based on the preferred size of the component.

This component will auto hide when its clicked on or if something else is clicked on.

If the target is a Container and its contents change, you should recall this function to ensure proper behavior.

Parameters:

component - The component to display.

Returns:

true if successful, false otherwise.

setRightClickTarget

public boolean setRightClickTarget(JTrayNativeMenu menu)

Sets the right click target native popup menu. This menu will be displayed when a right click on this JTrayIcon occurs.

Parameters:

menu - A JTrayNativeMenu to display

Returns:

true if successful, false otherwise

setLeftClickTarget

public boolean setLeftClickTarget(JTrayNativeMenu menu)

Sets the left click target native popup menu. This menu will be displayed when a left click on this JTrayIcon occurs.

Parameters:

menu - A JTrayNativeMenu to display

Returns:

true if successful, false otherwise

setRightClickTarget

public boolean setRightClickTarget(java.awt.Component component,
                                   boolean auto_hide)

Sets the right click target component. The component will be displayed when a right click on this JTrayIcon occurs.

If the component is a JPopupMenu or Window, it will display it as is. If the component is a MenuElement, a JPopupMenu is created and the MenuElement is added to it. Otherwise, a Window is created and the component is added to it. The window will set its size based on the preferred size of the component.

This component will auto hide when its clicked on or if something else is clicked on.

If the target is a Container and its contents change, you should recall this function to ensure proper behavior.

Parameters:

component - The component to display.

auto_hide - If true, this component will hide when clicked on or if something else is clicked on. If false, this component will not disappear automatically. In that case, it should be hidden manually when required using hideRightClickTarget().

Returns:

true if successful, false otherwise.

hideRightClickTarget

public void hideRightClickTarget()

Hides the right click target Java component if it is visible.

hideLeftClickTarget

public void hideLeftClickTarget()

Hides the left click target Java component if it is visible.

disableTargets

public static void disableTargets()

Disables both right and left click targets for all JTrayIcon instances.

Native popup menus cannot be disabled

enableTargets

public static void enableTargets()

Enables both right and left click targets for all JTrayIcon instances.

Native popup menus cannot be disabled

setRightHideDelay

public void setRightHideDelay(int delay)

Sets the delay (in milliseconds) for hiding the right click target component after it should be hidden.

The minimum and default delay time is 50ms.

This does not apply to native popup menus.

Parameters:

delay - The delay time.

setLeftHideDelay

public void setLeftHideDelay(int delay)

Sets the delay (in milliseconds) for hiding the left click target component after it should be hidden.

The minimum and default delay time is 50ms.

This does not apply to native popup menus.

Parameters:

delay - The delay time.

getRightHideDelay

public int getRightHideDelay()

Retrieves the current delay (in milliseconds) for hiding the right click target component.

This does not apply to native popup menus.

Returns:

The delay time.

getLeftHideDelay

public int getLeftHideDelay()

Retrieves the current delay (in milliseconds) for hiding the left click target component.

This does not apply to native popup menus.

Returns:

The delay time.

addNoHideComponent

public void addNoHideComponent(java.awt.Component component)

Specifies a component that should not cause a right or left click target to hide when it is clicked.

No hide components only work properly in JRE 1.4 or greater.

Parameters:

component - The no hide component.

removeNoHideComponent

public void removeNoHideComponent(java.awt.Component component)

Removes a component that should not cause a right or left click target to hide when it is clicked.

No hide components only work properly in JRE 1.4 or greater.

Parameters:

component - The no hide component.

getIconFilePath

public java.lang.String getIconFilePath()

Retrieves the file path for the icon file of this JTrayIcon if this icon was set with an icon with a file path.

Returns:

The file path. Returns null if this JTrayIcon was set with an Image or ImageIcon.

getIconImage

public java.awt.Image getIconImage()

Retrieves the Image of this JTrayIcon if this icon was set with an Image or ImageIcon.

Returns:

The Image. Returns null if this JTrayIcon was set with a file path.

getToolTipText

public java.lang.String getToolTipText()

Retrieves the tool tip text of this JTrayIcon.

Returns:

The tool tip text.