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 Java's ProgressMonitor class, which is a bit limiting. Specifically, this dialog can show "major" and "minor" progress bars simultaneously, and increment them both, as a long-running worker 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 (major steps), and performing some time-intensive operation within each directory (minor steps). 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 ("directory 2 of 12"), while also showing a "minor" progress bar showing the progress within the current directory ("file 17 of 111").

USAGE: Start by extending one of the worker classes: either MultiProgressWorker (for major and minor progress) or SimpleProgressWorker (for just a single progress bar). Implement the run() method to perform your long-running task. As your task progresses, invoke the various fire...() methods to notify listeners of progress. Remember to invoke either fireProgressComplete() or fireProgressCanceled() at the end of your run() method to let listeners know that the work is done. Failure to invoke one of these termination events will result in the progress dialog remaining open indefinitely.

When you have your worker class ready, create an instance of MultiProgressDialog, and invoke its runWorker() method, passing in an instance of your worker class. If you wish to set other options (documented below), do so before invoking runWorker().

MultiProgressDialog instances can be re-used, but be sure to invoke resetProgress() in between each usage to reset the progress bars.

Other options

  • You can set an initial show delay on the dialog, so that it will only appear if the work takes longer than a certain amount of time. This is useful to avoid flashing a progress dialog for very short operations. Use the setInitialShowDelayMS() method to set this delay time in milliseconds. The default is 0, meaning the dialog will appear as soon as the work begins.
  • You can customize the format of the progress messages shown in the major and minor progress labels. See the DEFAULT_PROGRESS_FORMAT constant for details. Use the setFormatString() method to change the format string.
Since:
swing-extras 1.6 (2022-04-15)
Author:
scorbo2
See Also:

  • Field Details

    • DEFAULT_PROGRESS_FORMAT

      public static final String DEFAULT_PROGRESS_FORMAT
      This will yield: "[%currentStep of %totalSteps] %message"

      You can go back to the pre-2.7 format with "%m (%s of %t)", which will yield "%message (%currentStep of %totalSteps)".

      It's probably best to keep the "x of y" part on the left side of the string. The string length of "%message" can vary widely and rapidly as progress continues, which can make it hard to read the step counts if they're bouncing around at the end of the string.

      But rather than hard-coding a "fix" for that problem, it is now configurable!

      The available tags are:

      • %m - The progress message sent from the worker thread
      • %s - The current step number (1-based)
      • %t - The total number of steps

      You can add whatever punctuation, spacing, or other text you like around the tags, though be aware there is a length limit on the progress label, and the worker-supplied message can be quite long.

      Use the setFormatString() method to change the format string.

      See Also:

    • LEGACY_PROGRESS_FORMAT

      public static final String LEGACY_PROGRESS_FORMAT
      If you really don't like the new 2.7 default format, you can use this legacy format string to get the old behavior.
      See Also:

  • Constructor Details

    • MultiProgressDialog

      public MultiProgressDialog(Window owner, String title)
      Creates a new, blank MultiProgressDialog with the specified owner window 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 Window 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.

    • getInitialShowDelayMS

      public long getInitialShowDelayMS()
      Returns the optional delay time, in milliseconds, between the time when the work begins and the time when the progress dialog is made visible. The default value is 0, meaning the dialog will appear as soon as the work begins.

    • setInitialShowDelayMS

      public void setInitialShowDelayMS(long initialShowDelayMS)
      Sets an optional delay time, in milliseconds, between the time when the work starts and the time when the dialog will make itself visible. The default value is 0, which means the dialog will appear as soon as the work begins. But you can set this to avoid showing a dialog for very short-running tasks. For example, setting this value to 2000 will prevent the dialog from showing if the work to be executed completes in less than 2 seconds.

    • 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.

    • getFormatString

      public String getFormatString()
      Returns the current format string that will be used to display progress messages. See the DEFAULT_PROGRESS_FORMAT constant for details.

    • setFormatString

      public void setFormatString(String formatString)
      Optionally change the format string that will be used to display progress messages. See the DEFAULT_PROGRESS_FORMAT constant for details.

    • getTruncationMode

      public MultiProgressDialog.TruncationMode getTruncationMode()
      Returns the current truncation mode for long progress messages.

    • setTruncationMode

      public void setTruncationMode(MultiProgressDialog.TruncationMode truncationMode)
      The default behavior is to truncate long progress messages at the end. You can change this to truncate at the start instead. Example: "some unreasonably long message" can either become "some unreasonably long mes..." with TruncationMode.END, or it can become "...nably long message" with TruncationMode.START.