Package ca.corbett.extras.progress

Class MultiProgressDialog

java.lang.Object
java.awt.Component
java.awt.Container
java.awt.Window
java.awt.Dialog
javax.swing.JDialog
ca.corbett.extras.progress.MultiProgressDialog
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer, WindowConstants
public final class MultiProgressDialog extends JDialog
Replacement for ProgressMonitor, which is a bit limiting. Specifically, this dialog can show "major" and "minor" progress bars simultaneously, and increment them each as a long-running thread progresses. This allows you to show more detailed progress, particularly for executing worker threads involving a list of long-running work items. For example, iterating over a list of directories and performing some time-intensive operation within each directory. In this hypothetical example, it would be helpful to the user to show a "major" progress bar showing the progress through the list of directories (for example, "directory 2 of 12"), while also showing a "minor" progress bar showing the progress within the current directory ("file 17 of 111").

USAGE:

Create an instance of MultiProgressDialog and pass it into a worker thread (or have the worker thread create one). The worker thread should invoke setMajorProgressBounds() to set the min and max values of the major progress bar. The worker thread can then show the dialog and begin work. As soon as the bounds of the minor progress bar are known, the worker thread can invoke setMinorProgressBounds(). Periodically, the worker thread should invoke setMajorProgress() and setMinorProgress() to let the user know what's going on, and also check on the isCanceled() method to learn if the user has clicked the cancel button. When the worker thread is finished, it can dispose the dialog.

MultiProgressDialog instances can be re-used, but be sure to invoke resetProgress() in between each usage to reset the progress bars (you will also then need to invoke setMajorProgressBounds() and setMinorProgressBounds() as soon as they are known, as above).

Since:
2022-04-15
Author:
scorbo2
See Also:

  • Constructor Details

    • MultiProgressDialog

      public MultiProgressDialog(JFrame owner, String title)
      Creates a new, blank MultiProgressDialog with the specified owner frame and window title. Closing the progress dialog will act the same as though the cancel button had been clicked. Call isCanceled() at any time to see if the operation should continue or not (that is, if the user has clicked the cancel button on the progress dialog).
      Parameters:
      owner - The JFrame that will own this MultiProgressDialog
      title - The window title

    • MultiProgressDialog

      public MultiProgressDialog(JDialog owner, String title)
      Creates a new, blank MultiProgressDialog with the specified owner dialog and window title. Closing the progress dialog will act the same as though the cancel button had been clicked. Call isCanceled() at any time to see if the operation should continue or not (that is, if the user has clicked the cancel button on the progress dialog).
      Parameters:
      owner - The JDialog that will own this MultiProgressDialog
      title - The window title

  • Method Details

    • resetProgress

      public void resetProgress()
      Resets to a blank, default state. Also resets the isCanceled flag.

    • runWorker

      public void runWorker(MultiProgressWorker worker, boolean disposeWhenComplete)
      Executes the given Runnable and auto-wires all progress events to this dialog. This is a very easy way to simply implement some runnable that can fire progress events, and pass it to this method to handle the UI aspect automatically. Progress errors are simply ignored here. You can add your own MultiProgressAdapter to the worker before passing it in here if you wish to respond to errors. This method will show both major and minor progress bars. It is intended for complex tasks that have subtasks. Use the overloaded runWorker that accepts a SimpleProgressWorker if you only need a single progress bar.
      Parameters:
      worker - Any MultiProgressWorker implementation that can perform some task.
      disposeWhenComplete - , if true, will dispose() this dialog when complete. Otherwise, hides the dialog.

    • runWorker

      public void runWorker(SimpleProgressWorker worker, boolean disposeWhenComplete)
      Executes the given Runnable and auto-wires all progress events to this dialog. This is a very easy way to simply implement some runnable that can fire progress events, and pass it to this method to handle the UI aspect automatically. Progress errors are simply ignored here. You can add your own SimpleProgressAdapter to the worker before passing it in here if you wish to respond to errors. This method will hide the "minor" progress bar and only show a single progress bar. It is intended for simple tasks. Use the overloaded runWorker that accepts a MultiProgressWorker to show both major and minor progress.
      Parameters:
      worker - Any SimpleProgressWorker implementation that can perform some task.
      disposeWhenComplete - , if true, will dispose() this dialog when complete. Otherwise, hides the dialog.

    • setMajorProgressBounds

      public void setMajorProgressBounds(int minimum, int maximum)
      Sets the minimum and maximum bounds of the major progress bar.This will also set the major progress value to "minimum".
      Parameters:
      minimum - The minimum value of the major progress bar (typically 0).
      maximum - The maximum value of the major progress bar.

    • setMinorProgressBounds

      public void setMinorProgressBounds(int minimum, int maximum)
      Sets the minimum and maximum bounds of the minor progress bar.This will also set the minor progress value to "minimum".
      Parameters:
      minimum - The minimum value of the minor progress bar (typically 0).
      maximum - The maximum value of the minor progress bar.

    • setMajorProgress

      public void setMajorProgress(int progress)
      Sets the progress value for the major progress bar without updating the progress label. See also setMajorProgress(int,String)
      Parameters:
      progress - The new value for the major progress bar.

    • setMajorProgress

      public void setMajorProgress(int progress, String message)
      Sets the progress value for the major progress bar and updates the major progress label with the given message.
      Parameters:
      progress - The new value for the major progress bar.
      message - The new message to show in the major progress label (ignored if null).

    • setMinorProgress

      public void setMinorProgress(int progress)
      Sets the progress value for the minor progress bar without updating the progress label. See also setMajorProgress(int,String)
      Parameters:
      progress - The new value for the minor progress bar.

    • setMinorProgress

      public void setMinorProgress(int progress, String message)
      Sets the progress value for the minor progress bar and updates the major progress label with the given message.
      Parameters:
      progress - The new value for the minor progress bar.
      message - The new message to show in the minor progress label (ignored if null).

    • isCanceled

      public boolean isCanceled()
      Indicates whether the cancel button has been clicked or not.
      Returns:
      True if the cancel button has been clicked.