23

Progress Helper

Features of JCProgressHelper  Constructors and Associated Classes

JCProgressHelper Methods  Examples

---

23.1 Features of JCProgressHelper

JCProgressHelper is a class that lets you create and manage a thread-safe progress dialog. With it, you can monitor some potentially time-consuming operation and present a visual indication of its progress. If it looks like the operation will take some time, a progress dialog appears. Before the operation is started the JCProgressHelper should be given a numeric range and a descriptive String. Initially, there is no JProgressBar. As the operation progresses, call the updateProgress() method to indicate how far along the [min .. max] range the operation is. After the first timeToDecideToPopup milliseconds (default 500) the progress monitor will predict how long the operation will take. If it is longer than timeToPopup (default 2 seconds) a JProgressBar is popped up.

Figure 56 :  A JCProgressHelper showing the methods used for labelling.

The advantages of JCProgressHelper include:

• You are able to quantify the process that the JCProgressHelper is monitoring by setting two integers representing a minimum and a maximum of some value that proportionately measures the progress of some time-consuming operation. As the process continues, you call updateProgress() with a parameter indicating how far along things are.
• The progress helper transforms all your calls to it into Thread-safe calls to the parent Swing component to encourage frequent updating.
• A descriptive, dynamically updatable, message informs users about the progress of the operation.
• The progress dialog contains a Cancel button, permitting the end-user to terminate long-running processes.
• The progress dialog waits for a time that you set in setTimeToDecideToPopup() before checking whether to pop up, and does not pop up at all unless the operation is projected to take at least a minimum time, which you may set also, in setPopupTime().

---

23.2 Constructors and Associated Classes

23.2.1 Constructors

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

The parameters in the constructors are:

parent	The object whose computations are to be monitored.
min, max	Integer parameters that represent a time scale for the operation. The progress bar is scaled between these values. Thus, if min = 40 and max = 90, and the current value is 50, then (50 - 40)/(90 - 40) = 1/5, and 1/5, that is 20%, of the length of the progress bar is shaded.
static_message	The first message line. This message cannot be changed once the dialog has popped up.
show_dynamic   _message	The changeable part of the message in the line below the static message of the progress dialog can be turned on and off using this Boolean parameter.
is_modal	If true, the progress dialog must remain the active window.
is_dismissable	If false, the user cannot cancel the computation that this progress meter is monitoring.

23.2.2 Associated Classes

Following is a list of the JCProgressHelper associated classes:

JCProgressEvent	JCProgressEvent is used to monitor the status of a process. The event contains information about the process name, the current unit being processed, and the total unit count for the process. The setAbort() method allows the listener to abort the process, and the isAborted() method checks to see if the process is aborted.
JCProgress   Listener	The listener interface that may be used for processes which are to be monitored by a progress bar. Methods are: processingBegin(), invoked when a process has begun, processingEnd(), invoked when the process has been compeleted, processingError(), invoked when a process encounters an error, and processingUnit(), invoked when a process unit has been completed.
JCProgress   CancelledEvent	JCProgressCancelledEvent is used to notify interested listeners when the user has cancelled progress via the Cancel button on the JCProgressHelper.
JCProgress   CancelledListener	The listener interface which is used to detect a user-cancellation action in the JCProgressHelper.   JCProgressCancelledEvent is fired when the user has cancelled progress via the Cancel button on the JCProgressHelper. Implementations of this interface may detect the cancellation in their application and react to it.
JCProgressHelper	The progress monitor itself.
JCProgress   AbortedException	Used to create an exception that tells the process that it should exit.
JCProgressAdapter	An abstract class that acts as an adapter. It provides null implementations of all the methods defined in JCProgressListener.

23.2.3 Using the Event and Listener Classes

Depending on your needs, there are four ways to use the progress mechanism:

