ProgressMonitor

Answer:
The ProgressMonitor class is a convenience class that saves you from the hassle of creating your own dialog with a JProgressBar. It will pop up a dialog containing a JProgressBar that displays the progress of an operation.

ProgressMonitor will only pop up the monitor after a set minimum amount of time has passed. The default value is 500 milliseconds and can be set with setMillisToDecideToPopup(int). Based on the progress of the operation up to this point, ProgressMonitor will decide how much longer it will take for the operation to complete. Only if this time is greater than a given threshold will the dialog be displayed. The default threshold is 2 seconds and can be set with setMillisToPopup).

The progress of an operation is conveyed to the ProgressMonitor by calling setProgress(int) with an integer argument representing the progress. The ProgressMonitor constructor accepts a minimum value and a maximum value for the progress indicator in order to determine when and how to update the progress bar.

If you are not careful, you can use ProgressMonitor to no effect. The most common cause is when your operation completes too quickly. You can get around this by reducing the popup threshold values to zero. Another situation that can occur is that the progress dialog will appear, but no updates will occur. You can prevent this by not calling setProgress so often that the AWT thread doesn't get a chance to update the progress bar.

In the end, I am not too keen on the ProgressMonitor class. The dialog it creates has both an OK and a Cancel button. The Cancel button makes sense and is intended to terminate the operation. Before calling setProgress, you should test if the operation has been canceled with boolean isCanceled(), which will return true if the cancel button has been pressed. The OK button doesn't make much sense to me, and will make the dialog disappear even before the operation has completed. Right now I consider this a bug and don't recommend using ProgressMonitor because the OK button can confuse users.

The following example code shows how you might use the ProgressMonitor class. I use a dummy loop to simulate work, but you could imagine that bytes were being read from a socket during a file download.

import java.awt.*;
import java.awt.event.*;
import javax.swing.*;

public class Progress {
  public static final int LOOP_MAX = 15000;
  public static void main(String[] args) {
    JFrame frame = new JFrame("Progress Demo");
    ProgressMonitor progress;
    WindowListener exitListener;

    exitListener = new WindowAdapter() {
      public void windowClosing(WindowEvent e) {
        Window window = e.getWindow();
        window.setVisible(false);
        window.dispose();
        System.exit(0);
      }
    };

    frame.addWindowListener(exitListener);
    frame.setSize(400, 400);
    frame.setVisible(true);

    progress =
      new ProgressMonitor(frame, "Executing dummy loop.",
			  "Iterating.", 0, LOOP_MAX);

    for(int i = 0; i <= LOOP_MAX; ++i) {
      // Simulate some work
      for(int j = 0; j <= LOOP_MAX; ++j);
      if(progress.isCanceled())
	break;
      progress.setProgress(i);
    }
  }
}