com.ccg.swing
Class UpdateSafely

java.lang.Object
  com.ccg.swing.UpdateSafely

All Implemented Interfaces:

Runnable

public class UpdateSafely
extends Object
implements Runnable

Class to make the updating of Swing components safe.

Swing components can not be freely modified by any thread running within a JVM. For example, this means that if one tries to update the text of a component from a thread which is external to the main Swing event dispatching thread, unpredictable things may occur.

The SwingUtilities class provides a set of methods to make the updating of swing components safe for any thread. This class attempts to encapsulate these features into something which is a little easier (more convienent) to work with. You use this class in the following manner:

• Construct the class.
• Add one or more JComponent objects to it.
• Set the properties you would like to adjust on the component.
• Invoke the "smartUpdate()" method to safely update the component(s) with your new properties.

Since:

1.0

Version:

$Revision: 1.2 $

Author:

$Author: pkb $

See Also:

SwingUtilities, Grouping

Constructor Summary

UpdateSafely()
Default constructor.

UpdateSafely(Object o)
Constructor for a single component.

Method Summary

Color	getBackground() Get the background color to apply to the components.
Boolean	getEnabled() Get whether the component should be enabled or disabled.
Color	getForeground() Get the foreground color to apply to the components.
Boolean	getSelected() Get whether the components should be selected or not.
String	getText() Get the new value for the label field.
boolean	isAutoPropertyClearEnabled() Should properties be automatically cleared after updating?
void	run() Method which updates the component(s) in the background.
void	setAutoPropertyClearEnabled(boolean val) Set should we clear propertries after updating.
void	setBackground(Color val) Set the background color to apply to the components.
void	setEnabled(Boolean val) Set whether the component should be enabled or disabled.
void	setForeground(Color val) Set the foreground color to apply to the components.
void	setSelected(Boolean val) Set whether the components should be selected or not.
void	setText(String val) Set the new value for the label field.
void	smartAdd(Object o) Add more component(s) to the set we can update.
void	smartUpdate() The "non-static" version of "smart update".
static void	smartUpdateJLabel(JLabel label, String val) The "thread safe" way to change the value of a GUI label.

Methods inherited from class java.lang.Object

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

Constructor Detail

UpdateSafely

public UpdateSafely()

Default constructor.

You'll want to use the "add"/"set" methods after creating a object in this fashion.

Since:

1.0

UpdateSafely

public UpdateSafely(Object o)

Constructor for a single component.

Constructs the object and does a "smart add" of the object(s) which you specify.

Parameters:

o - Typically a JComponent, but it can be any object supported by the Grouping.smartAdd(object) method.

Since:

1.0

Method Detail

smartAdd

public void smartAdd(Object o)

Add more component(s) to the set we can update.

This method allows one to add more component(s) to the group of components which we allow you to update on the fly.

Parameters:

o - Typically a JComponent, but it can be any object supported by the Grouping.smartAdd(object) method.

Since:

1.0

smartUpdateJLabel

public static void smartUpdateJLabel(JLabel label,
                                     String val)

The "thread safe" way to change the value of a GUI label.

This static method will "safely" update the text of a JLabel component regardless of whether you invoke it from the Swing event dispatching thread or not.

This method determines if the invoking thread is the Swing event dispatching thread or some external thread. If it is within the main Swing event thread, we will simply update the label immediately. If not, we will create a new UpdateSafely object and pass it to the invokeLater(Runnable) method so that the update can occur at a "safe" time in the Swing universe.

Parameters:

label - The label component to update. You can pass null, but we won't do anything.

val - The value to assign to the label. You can pass null and we will clear the contents of the label (same as passing "").

Since:

1.0

See Also:

smartUpdate()

smartUpdate

public void smartUpdate()

The "non-static" version of "smart update".

This is similar to the static version of the "smartUpdate()" method. This method updates the contents of the associated label in a "safe" manner regardless of what JVM thread you invoke it from (it makes use of the invokeLater(Runnable) method if necessary).

Since:

1.0

See Also:

smartUpdateJLabel(JLabel,String)

run

public void run()

Method which updates the component(s) in the background.

This method is intended to be run at a later time by the Swing event dispatcher thread (when it is safe to change the value(s) of the component(s)).

If there are any component(s) set, the following will be done:

• The component(s) will be enabled or disabled if a non-null value has been specified.
• The component(s) will be put in a selected or unselected state (when applicable) if a non-null value has been specified.
• The text value of the component(s) (when applicable) will be set if a non-null value has been specified.
• The foreground color of the component(s) will be set if a non-null value has been specified.
• The background color of the component(s) will be set if a non-null value has been specified.

After the updates have been applied to the component(s), the current settings will be cleared from this object UNLESS you explicitly tell the object to keep the properties applied (via the setAutoPropertyClearEnabled(boolean) method).

NOTE: This method should never be invoked directly (unless you know you are within the Swing event dispatching thread). Instead, either use the smartUpdate() method which will safely invoke this method, or pass the entire object to SwingUtilities.invokeLater(java.lang.Runnable) method.

Specified by:

run in interface Runnable

Since:

1.0

See Also:

smartUpdate()

setText

public void setText(String val)

Set the new value for the label field.

Parameters:

val - New String value to assign.

See Also:

getText()

getText

public String getText()

Get the new value for the label field.

Returns:

Current String value assigned - never returns null - will return "" if null value assigned.

See Also:

setText(java.lang.String)

setAutoPropertyClearEnabled

public void setAutoPropertyClearEnabled(boolean val)

Set should we clear propertries after updating.

By default, the properites which you set (such as text, colors, enabled, etc) are cleared once we apply them to the components. This is typically the desired behavior. If you would like this object to retain its property settings AFTER they have been applied, then you need to set the value to false.

Parameters:

val - New boolean value to assign.

See Also:

isAutoPropertyClearEnabled()

isAutoPropertyClearEnabled

public boolean isAutoPropertyClearEnabled()

Should properties be automatically cleared after updating?

Returns:

Current boolean value assigned.

See Also:

setAutoPropertyClearEnabled(boolean)

setForeground

public void setForeground(Color val)

Set the foreground color to apply to the components.

Parameters:

val - New Color value to assign or null if you don't want to change the color.

See Also:

getForeground()

getForeground

public Color getForeground()

Get the foreground color to apply to the components.

Returns:

Current Color value assigned.

See Also:

setForeground(java.awt.Color)

setBackground

public void setBackground(Color val)

Set the background color to apply to the components.

Parameters:

val - New Color value to assign or null if you don't want to change the color.

See Also:

getBackground()

getBackground

public Color getBackground()

Get the background color to apply to the components.

Returns:

Current Color value assigned.

See Also:

setBackground(java.awt.Color)

setEnabled

public void setEnabled(Boolean val)

Set whether the component should be enabled or disabled.

Parameters:

val - Boolean object which indicates whether to enable or disable the components (or null if you don't want to change the enable/disable state).

See Also:

getEnabled()

getEnabled

public Boolean getEnabled()

Get whether the component should be enabled or disabled.

Returns:

Current Boolean value assigned.

See Also:

setEnabled(java.lang.Boolean)

setSelected

public void setSelected(Boolean val)

Set whether the components should be selected or not.

Parameters:

val - Boolean object to use to set the selected state of the components, OR null if you don't want to change the selected state.

See Also:

getSelected()

getSelected

public Boolean getSelected()

Get whether the components should be selected or not.

Returns:

Current Boolean value assigned.

See Also:

setSelected(java.lang.Boolean)