• Use the JCProgressHelper GUI and let it handle all updates without any need to invoke events and listeners in your code. In this case, you call startProgress() and updateProgress() to control the progress bar. See examples.elements.BasicProgressHelperExample.java in the JCLASS_HOME/examples/elements directory.
• Use createProgressListener() to have JCProgressHelper manage events internally. In this case, you call listener methods like processingBegin() and processingUnit(), which are implemented by the progress meter itself. You don't have to supply the code.
• Create your own addProgressListener() method and have it register JCProgressListeners. This option gives you the most control. You'll need to have one of your classes implement JCProgressListener, or you can extend JCProgressAdapter. You override the listener methods you need, and you will have to provide implementations of addProgressListener(JCProgressListener), removeProgressListener(JCProgressListener), and fireProgressEvent(JCProgressEvent) in the class that wishes to control the progress meter. See ProgressListenerExample.java in the JCLASS_HOME/examples/elements directory.
• Use an implementation of JCProgressCancelledListener to handle what must be done if the end user clicks the JCProgressHelper's Cancel button. A JCProgressCancelledEvent is sent to all JCProgressCancelledListeners when this button is clicked. If you use this listener your application is notified immediately when the Cancel button has been clicked, rather than having to wait until processingUnit() is called from JCProgressListener.

---

23.3 JCProgressHelper Methods

completeProgress()	Call this method when your computation has finished to allow for cleanup.
isOkayToContinue()	Is false if the user has pressed the Cancel button. You can use it in your code to force a cancellation of the computation.
setDynamicMessage()	The changeable part of the progress meter's message.
setCancelString	Sets the String in the Cancel button. Default is "Cancel".
setDialogTitle	Sets the String in the dialog's title bar. Default is "Progress..."
setMaximum()	You model the duration of a process by inventing an integer range min .. max. Choose the range so that it is easy to calculate the integer that represents your computation's degree of completion. Set the maximum-time integer using this method.
setMinimum()	Use this method to set the minimum-time integer.
setRange()	A convenience method that combines setMinimum and setMaximum.
setStaticMessage()	Use this method to define the unchanging part of the progress meter's message.
setTimeToDecideTo   Popup()	The progress meter waits until this time before attempting to predict how long the process it is monitoring will take. It then uses the time set in setTimeToPopup() to decide whether to pop up at all.
setTimeToPopup()	The progress meter won't pop up if the progress meter's calculation estimates that the process will take less time than the time you set here. The default is 500 ms.
startProgress()	Call this method within your object to inform the progress meter that timing has begun.
updateProgress()	Call this method with a integer parameter that represents your computation's degree of completion.

---

23.4 Examples

Add a JCProgressHelper to your component as follows:

JCProgressHelper jpr = new JCProgressHelper(eFrame, "Here is a progress message", 0, 10, true, true, true);

Set a time which it is unnecessary to display a progress meter and call setPopupTime() with this value. Decide when you want the progress helper to calculate its estimation of the monitored process' completion time and call setTimeToDecideToPopup() with this time. This time should be long enough that the tracking variable is no longer at its minimum value, so that the progress meter has a way of estimating how long the operation will take to complete.

Call the updateProgress() method periodically to update the tracking variable:

jpr.updateProgress(5); // Progress indicator is half-way along

When the process has completed, call completeProgress() to remove the dialog.

A full example

The following code causes a progress dialog to appear. It sets both a static message and a dynamic message that is changed every time the progress bar is updated. Since the dialog is managed in an AWT thread, you may have to make sure that it is given a chance to run, especially if you wish to perform some initialization of the progress dialog in the mainline thread and you wish it to appear in the dialog.

import javax.swing.*;
import com.klg.jclass.util.swing.JCProgressHelper;

public class ProgressHelper extends JFrame {

// Use the constructor that permits setting a static message
public ProgressHelper() {
JCProgressHelper jpr = new JCProgressHelper(this, "Here is a static progress message", 0, 100, true, true, false);
// Pop up the progress dialog.
// There will be a delay, determined in part
// by the two popup time parameters.
jpr.startProgress();
for (int j = 1; j < 11; j++){
// Simulate an ongoing process ...
try {
Thread.sleep(1000);
} catch (Exception e) {
}
// ... and update the progress meter periodically,
jpr.updateProgress(j*10);
// changing the dynamic message as the meter updates.
jpr.setDynamicMessage("Dynamic "+ j*10);
}
// Dispose of the progress meter
jpr.completeProgress();
// The mainline program can continue as required...
// ... until its tasks are completed.
System.exit(0);
}

public static void main(String[] args) {
ProgressHelper ph = new ProgressHelper();
}
}