Class BusyDialog


  • public final class BusyDialog
    extends java.lang.Object
    Displays a pop-up dialog to indicate that the application is busy while performing operations that take a long time to complete. The dialog can display a heading, a smaller status message, the current progress as a progress bar, and may optionally include a Cancel button. The progress bar will initially indicate that the length of the operation is indeterminate; setting a non-negative maximum progress value will change the progress bar to determinate mode.

    Note that the dialog will be displayed (and the operation to be performed may start running) immediately, before the constructor returns. There is no need to explicitly "start" the operation.

    To use a BusyDialog from script code, use the Thread.busyWindow( task, title, canCancel ) function in the threads library.

    Author:
    Chris Jennings
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.awt.event.ActionListener NO_CANCEL_ACTION
      This is a shared action listener that performs no action.
    • Constructor Summary

      Constructors 
      Constructor Description
      BusyDialog​(java.lang.String title, java.lang.Runnable operation)
      Creates a new busy dialog with the specified title message that will perform the specified operation in a separate thread.
      BusyDialog​(java.lang.String title, java.lang.Runnable operation, java.awt.event.ActionListener cancelAction)
      Creates a new busy dialog with the specified title message that will perform the specified operation in a separate thread.
      BusyDialog​(javax.swing.JFrame parent, java.lang.String title, java.lang.Runnable operation)
      Creates a new busy dialog with the specified title message that will perform the specified operation in a separate thread.
      BusyDialog​(javax.swing.JFrame parent, java.lang.String title, java.lang.Runnable operation, java.awt.event.ActionListener cancelAction)
      Creates a new busy dialog with the specified title message that will perform the specified operation in a separate thread.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void currentProgress​(int currentValue)
      Sets the current progress value of the current busy dialog.
      static void currentProgress​(int currentValue, int delay)
      Sets the current progress value of the current busy dialog.
      static BusyDialog getCurrentDialog()
      Returns the busy dialog most appropriate for the caller.
      int getProgressCurrent()
      Returns the current progress value of this busy dialog.
      int getProgressMaximum()
      Returns the current maximum progress value, or -1 if in indeterminate mode.
      boolean isCancelled()
      Returns true if this dialog has a cancel button and it has been pressed by the user.
      static void maximumProgress​(int maximumValue)
      Sets the maximum progress value of the current busy dialog.
      void setProgressCurrent​(int currentValue)
      Sets the current progress value of this busy dialog.
      void setProgressMaximum​(int maximumValue)
      Sets the maximum progress value of this busy dialog.
      void setStatusText​(java.lang.String text)
      Sets the status text of this busy dialog.
      void setTitleText​(java.lang.String text)
      Sets the title of this busy dialog.
      static void statusText​(java.lang.String text)
      Sets the status text of the current busy dialog.
      static void statusText​(java.lang.String text, int delay)
      Sets the status text of the current busy dialog.
      static void titleText​(java.lang.String text)
      Sets the title of the current busy dialog.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • NO_CANCEL_ACTION

        public static final java.awt.event.ActionListener NO_CANCEL_ACTION
        This is a shared action listener that performs no action. It can be passed to the constructor to create a busy dialog with a Cancel button but with no explicit cancel action attached. The Runnable representing the operation being performed can still determine if the Cancel button has been pressed by calling isCancelled().
    • Constructor Detail

      • BusyDialog

        public BusyDialog​(java.lang.String title,
                          java.lang.Runnable operation)
        Creates a new busy dialog with the specified title message that will perform the specified operation in a separate thread. The dialog's parent window will be the main application window.
        Parameters:
        title - the initial title message
        operation - the operation to perform
      • BusyDialog

        public BusyDialog​(javax.swing.JFrame parent,
                          java.lang.String title,
                          java.lang.Runnable operation)
        Creates a new busy dialog with the specified title message that will perform the specified operation in a separate thread. The dialog's parent frame will default to the main application window if null.
        Parameters:
        parent - the parent frame
        title - the initial title message
        operation - the operation to perform
      • BusyDialog

        public BusyDialog​(java.lang.String title,
                          java.lang.Runnable operation,
                          java.awt.event.ActionListener cancelAction)
        Creates a new busy dialog with the specified title message that will perform the specified operation in a separate thread. The dialog's parent window will be the main application window. The dialog will include a Cancel button that can be clicked by the user. When pressed, the specified listener's actionPerformed method will be called from the event dispatch thread.
        Parameters:
        title - the initial title message
        operation - the operation to perform
        cancelAction - the action to perform when the user presses the Cancel button
      • BusyDialog

        public BusyDialog​(javax.swing.JFrame parent,
                          java.lang.String title,
                          java.lang.Runnable operation,
                          java.awt.event.ActionListener cancelAction)
        Creates a new busy dialog with the specified title message that will perform the specified operation in a separate thread. The dialog's parent frame will default to the main application window if null. The dialog will include a Cancel button that can be clicked by the user. When pressed, the specified listener's actionPerformed method will be called from the event dispatch thread.
        Parameters:
        parent - the parent frame
        title - the initial title message
        operation - the operation to perform
        cancelAction - the action to perform when the user presses the Cancel button
    • Method Detail

      • titleText

        public static void titleText​(java.lang.String text)
        Sets the title of the current busy dialog. (The initial title is set in the constructor.) If no busy dialog is open, this method has no effect.

        This method can be called from any thread.

        Parameters:
        text - the title text displayed in large print at the top of the dialog
        See Also:
        setTitleText(java.lang.String), getCurrentDialog()
      • statusText

        public static void statusText​(java.lang.String text)
        Sets the status text of the current busy dialog. If no busy dialog is open, this method has no effect.

        This method can be called from any thread.

        Parameters:
        text - the status text displayed in small print at the bottom of the dialog
        See Also:
        setStatusText(java.lang.String), getCurrentDialog()
      • statusText

        public static void statusText​(java.lang.String text,
                                      int delay)
        Sets the status text of the current busy dialog. This version of the method will not actually update the text more often than once per delay milliseconds. This prevents status text updates from dominating the time spent doing real work If no busy dialog is open, this method has no effect.

        This method can be called from any thread.

        Parameters:
        text - the status text displayed in small print at the bottom of the dialog
        delay - the minimum time between status text changes, in milliseconds
        See Also:
        setStatusText(java.lang.String), getCurrentDialog()
      • currentProgress

        public static void currentProgress​(int currentValue)
        Sets the current progress value of the current busy dialog. If no busy dialog is open, this method has no effect.

        This method can be called from any thread.

        Parameters:
        currentValue - the number of units of work that have been completed
        See Also:
        setProgressCurrent(int), getCurrentDialog()
      • currentProgress

        public static void currentProgress​(int currentValue,
                                           int delay)
        Sets the current progress value of the current busy dialog. This version of the method will not actually update the progress more often than once per delay milliseconds. This prevents progress updates from dominating the time spent doing real work If no busy dialog is open, this method has no effect.

        This method can be called from any thread.

        Parameters:
        currentValue - the number of units of work that have been completed
        delay - the minimum time between status text changes, in milliseconds
        See Also:
        setProgressCurrent(int), getCurrentDialog()
      • maximumProgress

        public static void maximumProgress​(int maximumValue)
        Sets the maximum progress value of the current busy dialog. If no busy dialog is open, this method has no effect.

        This method can be called from any thread.

        Parameters:
        maximumValue - the total number of units of work that must be performed, or -1 if unknown
        See Also:
        setProgressMaximum(int), getCurrentDialog()
      • getCurrentDialog

        public static BusyDialog getCurrentDialog()
        Returns the busy dialog most appropriate for the caller. If this is called from the Runnable that was passed to a BusyDialog constructor, then it will return the dialog that is displaying progress for that Runnable. Otherwise, it returns the most recently created BusyDialog that is still open. If no BusyDialog is open, it will return null. The static methods titleText(java.lang.String), statusText(java.lang.String), currentProgress(int), and maximumProgress(int) all modify the state of the current dialog.

        This method can be called from any thread.

        Returns:
        the busy dialog that this thread should modify, or null
      • setTitleText

        public void setTitleText​(java.lang.String text)
        Sets the title of this busy dialog. (The initial title is set in the constructor.)

        This method can be called from any thread.

        Parameters:
        text - the title text displayed in large print at the top of the dialog
      • setStatusText

        public void setStatusText​(java.lang.String text)
        Sets the status text of this busy dialog.

        This method can be called from any thread.

        Parameters:
        text - the status text displayed in small print at the bottom of the dialog
      • setProgressCurrent

        public void setProgressCurrent​(int currentValue)
        Sets the current progress value of this busy dialog.

        This method can be called from any thread.

        Parameters:
        currentValue - the number of units of work that have been completed
      • setProgressMaximum

        public void setProgressMaximum​(int maximumValue)
        Sets the maximum progress value of this busy dialog. This is a value that represents the total number of units of work to be performed. Setting the maximum progress value to -1 will cause the progress to enter indeterminate mode. This mode should be used when the total amount of work is unknown or the length of time required to complete a work unit is so variable that the progress bar is not a meaningful indicator of how long the task will take to complete.

        When this method is called and the maximumValue is not negative, the current progress value is reset to 0.

        This method can be called from any thread.

        Parameters:
        maximumValue - the total number of units of work that must be performed
      • getProgressMaximum

        public int getProgressMaximum()
        Returns the current maximum progress value, or -1 if in indeterminate mode.
        Returns:
        the total number of work units to complete, or -1
      • isCancelled

        public boolean isCancelled()
        Returns true if this dialog has a cancel button and it has been pressed by the user.
        Returns:
        true if the user has indicated that they wish to cancel the operation