Previous | Next | Trail Map | Creating a User Interface (with Swing) | Using the JFC/Swing Packages

How to Monitor Progress

A task running within a program might take a while to complete. A user-friendly program provides some indication to the user about how long the task might take and how much work has already been done.

The Swing package provides three classes to help you create GUIs that monitor and display the progress of a long-running task:

JProgressBar(in the API reference documentation)
A progress bar graphically displays how much of the total task has completed. See How to Use Progress Bars for information and an example of using a progress bar.
ProgressMonitor(in the API reference documentation)
An instance of this class monitors the progress of a task. If the elapsed time of the task exceeds a program-specified value, the monitor pops up a dialog with a task description, a status note, a progress bar, an Ok button, and a Cancel button. See How to Use Progress Monitors for details and an example of using a progress monitor.
ProgressMonitorInputStream(in the API reference documentation)
An input stream with an attached progress monitor, which monitors reading from the stream. You use an instance of this stream like any of the other input streams described in Reading and Writing(in the Essential Java Classes trail). You can get the stream's progress monitor with a call to getProgressMonitor and configure it as described in How to Use Progress Monitors.
After you see a progress bar and a progress monitor in action, Deciding Whether to Use a Progress Bar or a Progress Monitor can help you figure out which is appropriate for your application.

How to Use Progress Bars
Here's a picture of a small demo application that uses a progress bar to measure the progress of a task that runs in its own thread:
Try this:
  1. Compile and run the application. The main source file is ProgressBarDemo.java. You will also need LongTask.java and SwingWorker.java.
    See Getting Started with Swing if you need help.
  2. Push the Start button. Watch the progress bar as the task makes progress. The task displays its output in the text area at the bottom of the window.
Below is the code from ProgressBarDemo.java that creates and sets up the progress bar: 
...where member variables are delcared...
JProgressBar progressBar;
...
    ...in the constructor for the demo's frame...
    progressBar = new JProgressBar(0, task.getLengthOfTask());
    progressBar.setValue(0);
    progressBar.setStringPainted(true);
The constructor used to create the progress bar sets the progress bar's minimum and maximum values. You can also set these values with setMinimum and setMaximum. The minimum and maximum values used in this program are 0 and the length of the task, which is typical of many programs and tasks. However, a progress bar's minimum and maximum values can be any value, even negative. The code snippet also sets the progress bar's current value to 0. The minimum, current, and maximum values must be related as follows: 
minimum <= current <= maximum
If you attempt to set any of the values and the new value violates the relationship, the progress bar adjusts one or more of other values according to the rules established by BoundedRangeModel(in the API reference documentation) to maintain the relationship.

