org.netbeans.api.progress

Class BaseProgressUtils

java.lang.Object

org.netbeans.api.progress.BaseProgressUtils

public final class BaseProgressUtils
extends Object

Contains useful utilities that can function in a non-Swing environment. For Swing-related utilities (which use e.g. JComponent and Swing Actions), use org.netbeans.api.progress.ProgressUtils from the api.progress.nb module.

Since:

1.40

Method Summary

Modifier and Type	Method and Description
static void	runOffEventDispatchThread(Runnable operation, String operationDescr, AtomicBoolean cancelOperation, boolean waitForCanceled) Runs operation out of event dispatch thread, blocks UI while operation is in progress.
static void	runOffEventDispatchThread(Runnable operation, String operationDescr, AtomicBoolean cancelOperation, boolean waitForCanceled, int waitCursorAfter, int dialogAfter) Runs operation out of event dispatch thread, blocks UI while operation is in progress.
static void	runOffEventThreadWithProgressDialog(Runnable operation, String dialogTitle, ProgressHandle progress, boolean includeDetailLabel, int waitCursorAfter, int dialogAfter) Runs operation out of the event thread, blocking the whole UI.
static <T> T	showProgressDialogAndRun(ProgressRunnable<T> operation, String displayName, boolean includeDetailLabel) Show a modal progress dialog that blocks the main window and all other currently displayed frames or dialogs, while running the passed runnable on a background thread.
static void	showProgressDialogAndRun(Runnable operation, ProgressHandle progress, boolean includeDetailLabel) Show a modal progress dialog that blocks the main window and all other currently displayed frames or dialogs, while running the passed runnable on a background thread.
static void	showProgressDialogAndRun(Runnable operation, String displayName) Show a modal progress dialog that blocks the main window and all other currently displayed frames or dialogs, while running the passed runnable on a background thread with an indeterminate-state progress bar.
static <T> Future<T>	showProgressDialogAndRunLater(ProgressRunnable<T> operation, ProgressHandle handle, boolean includeDetailLabel) Show a modal progress dialog that blocks the main window and all other currently displayed frames or dialogs while running a background process.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

runOffEventDispatchThread

public static void runOffEventDispatchThread(Runnable operation,
                                             String operationDescr,
                                             AtomicBoolean cancelOperation,
                                             boolean waitForCanceled)

Runs operation out of event dispatch thread, blocks UI while operation is in progress. First it shows wait cursor after ~50ms elapses, if operation takes longer than ~10s a dialog with Cancel button is shown.

This method is supposed to be used by user invoked foreground actions, that are expected to run very fast in vast majority of cases. However, in some rather rare cases (e.g. extensive IO operations in progress), supplied operation may need longer time. In such case this method first displays wait cursor and if operation takes even more time it displays dialog allowing to cancel operation. DO NOT use this method for operations that may take long time under normal circumstances!

Parameters:

operation - operation to perform

operationDescr - text shown in dialog

cancelOperation - set to true if user canceled the operation

waitForCanceled - true if method should wait until canceled task is finished (if it is not finished in 1s ISE is thrown)

runOffEventDispatchThread

public static void runOffEventDispatchThread(Runnable operation,
                                             String operationDescr,
                                             AtomicBoolean cancelOperation,
                                             boolean waitForCanceled,
                                             int waitCursorAfter,
                                             int dialogAfter)

Runs operation out of event dispatch thread, blocks UI while operation is in progress. First it shows wait cursor after waitCursorAfter elapses, if operation takes longer than dialogAfter a dialog with Cancel button is shown.

This method is supposed to be used by user invoked foreground actions, that are expected to run very fast in vast majority of cases. However, in some rather rare cases (e.g. extensive IO operations in progress), supplied operation may need longer time. In such case this method first displays wait cursor and if operation takes even more time it displays dialog allowing to cancel operation. DO NOT use this method for operations that may take long time under normal circumstances!

Parameters:

operation - operation to perform

operationDescr - text shown in dialog

cancelOperation - set to true if user canceled the operation

waitForCanceled - true if method should wait until canceled task is finished (if it is not finished in 1s ISE is thrown)

