Package ca.cgjennings.apps.arkham

Class BusyDialog

java.lang.Object

ca.cgjennings.apps.arkham.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

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

getProgressCurrent

public int getProgressCurrent()

Returns the current progress value of this busy dialog.

Returns:

the number of work units that have been completed

See Also:

setProgressCurrent(int), setProgressMaximum(int)

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