The call to setStringPainted causes the progress bar display a percent string within its bounds. By default, the percent string indicates the percentage complete for the progress bar. The percent string is the value returned by the getPercentComplete method formatted as a percent. [PENDING: i've gone round and round on the wording of the previous two sentences. Kathy: can you make it better?] Alternatively, you can display a different string with setString.

You start the task by clicking the Start button. Once the task has begun, a timer (an instance of the Timer class) fires an action event every second. Here's the ActionPerformed method of the timer's action listener: 

public void actionPerformed(ActionEvent evt) {
    progressBar.setValue(task.getCurrent());
    taskOutput.append(task.getMessage() + newline);
    taskOutput.setCaretPosition(taskOutput.getDocument().getLength());
    if (task.done()) {
	Toolkit.getDefaultToolkit().beep();
	timer.stop();
	startButton.setEnabled(true);
	progressBar.setValue(progressBar.getMinimum());
    }
}
The bold line of code gets the amount of work completed by the task and updates the progress bar with that value. So the progress bar measures the progress made by the task each second, not the elapsed time. The rest of the code updates the output log, and if the task is done, turns the timer off, and resets the other controls.

As mentioned, the long-running task in this program runs in a separate thread. Generally, it's a good idea to isolate a potentially long-running task in its own thread so that the task doesn't block the rest of the program. The long-running task is implemented by LongTask.java, which uses a SwingWorker to ensure that the thread runs safely within a Swing program. See Using the SwingWorker Class in Threads and Swing for information about the SwingWorker class.

How to Use Progress Monitors
Now, let's rewrite the previous example to use a progress monitor instead of a progress bar. Here's a picture of the new demo program, ProgressMonitorDemo.java:
The general operation of this program is similar to the previous. You click the Start button to start the same long task used in the previous program. The task displays output in the text area at the bottom of the main window. However, this program uses a progress monitor instead of a progress bar.

The previous example created the progress bar on startup. In contrast, this program creates the progress monitor in the Start button's action listener's actionPerformed method. A progress monitor cannot be used again, so a new one must be created each time a new task is started.

Here's the statement to create the progress monitor: 

progressMonitor = new ProgressMonitor(ProgressMonitorDemo.this,
                                      "Running a Long Task",
                                      "", 0, task.getLengthOfTask());
The constructor used in this example initializes several progress monitor parameters. After the example creates the progress monitor, it configures the monitor further: 
progressMonitor.setProgress(0);
progressMonitor.setMillisToDecideToPopup(2 * ONE_SECOND);
The first line sets the current position of the progress bar on the dialog. The second indicates that the monitor should pop up a dialog if the task runs longer than two seconds.

By the simple fact that this example uses a progress monitor, it adds a feature that wasn't present in the version of the program that uses a progress bar. The user can cancel the task by clicking the Cancel button on the dialog. Here's the code in the example that checks to see if the user canceled the task or if the task exited normally: 

if (progressMonitor.isCanceled() || task.done()) {
    progressMonitor.close();
    task.stop();
    Toolkit.getDefaultToolkit().beep();
    timer.stop();
    startButton.setEnabled(true);
}
Note that the progress monitor doesn't itself cancel the task. It provides the GUI and API to allow the program to do so easily.

Deciding Whether to Use a Progress Bar or a Progress Monitor
Use a progress bar if:

Use a progress monitor if:

If you decide to use a progress monitor and the task you are monitoring is reading from an input stream, use the ProgressMonitorInputStream class.

The Progress Monitoring API

The following tables list the commonly used JProgressBar constructors and methods. Other methods you're likely to call are defined by the JComponent(in the API reference documentation) and Component(in the API reference documentation) classes and include [PENDING: anything in particular for these classes?]. [Link to JComponent and Component discussions.]

The API for monitoring progress falls into these categories:

Setting or Getting the Progress Bar's Constraints/Values
Method Purpose
void setValue(int)
int getValue() 		Set or get the current value of the progress bar. The value is constrained by the minimum and maximum values.
double getPercentComplete() Get the percent complete for the progress bar.
void setMinimum(int)
int getMinimum() 		Set or get the minimum value of the progress bar.
void setMaximum(int)
int getMaximum() 		Set or get the maximum value of the progress bar.
void setModel(BoundedRangeModel)
BoundedRangeModel getMaximum() 		Set or get the model used by the progress bar. The model establishes the progress bar's constraints and values. So you can use this method as an alternative to using the individual set/get methods listed above.

Fine Tuning the Progress Bar's Appearance
Method Purpose
void setOrientation(int)
int getOrientation() 		Set or get whether the progress bar is vertical or horizontal. Acceptable values are JProgressBar.VERTICAL or JProgressBar.HORIZONTAL.
void setBorderPainted(boolean)
boolean isBorderPainted() 		Set or get whether the progress bar has a border.
void setStringPainted(boolean)
boolean isStringPainted() 		Set or get whether the progress bar displays a percent string. By default, the value of the percent string is the value returned by getPercentComplete formatted as a percent. You can change the percent string with setString.
void setString(String)
String getString() 		Set or get the percent string.

Configuring the Progress Monitor
Method Purpose
ProgressMonitor(Component, Object, String, int, int) Create progress monitor and initialize its dialog's parent, description string, status note, and minimum and maximum values.
void setMinimum(int)
int getMinimum() 		Set or get the minimum value of the progress monitor.
void setMaximum(int)
int getMaximum() 		Set or get the maximum value of the progress monitor.
void setProgress(int) Update the monitor's progress.
void setNote(String)
String getNote() 		Set or get the status note. This note is displayed on the dialog. To omit the status note from the dialog, provide null as the third argument to the monitor's constructor.
void setMillisToPopup(int)
int getMillisToPopup() 		[PENDING: what is this? API docs doesn't say here's a guess....] Set or get the time after which the monitor should popup a dialog regardless of the state of the task.
void setMillisToDecideToPopup(int)
int getMillisToDecideToPopup() 		Set or get the time after which the monitor should popup a dialog if the task has not yet completed.

Terminating the Progress Monitor
Method Purpose
close() Close the progress monitor. This hides the dialog.
boolean isCanceled() Determine whether the user pressed the Cancel button.

Examples that Monitor Progress

This table shows the examples that use JProgressBar, ProgressMonitor, or ProgressMonitorInputStream, and where those examples are described.

Example Where Described Notes
ProgressBarDemo.java This page and How to Use Timers Uses a basic progress bar to show progress on a task running in a separate thread.
ProgressMonitorDemo.java This page Modification of the previous example that uses a progress monitor instead of a progress bar.

Previous | Next | Trail Map | Creating a User Interface (with Swing) | Using the JFC/Swing Packages