org.netbeans.api.progress

Class ProgressHandle

java.lang.Object

org.netbeans.api.progress.ProgressHandle

All Implemented Interfaces:

AutoCloseable

public final class ProgressHandle
extends Object
implements AutoCloseable

Instances provided by the ProgressHandleFactory allow the users of the API to notify the progress bar UI about changes in the state of the running task. Progress component will be visualized only after one of the start() methods.

This class was adapted to contain only non-Swing part of the Progress API. If you need to use progress UI components, please work with org.netbeans.api.progres.ProgressUIHandle class from org.netbeans.api.progress.nb module.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ACTION_VIEW The action command generated by user "activation" of a ProgressHandle's representation.

Method Summary

Modifier and Type	Method and Description
boolean	addDefaultAction(Action action) Adds an action to the progress indicator.
void	close() Calls ProgressHandle.finish()
static ProgressHandle	createHandle(String displayName) Create a progress ui handle for a long lasting task.
static ProgressHandle	createHandle(String displayName, Cancellable allowToCancel) Create a progress ui handle for a long lasting task.
static ProgressHandle	createHandle(String displayName, Cancellable allowToCancel, Action viewAction) Creates a potentially cancellable handle, which can deliver an event if the user 'triggers' the handle.
static ProgressHandle	createSystemHandle(String displayName, Cancellable allowToCancel) Create a cancelable handle for a task that is not triggered by explicit user action.
static ProgressHandle	createSystemHandle(String displayName, Cancellable allowToCancel, Action viewAction) Creates a possibly cancellable handle, not initiated by the user, e.g.
void	finish() Finish the task, remove the task's component from the progress bar UI.
void	progress(int workunit) Notify the user about completed workunits.
void	progress(String message) Notify the user about progress by showing message with details.
void	progress(String message, int workunit) Notify the user about completed workunits and show additional detailed message.
void	setDisplayName(String newDisplayName) Change the display name of the progress task.
void	setInitialDelay(int millis) Set a custom initial delay for the progress task to appear in the status bar.
void	start() start the progress indication for indeterminate task.
void	start(int workunits) start the progress indication for a task with known number of steps.
void	start(int workunits, long estimate) start the progress indication for a task with known number of steps and known time estimate for completing the task.
void	suspend(String message) Current task can switch to silent suspend mode where the progress bar stops moving, hides completely or partially.
void	switchToDeterminate(int workunits) Currently indeterminate task can be switched to show percentage completed.
void	switchToDeterminate(int workunits, long estimate) Currently indeterminate task can be switched to show the time estimate til completion.
void	switchToIndeterminate() Currently determinate task (with percentage or time estimate) can be switched to indeterminate mode.

Methods inherited from class java.lang.Object

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

Field Detail

ACTION_VIEW

public static final String ACTION_VIEW

The action command generated by user "activation" of a ProgressHandle's representation.

See Also:

Constant Field Values

Method Detail

createHandle

public static ProgressHandle createHandle(String displayName)

Create a progress ui handle for a long lasting task.

Parameters:

displayName - to be shown in the progress UI

Returns:

an instance of ProgressHandle, initialized but not started.

createHandle

public static ProgressHandle createHandle(String displayName,
                                          Cancellable allowToCancel)

Create a progress ui handle for a long lasting task.

Parameters:

allowToCancel - either null, if the task cannot be cancelled or an instance of Cancellable that will be called when user triggers cancel of the task.

displayName - to be shown in the progress UI

Returns:

an instance of ProgressHandle, initialized but not started.

createSystemHandle

public static ProgressHandle createSystemHandle(String displayName,
                                                Cancellable allowToCancel)

Create a cancelable handle for a task that is not triggered by explicit user action. Such tasks have lower priority in the UI.

Parameters:

displayName - to be shown in the progress UI

allowToCancel - either null, if the task cannot be cancelled or an instance of Cancellable that will be called when user triggers cancel of the task.

Returns:

an instance of ProgressHandle, initialized but not started.

createHandle

public static ProgressHandle createHandle(String displayName,
                                          Cancellable allowToCancel,
                                          Action viewAction)

Creates a potentially cancellable handle, which can deliver an event if the user 'triggers' the handle. How the handle will be presented, and what the "trigger" gesture is depends on the Controller implementation. The user may make an action on the handle (other than cancel), which will be reflected back. Typically used to focus or display some part of the UI. If triggerCallback is provided, it should handle at least ProgressHandle.ACTION_VIEW action command ActionEvent.getActionCommand().

Parameters:

viewAction - callback on user's trigger.

displayName - to be shown in the progress UI

allowToCancel - either null, if the task cannot be cancelled or an instance of Cancellable that will be called when user triggers cancel of the task.

