com.klg.jclass.util.swing
Class JCProgressHelper

java.lang.Object
  |
  +--com.klg.jclass.util.swing.JCProgressHelper

public class JCProgressHelper

extends Object

This is a class for creating and managing a progress dialog in a Thread-safe manner. An instance of this class monitors the progress of some operation.

Call startProgress() when you want to start the progress meter. The two parameters, popupTime and decideTime, give you complete control over when the dialog appears. Call updateProgress() whenever you want to update the progress meter.

Normally, decideTime is less than popupTime. If the progress monitor is not yet being displayed, a call to updateProgress() causes the progress meter to compare the decideTime property (default 500 ms, or set using setTimeToDecideToPopup()) to the elapsesd time since the monitor was started. If the elapsed time is greater than decideTime, the progress monitor predicts how long the entire operation will take. If it is longer than popupTime (default: 2 seconds, or set with setTimeToPopup()), a JCProgressHelper will be popped up.

To force the dialog to appear, set popupTimeto 0.

Before the progress is started the JCProgressHelper should be given a numeric range and a descriptive String, either by setting them in the constructor or by calling the appropriate methods. As the operation progresses, call the updateProgress() method periodically to indicate how far along the [min, max] range the operation is.

Field Summary

protected String	cancelString
protected long	decideTime
protected JDialog	dialog
protected String	dialogTitle
protected String	dynamicMessage
protected JLabel	dynamicMessageLabel
protected boolean	firstPass
protected boolean	isDismissable
protected boolean	isModal
protected int	max
protected int	min
protected JOptionPane	optionPane
protected Component	parent
protected boolean	popupInitiated
protected long	popupTime
protected JProgressBar	progressbar
protected com.klg.jclass.util.JCListenerList	progressCancelledListeners
protected boolean	progressComplete
protected boolean	showDynamicMessage
protected long	startTime
protected String	staticMessage
protected String	staticMessageLabel
protected int	value

Constructor Summary

JCProgressHelper(Component parent)
Creates a JCProgressHelper with default characteristics.

JCProgressHelper(Component parent, String static_message, int min, int max)
Creates a JCProgressHelper with default characteristics.

JCProgressHelper(Component parent, String static_message, int min, int max, boolean show_dynamic_message, boolean is_modal, boolean is_dismissable)
Creates a JCProgressHelper with no default settings.

Method Summary

void	addProgressCancelledListener(com.klg.jclass.util.progress.JCProgressCancelledListener l) Convenience method for adding a JCProgressCancelledListener.
void	completeProgress() Closes and disposes the JCProgressHelper.
com.klg.jclass.util.progress.JCProgressListener	createProgressListener() Returns a listener that uses this JCProgressHelper that is suitable for attaching to any Bean that implements an addProgressListener(JCProgressListener) method.
protected void	fireUserCancelledProgressEvent(com.klg.jclass.util.progress.JCProgressCancelledEvent event) Fires an event to tell interested listeners that the user has cancelled progress.
String	getCancelString() Returns the String which displays in the dialog's cancel button.
String	getDialogTitle() Returns the String which displays in the dialog's title bar.
boolean	isOkayToContinue() Returns true as long as the user has not cancelled the progress by hitting the cancel button in the OptionPane.
protected void	popupDialog() Called internally, creates and displays the dialog.
void	removeProgressCancelledListener(com.klg.jclass.util.progress.JCProgressCancelledListener l) Convenience method for removing a JCProgressCancelledListener.
void	setCancelString(String cancelString) Sets the String which displays in the dialog's cancel button.
void	setDialogTitle(String dialogTitle) Sets the String which displays in the dialog's title bar.
void	setDynamicMessage(String dynamic_message) Sets the dynamicMessage property.
void	setMaximum(int max) Sets the max property.
void	setMinimum(int min) Sets the min property.
void	setRange(int min, int max) Sets the min and max properties.
void	setStaticMessage(String message) Sets the staticMessage property.
void	setTimeToDecideToPopup(long time) Sets the decideTime property.
void	setTimeToPopup(long time) Sets the popupTime property.
void	startProgress() Starts the progress meter.
void	updateProgress(int new_value) Updates the value in the progress bar.

Methods inherited from class java.lang.Object

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

Field Detail

parent

protected Component parent

staticMessage

protected String staticMessage

dynamicMessage

protected String dynamicMessage

dialogTitle

protected String dialogTitle

cancelString

protected String cancelString

progressbar

protected JProgressBar progressbar

dialog

protected JDialog dialog

staticMessageLabel

protected String staticMessageLabel

optionPane

protected JOptionPane optionPane

dynamicMessageLabel

protected JLabel dynamicMessageLabel

isModal

protected boolean isModal

isDismissable

protected boolean isDismissable

showDynamicMessage

protected boolean showDynamicMessage

max

protected int max

min

protected int min

value

protected int value

decideTime

protected long decideTime

popupTime

protected long popupTime

startTime

protected long startTime

popupInitiated

protected boolean popupInitiated

progressComplete

protected boolean progressComplete

firstPass

protected boolean firstPass

progressCancelledListeners

protected com.klg.jclass.util.JCListenerList progressCancelledListeners

Constructor Detail

JCProgressHelper

public JCProgressHelper(Component parent)

Creates a JCProgressHelper with default characteristics.

Defaults:

 static_message = null
 min = 0
 max = 0
 show_dynamic_message = true
 is_modal = false
 is_dismissable = false
 

Parameters:

parent - the Component that is the parent of the JCProgressHelper

JCProgressHelper

public JCProgressHelper(Component parent,
                        String static_message,
                        int min,
                        int max)

Creates a JCProgressHelper with default characteristics.

Defaults:

 show_dynamic_message = true
 is_modal = false
 is_dismissable = false
 

Parameters:

parent - the Component that is the parent of the JCProgressHelper

static_message - the String that is the text of the message shown

min - the int denoting the minimum value of the ProgressBar

max - the int denoting the maximum value of the ProgressBar

JCProgressHelper

public JCProgressHelper(Component parent,
                        String static_message,
                        int min,
                        int max,
                        boolean show_dynamic_message,
                        boolean is_modal,
                        boolean is_dismissable)

Creates a JCProgressHelper with no default settings. All settings are set using the arguments passed to this constructor.

Parameters:

parent - the Component that is the parent of the JCProgressHelper

static_message - the String that is the text of the message shown in the progress bar

min - the int that is the minimum value of the ProgressBar

max - the int that is the maximum value of the ProgressBar

show_dynamic_message - the boolean that tells JCProgressHelper whether or not to display dynamic messages

is_modal - the boolean that tells JCProgressHelper whether it is modal

is_dismissable - the boolean that tells JCProgressHelper whether or not the user can cancel it

Method Detail

startProgress

public void startProgress()

Starts the progress meter. The initial length of the bar, showing the amount completed, is determined from the proportion (value - min) / (max - min).
If value = min, the progress bar shows 0% complete.

addProgressCancelledListener

public void addProgressCancelledListener(com.klg.jclass.util.progress.JCProgressCancelledListener l)

Convenience method for adding a JCProgressCancelledListener.

Parameters:

l - JCProgressCancelledListener

removeProgressCancelledListener

public void removeProgressCancelledListener(com.klg.jclass.util.progress.JCProgressCancelledListener l)

Convenience method for removing a JCProgressCancelledListener.

Parameters:

l - JCProgressCancelledListener

fireUserCancelledProgressEvent

protected void fireUserCancelledProgressEvent(com.klg.jclass.util.progress.JCProgressCancelledEvent event)

Fires an event to tell interested listeners that the user has cancelled progress.

Parameters:

event - JCProgressCancelledEvent

popupDialog

protected void popupDialog()

Called internally, creates and displays the dialog.

setTimeToDecideToPopup

public void setTimeToDecideToPopup(long time)

Sets the decideTime property.

Parameters:

time - the long value that is compared to the popupTime to determine whether or not to pop up the dialog

setTimeToPopup

public void setTimeToPopup(long time)

Sets the popupTime property. If this value is <1, the thread which pauses popping up the dialog in startProgress() is never called, and the dialog pops up immediately.

Parameters:

time - the long value that gives the operation a metric for deciding whether or not the JCProgressHelper is required.

setStaticMessage

public void setStaticMessage(String message)

Sets the staticMessage property. In the dialog, two areas are reserved for message lines. The static message is on the upper line.

Parameters:

message - the String that is displayed throughout the life of the JCProgressHelper

getDialogTitle

public String getDialogTitle()

Returns the String which displays in the dialog's title bar.

Returns:

dialogTitle the String that shows in the title bar of the dialog

setDialogTitle

public void setDialogTitle(String dialogTitle)

Sets the String which displays in the dialog's title bar. The default is "Progress..."

Parameters:

dialogTitle - the String that shows in the title bar of the dialog

getCancelString

public String getCancelString()

Returns the String which displays in the dialog's cancel button.

Returns:

dialogTitle the String that shows in the title bar of the dialog

setCancelString

public void setCancelString(String cancelString)

Sets the String which displays in the dialog's cancel button. The default is "Cancel".

Parameters:

cancelString -

setMaximum

public void setMaximum(int max)

Sets the max property. This variable represents the highest value that may be passed to updateProgess().

Parameters:

max - the int that is the maximum value of the progress bar

setMinimum

public void setMinimum(int min)

Sets the min property. This is the value used to indicate the proportion of the task that has been completed when the progress meter first pops up. Typically, this value is zero.

Parameters:

min - the int that is the minimum value of the progress bar

setRange

public void setRange(int min,
                     int max)

Sets the min and max properties.

Parameters:

min - the int that is the minimum value of the progress bar

max - the int that is the maximum value of the progress bar

updateProgress

public void updateProgress(int new_value)

Updates the value in the progress bar.

Parameters:

new_value - the int that is the new value displayed in the progress bar as a length

completeProgress

public void completeProgress()

Closes and disposes the JCProgressHelper.

isOkayToContinue

public boolean isOkayToContinue()

Returns true as long as the user has not cancelled the progress by hitting the cancel button in the OptionPane.

Returns:

the boolean representing whether or not the user has cancelled the dialog

setDynamicMessage

public void setDynamicMessage(String dynamic_message)

Sets the dynamicMessage property. Dynamic messages are the ones which show up just above the progress bar and just below the static message, usually containing text information on the current progress of the operation, such as naming the sub-task currently being performed.

Parameters:

dynamic_message - the String that announces what the status of the operation is

createProgressListener

public com.klg.jclass.util.progress.JCProgressListener createProgressListener()

Returns a listener that uses this JCProgressHelper that is suitable for attaching to any Bean that implements an addProgressListener(JCProgressListener) method.

Returns:

listener that uses this JCProgressHelper

See Also:

JCProgressListener