waitCursorAfter - time in ms after which wait cursor is shown

dialogAfter - time in ms after which dialog with "Cancel" button is shown

Since:

1.19

showProgressDialogAndRun

public static void showProgressDialogAndRun(Runnable operation,
                                            ProgressHandle progress,
                                            boolean includeDetailLabel)

Show a modal progress dialog that blocks the main window and all other currently displayed frames or dialogs, while running the passed runnable on a background thread.

This method is thread-safe, and will block until the operation has completed, regardless of what thread calls this method.

The resulting progress UI should show a cancel button if the passed runnable implements org.openide.util.Cancellable.

Unless you are being passed the runnable or progress handle from foreign code (such as in WizardDescriptor.progressInstantiatingIterator), it is usually simpler to use showProgressDialogAndRun(ProgressRunnable, String, boolean).

Parameters:

operation - A runnable to run in the background

progress - A progress handle to create a progress bar for

includeDetailLabel - True if the caller will use ProgressHandle.progress (String, int), false if not. If true, the created dialog will include a label that shows progress details.

Since:

1.19

runOffEventThreadWithProgressDialog

public static void runOffEventThreadWithProgressDialog(Runnable operation,
                                                       String dialogTitle,
                                                       ProgressHandle progress,
                                                       boolean includeDetailLabel,
                                                       int waitCursorAfter,
                                                       int dialogAfter)

Runs operation out of the event thread, blocking the whole UI. When operation takes more than 1s, the method first displays wait cursor. If operation will not end in 3s interval, modal dialog with progress is shown up. If operation is marked with Cancellable interface, cancel button is part of dialog and can be used to interrupt the operation.

Parameters:

operation - task to perform in the background

dialogTitle - dialog title

progress - progress handle. Do not invoke any methods before passing to this method. Start/progress/finish it only in operation

includeDetailLabel - show progress detail label in the dialog

waitCursorAfter - amount of time, in milliseconds, after which wait cursor is shown

dialogAfter - amount of time, in milliseconds, after which dialog is shown

Since:

1.30

showProgressDialogAndRun

public static <T> T showProgressDialogAndRun(ProgressRunnable<T> operation,
                                             String displayName,
                                             boolean includeDetailLabel)

Show a modal progress dialog that blocks the main window and all other currently displayed frames or dialogs, while running the passed runnable on a background thread.

This method is thread-safe, and will block until the operation has completed, regardless of what thread calls this method.

The resulting progress UI should show a cancel button if the passed runnable implements org.openide.util.Cancellable.

Type Parameters:

T - The result type - use Void if no return type needed

Parameters:

operation - A runnable-like object which performs work in the background, and is passed a ProgressHandle to update progress

displayName - The display name for this operation

includeDetailLabel - If true, include a lable to show progress details (needed only if you plan to call ProgressHandle.setProgress(String, int)

Returns:

The result of the operation.

Since:

1.19

showProgressDialogAndRun

public static void showProgressDialogAndRun(Runnable operation,
                                            String displayName)

Show a modal progress dialog that blocks the main window and all other currently displayed frames or dialogs, while running the passed runnable on a background thread with an indeterminate-state progress bar.

This method is thread-safe, and will block until the operation has completed, regardless of what thread calls this method.

The resulting progress UI should show a cancel button if the passed runnable implements org.openide.util.Cancellable. .

Parameters:

operation - A runnable to run

displayName - The display name of the operation, to show in the dialog

Since:

1.19

showProgressDialogAndRunLater

public static <T> Future<T> showProgressDialogAndRunLater(ProgressRunnable<T> operation,
                                                          ProgressHandle handle,
                                                          boolean includeDetailLabel)

Show a modal progress dialog that blocks the main window and all other currently displayed frames or dialogs while running a background process. This call should block until the work is started, and then return a task which can be monitored for completion or cancellation. This method will not block while the work is run, only until the progress UI is initialized.

The resulting progress UI should show a cancel button if the passed runnable implements org.openide.util.Cancellable.

Parameters:

operation -

handle -

includeDetailLabel -

Returns: