com.ccg.swing
Class ProgressMonitorUpdate

java.lang.Object
  com.ccg.swing.ProgressMonitorUpdate

All Implemented Interfaces:

Runnable

public class ProgressMonitorUpdate
extends Object
implements Runnable

Class to help safely update ProgressMonitor objects.

The Swing API does not allow any thread to update Swing components. Instead, all updates to Swing components need to be done within the Swing dispatch thread. This makes it somewhat difficult to have background tasks (which might take awhile) report their progress in Swing components. You can refer to the Swing tutorials on using the SwingUtilities.invokeLater(java.lang.Runnable) and using Timer classes and methods for more information on how you might do this by hand.

This class was designed to help one safely update a Swing ProgressMonitor from ANY thread which is running within the JVM. Use of this class boils down to the following:

• Initialize the object (by associating a ProgressMonitor.
• When needed, you can set new values for the current progress, text displayed, minimum value and maximum value.
• When you are ready to "safely" apply your updates, use the update() method, which will take care of applying the current values WITHOUT blocking your invoking thread.

The best way to use this class is to construct the object with an associated TagLookup object (which can easily be created from a associated resource bundle using the static getBundle methods and Resources.getTagLookup found in the Resources class (or use the getTagLookup method found in the RFrame class. If you construct the object in this fashion, you can then use the update method which does message lookup and text subsitution based on the resources.

Here is a quick example of how this might look in your program:

                                // Create/initialize the object
 java.util.ResourceBundle rb =
   Resources.getBundle(this.class);
 TagLookup tl = Resources.getTagLookup(rb,"pmu");

 ....

                                // update progress with new message
                                // from resource bundle
 Object args = { new java.util.Date() };
 pmu.update(10,"1",args[]);

 ...

                                // update progress only (not message)
 pmu.update(20,null,null);

 ...

                                // update progress only (no args)
 pmu.update(50,"2",null);

 ...
 

The associate resource bundle for the above would have lines like the following in it:

 pmu.label=Building the super object
 pmu.min=0
 pmu.max=100
 pmu.millisToDecideToPopup=500
 pmu.millisToPopup=1000
 # Initial message
 pmu.0=Initializing
 # Progess messages (use tag of "1", "2" in update)
 # Note that pmu.1 supports the MessageFormat#format(String,Object[]) method
 pmu.1=Starting build at {0}
 pmu.2=Halfway done!
 

The above properties would then be used to initialize the monitor object, and the defined messages: "pmu.1", "pmu.2", ... are then used during updates. To see a "working" example of this, refer to the MyClass.java example program and its corresponding msgs/MyClass.properties resource file.

It should be noted, that the value: Integer.MIN_VALUE is used to indicate that no change is required. You can not use this class if you need to support this value (which is very unlikely).

Since:

1.0

Version:

$Revision: 1.3 $

Author:

$Author: pkb $

See Also:

ProgressMonitor

Constructor Summary

ProgressMonitorUpdate()
Minimal constructor for the object.

ProgressMonitorUpdate(Component parent, TagLookup val)
Construct a progress monitoring object from a set of resources.

Method Summary

void	close() Closes the progress monitor object (and dissassociates).
int	getMaximum() Get the maximum value which will be reached when done.
int	getMinimum() Get the minimum value which the progress could be.
String	getNote() Get the "note" to assign to the associated ProgressMonitor.
int	getProgress() Get the current progress value which will be applied.
ProgressMonitor	getProgressMonitor() Get the ProgressMonitor object you want to update.
boolean	isCanceled() Has the user attempted to cancel the background task?
void	run() Do the actual update of the associated ProgressMonitor.
void	setMaximum(int val) Set the maximum value which will be reached when done.
void	setMinimum(int val) Set the minimum value which the progress could be.
void	setNote(String val) Set the "note" to assign to the associated ProgressMonitor.
void	setProgress(int val) Set the progress value which will be applied at the next update.
void	setProgressMonitor(ProgressMonitor val) Set the ProgressMonitor object you want to update.
void	update() Go ahead and safely apply any changes to the monitor.
void	update(int progress, String text) Safely update the progress monitor's status.
void	update(int progress, String tag, Object[] args) Safely update the progress monitor's status using resources.

Methods inherited from class java.lang.Object

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

Constructor Detail

ProgressMonitorUpdate

public ProgressMonitorUpdate()

Minimal constructor for the object.

If you construct the object in this fashion, you will need to set the ProgressMonitor object to be associated before you can update progress information.

Since:

1.0

See Also:

ProgressMonitorUpdate(Component,TagLookup)

ProgressMonitorUpdate

public ProgressMonitorUpdate(Component parent,
                             TagLookup val)

Construct a progress monitoring object from a set of resources.

You can use this method to associate resource bundles with the progress as it is reported. This allows one to simplify the process of localizing their progress messages. This constructor will create a new ProgressMonitor object and assign it to this object for future updates.

If you construct the object in this fashion, you can then use the resource update method for updating progress information.

We use the following properties from the TagLookup object passed (all are optional):

.label=TEXT

This is the static text that will remain constant (never changes as the progress monitor is displayed to the user). You won't like the default value - so please specify one.

.min=INT

This is the minimum value of the progress monitor at time of construction (it can be adjusted later via its "set" method. If omitted, it defaults to 0.

.max=INT

This is the maximum value of the progress monitor at time of construction (it can be adjusted later via its "set" method. If omitted, it defaults to 100.

.millisToDecideToPopup=INT

This is how long we should wait (in milliseconds) to decide if a popup progress window is needed. If omitted, we won't explicitly set this value in the ProgressMonitor object (which results in the Swing default setting for the object).

.millisToPopup

This is how long we should wait (in milliseconds) after deciding that that we need to pop-up a progress window before we actually display the progress window. If omitted, we won't explicitly set this value in the ProgressMonitor object (which results in the Swing default setting for the object).

.0=TEXT

Initial "note" to be displayed. Defaults to the zero length string so that notes could appear later.

Parameters:

parent - The parent Component which will own the monitor object - must not be null.

val - New TagLookup value to assign (null is allowed - but we will then just behave like the normal constructor).

See Also:

update(int,String,Object[])

Method Detail

setProgressMonitor

public void setProgressMonitor(ProgressMonitor val)

Set the ProgressMonitor object you want to update.

Parameters:

val - New ProgressMonitor value to assign.

See Also:

getProgressMonitor()

getProgressMonitor

public ProgressMonitor getProgressMonitor()

Get the ProgressMonitor object you want to update.

Returns:

Current ProgressMonitor value assigned.

See Also:

setProgressMonitor(javax.swing.ProgressMonitor)

update

public void update()

Go ahead and safely apply any changes to the monitor.

This method will use the SwingUtilities.invokeLater(java.lang.Runnable) method to apply any changes you have set to the associated ProgressMonitor object. This is done in a thread safe manner (the updates aren't immediate, but as soon as the Swing API deems it OK to do). This method returns immediately (it won't block the invoker).

If you never set a ProgressMonitor object, then nothing will be done.

Since:

1.0

See Also:

run()

update

public void update(int progress,
                   String text)

Safely update the progress monitor's status.

This is a convenience method which updates the amount of progress made, optionally updates the progress text and then safely updates the progress panel (you can invoke this from any thread).

Parameters:

progress - The current progress made (should be in the range of getMinimum() and #getMaximum()

text - If you would like to update the text, pass a non-null value here

Since:

1.0

See Also:

update(), setProgress(int), setNote(java.lang.String)

update

public void update(int progress,
                   String tag,
                   Object[] args)

Safely update the progress monitor's status using resources.

This is a convenience method which updates the amount of progress made, optionally updates the progress text and then safely updates the progress panel (you can invoke this from any thread). This method should only be used if you constructed the object with an associate TagLookup object where it pulls its message resources from.

This method will still work (won't error) if you did not construct the object in this fashion - however it will only update the progress bar (not the text)

Parameters:

progress - The current progress made (should be in the range of getMinimum() and #getMaximum()

tag - The tag identifier of the message in the associated TagLookup object (typically with a leading period, like ".1", ".almostDone", etc). Note, if this value isn't found in your resource's, we'll just clear the "note" area.

args - Optional set of arguments which will be subsituted into the message (you can pass null if the message doesn't support arguments). This allows one to use the MessageFormat type subsitutions on the note displayed.

Since:

1.0

See Also:

ProgressMonitorUpdate(Component,TagLookup), update(), setProgress(int), setNote(java.lang.String)

run

public void run()

Do the actual update of the associated ProgressMonitor.

This method transfers any of the 'set' values to the associated ProgressMonitor object. This method MUST be invoked within the Swing event dispatching thread. Typically one doesn't use this method directly, but indirectly via the "update" methods (which can be safely used by any thread).

Specified by:

run in interface Runnable

Since:

1.0

See Also:

update(), update(int,String)

setMaximum

public void setMaximum(int val)

Set the maximum value which will be reached when done.

Note, the value will not be applied until run is invoked. Values less than 0 will not be applied (won't update the associated ProgressMonitor.

Parameters:

val - New int value to assign.

See Also:

getMaximum(), ProgressMonitor.setMaximum(int)

getMaximum

public int getMaximum()

Get the maximum value which will be reached when done.

Returns:

Current int value assigned - returns Integer.MIN_VALUE if no change.

See Also:

setMaximum(int), ProgressMonitor.getMaximum()

setMinimum

public void setMinimum(int val)

Set the minimum value which the progress could be.

Note, the value will not be applied until run is invoked. Values less than 0 will not be applied (won't update the associated ProgressMonitor.

Parameters:

val - New int value to assign.

See Also:

getMinimum(), ProgressMonitor.setMinimum(int)

getMinimum

public int getMinimum()

Get the minimum value which the progress could be.

Returns:

Current int value assigned - returns Integer.MIN_VALUE if no change.

See Also:

setMinimum(int), ProgressMonitor.getMinimum()

setProgress

public void setProgress(int val)

Set the progress value which will be applied at the next update.

Note, the value will not be applied until run is invoked. Values less than 0 will not be applied (won't update the associated ProgressMonitor.

Parameters:

val - New int value to assign.

See Also:

getProgress(), ProgressMonitor.setProgress(int)

getProgress

public int getProgress()

Get the current progress value which will be applied.

Returns:

Current int value assigned - returns Integer.MIN_VALUE if no change.

See Also:

setProgress(int)

setNote

public void setNote(String val)

Set the "note" to assign to the associated ProgressMonitor.

Note, the value will not be applied until run is invoked.

Parameters:

val - New text value to display in the progress window (null is OK - we just don't do anything with it).

See Also:

getNote(), ProgressMonitor.setNote(java.lang.String)

getNote

public String getNote()

Get the "note" to assign to the associated ProgressMonitor.

Returns:

The pending text to be applied, or null if no change since last text was applied.

See Also:

setNote(java.lang.String), ProgressMonitor.getNote()

isCanceled

public boolean isCanceled()

Has the user attempted to cancel the background task?

Returns:

true if the "Cancel" button was pressed

Since:

1.0

See Also:

ProgressMonitor.isCanceled()

close

public void close()

Closes the progress monitor object (and dissassociates).

Since:

1.0

See Also:

isCanceled()