Returns:

an instance of ProgressHandle, initialized but not started.

Since:

1.59

createSystemHandle

public static ProgressHandle createSystemHandle(String displayName,
                                                Cancellable allowToCancel,
                                                Action viewAction)

Creates a possibly cancellable handle, not initiated by the user, e.g. for indexing, repository or other system-launched tasks. See documentation for ProgressHandle.createHandle(java.lang.String, org.openide.util.Cancellable, javax.swing.Action) for more details.

Parameters:

displayName - to be shown in the progress UI

allowToCancel - either null, if the task cannot be cancelled or an Cancellable instance that will be called when the user requests cancel.

viewAction - listener that will be triggered when the progress is 'activated'.

Returns:

created ProgressHandle instance

start

public final void start()

start the progress indication for indeterminate task. it will be visualized by a progress bar in indeterminate mode. start method can be called just once.

start

public final void start(int workunits)

start the progress indication for a task with known number of steps. start method can be called just once.

Parameters:

workunits - total number of workunits that will be processed

start

public final void start(int workunits,
                        long estimate)

start the progress indication for a task with known number of steps and known time estimate for completing the task. start method can be called just once.

Parameters:

workunits - total number of workunits that will be processed

estimate - estimated time to process the task in seconds

switchToIndeterminate

public final void switchToIndeterminate()

Currently determinate task (with percentage or time estimate) can be switched to indeterminate mode. This method has to be called after calling start method and before calling finish method (the task has to be running).

suspend

public final void suspend(String message)

Current task can switch to silent suspend mode where the progress bar stops moving, hides completely or partially. This method has to be called after calling start method and before calling finish method (the task has to be running). Useful to make progress in status bar less intrusive. for very long running tasks, eg. running an ant script that executes user application, debugs user application etc. Any incoming progress wakes up the progress bar to previous state.

Parameters:

message - a message to display in the silent mode

Since:

org.netbeans.api.progress/1 1.9

switchToDeterminate

public final void switchToDeterminate(int workunits)

Currently indeterminate task can be switched to show percentage completed. This method has to be called after calling start method and before calling finish method (the task has to be running). A common usecase is to calculate the amount of work in the beginning showing in indeterminate mode and later switch to the progress with known steps

Parameters:

workunits - a definite number of complete units of work out of the total

switchToDeterminate

public final void switchToDeterminate(int workunits,
                                      long estimate)

Currently indeterminate task can be switched to show the time estimate til completion. This method has to be called after calling start method and before calling finish method (the task has to be running). A common usecase is to calculate the amount of work in the beginning in indeterminate mode and later switch to the progress with the calculated estimate.

Parameters:

workunits - a definite number of complete units of work out of the total

estimate - estimated time to process the task, in seconds

close

public final void close()

Calls ProgressHandle.finish()

Specified by:

close in interface AutoCloseable

finish

public final void finish()

Finish the task, remove the task's component from the progress bar UI. This method has to be called after calling start method (the task has to be running).

progress

public final void progress(int workunit)

Notify the user about completed workunits. This method has to be called after calling start method and before calling finish method (the task has to be running).

Parameters:

workunit - a cumulative number of workunits completed so far

progress

public final void progress(String message)

Notify the user about progress by showing message with details. This method has to be called after calling start method and before calling finish method (the task has to be running).

Parameters:

message - details about the status of the task

progress

public final void progress(String message,
                           int workunit)

Notify the user about completed workunits and show additional detailed message. This method has to be called after calling start method and before calling finish method (the task has to be running).

Parameters:

message - details about the status of the task

workunit - a cumulative number of workunits completed so far

setInitialDelay

public final void setInitialDelay(int millis)

Set a custom initial delay for the progress task to appear in the status bar. This delay marks the time between starting of the progress handle and its appearance in the status bar. If it finishes earlier, it's not shown at all. There is a default < 1s value for this. If you want it to appear earlier or later, call this method with the value you prefer before starting the handle. (Has no effect if called after the handle is started.)

Progress bars that are placed in custom dialogs do always appear right away without a delay.

Parameters:

millis - number of miliseconds to wait before the progress appears in status bar.

Since:

org.netbeans.api.progress/1 1.2

setDisplayName

public final void setDisplayName(String newDisplayName)

Change the display name of the progress task. Use with care, please make sure the changed name is not completely different, or otherwise it might appear to the user as a different task.

Parameters:

newDisplayName - a new name to set for the task

Since:

org.netbeans.api.progress 1.5

addDefaultAction

public final boolean addDefaultAction(Action action)

Adds an action to the progress indicator.

Parameters:

action - describes the action

Returns:

true, if actions are supported by the progress implementation.

Since:

1.59