Module aya.ij.parsing.core

Package com.intellij.openapi.progress

Interface ProgressIndicator

public interface ProgressIndicator

An object accompanying a computation, usually in a background thread. It allows to display process status to the user (setText(java.lang.String), setText2(java.lang.String), setFraction(double), setIndeterminate(boolean)) and interrupt if the computation is canceled (#checkCanceled()).

There are many implementations which may implement only parts of the functionality in this interface. Some indicators are invisible, not showing any status to the user, but still tracking cancellation.

To run a task with a visible progress indicator, modal or displayed in the status bar, please use ProgressManager#run methods.

To associate a thread with a progress, use ProgressManager#runProcess methods. This is mostly used with invisible progress indicators for cancellation handling. A common case is to take a read action that's interrupted by a write action about to occur in the UI thread, to avoid UI freezes (see com.intellij.openapi.application.ReadAction#nonBlocking(Runnable)). Another common case is wrapping main thread's to parallelize the associated computation by forking additional threads.

Current thread's progress indicator, visible or not, can be retrieved with ProgressManager#getGlobalProgressIndicator().

Here are some commonly used implementations:

• EmptyProgressIndicator: invisible (ignores text/fraction-related methods), used only for cancellation tracking. Remembers its creation modality state.
• com.intellij.openapi.progress.util.ProgressIndicatorBase: invisible, but can be made visible by subclassing: remembers text/fraction inside and allows to retrieve them and possibly show in the UI. Non-modal by default.
• com.intellij.openapi.progress.util.ProgressWindow: visible progress, either modal or background. Usually not created directly, instantiated internally inside ProgressManager#run.
• com.intellij.openapi.progress.util.ProgressWrapper: wraps an existing progress indicator, usually to fork another thread with the same cancellation policy. Use com.intellij.concurrency.SensitiveProgressWrapper to allow that separate thread's indicator to be canceled independently from the main thread.

Method Summary

Modifier and Type	Method	Description
void	cancel()	Cancels the current process.
default void	finishNonCancelableSection()	Deprecated.
double	getFraction()
String	getText()
String	getText2()
boolean	isCanceled()
boolean	isIndeterminate()
boolean	isModal()
boolean	isPopupWasShown()	Usually invoked in the thread associated with this indicator, used to check if the computation performed by this thread has been canceled, and, if yes, stop it immediately (by throwing an exception).
boolean	isRunning()
boolean	isShowing()
void	popState()
void	pushState()
void	setFraction(double fraction)	Sets the fraction: a number between 0.0 and 1.0 reflecting the ratio of work that has already be done (0.0 for nothing, 1.0 for all).
void	setIndeterminate(boolean indeterminate)	Marks the progress indeterminate (for processes that can't estimate the amount of work to be done) or determinate (for processes that can display the fraction of the work done using setFraction(double)).
void	setModalityProgress(@Nullable ProgressIndicator modalityProgress)	In many implementations, grants to this progress indicator its own modality state.
void	setText(String text)	Sets text above the progress bar
void	setText2(String text)	Sets text under the progress bar
void	start()	Marks the process as started.
default void	startNonCancelableSection()	Deprecated.
void	stop()	Marks the process as finished.

Method Details

start

void start()

Marks the process as started. Invoked by ProgressManager internals, shouldn't be called from client code unless you know what you're doing.

stop

void stop()

Marks the process as finished. Invoked by ProgressManager internals, shouldn't be called from client code unless you know what you're doing.

isRunning

boolean isRunning()

Returns:

whether the computation associated with this progress indicator is currently running: started, not yet finished, but possibly already canceled.

cancel

void cancel()

Cancels the current process. Is usually invoked not by the process itself, but by some external activity: e.g. a handler for a "Cancel" button pressed by the user (for visible processes), or by some other event handler which recognizes that the process makes no sense.

isCanceled

boolean isCanceled()

Returns:

whether the process has been canceled. Usually #checkCanceled() is called instead.

See Also:

• cancel()

setText

void setText(String text)

Sets text above the progress bar

Parameters:

text - Text to set

See Also:

• setText2(String)

getText

String getText()

Returns:

text above the progress bar, set by setText(String)

setText2

void setText2(String text)

Sets text under the progress bar

Parameters:

text - Text to set

See Also:

• setText(String)

getText2

String getText2()

Returns:

text under the progress bar, set by setText2(String)

getFraction

double getFraction()

Returns:

current fraction, set by setFraction(double)

setFraction

void setFraction(double fraction)

Sets the fraction: a number between 0.0 and 1.0 reflecting the ratio of work that has already be done (0.0 for nothing, 1.0 for all). Only works for determinate indicator. The fraction should provide the user with rough estimation of the time left. If that's impossible, consider making the progress indeterminate.

See Also:

• setIndeterminate(boolean)

pushState

void pushState()

popState

void popState()

startNonCancelableSection

@Deprecated
default void startNonCancelableSection()

Deprecated.

use ProgressManager#executeNonCancelableSection(Runnable) instead

finishNonCancelableSection

@Deprecated
default void finishNonCancelableSection()

Deprecated.

use ProgressManager#executeNonCancelableSection(Runnable) instead

isModal

boolean isModal()

Returns:

whether this process blocks user activities while active, probably displaying a modal dialog.

See Also:

• setModalityProgress(ProgressIndicator)

setModalityProgress

void setModalityProgress(@Nullable
 @Nullable ProgressIndicator modalityProgress)

In many implementations, grants to this progress indicator its own modality state. Don't call unless you know what you're doing. Passing a non-null value can make this indicator modal (as in isModal(), which, if not accompanied by showing a modal dialog, might affect the whole IDE adversely: e.g. actions won't be executed, editor typing won't work, and all that with no visible indication.

isIndeterminate

boolean isIndeterminate()

Returns:

whether the progress is indeterminate and displays no fractions

setIndeterminate

void setIndeterminate(boolean indeterminate)

Marks the progress indeterminate (for processes that can't estimate the amount of work to be done) or determinate (for processes that can display the fraction of the work done using setFraction(double)).

isPopupWasShown

boolean isPopupWasShown()

Usually invoked in the thread associated with this indicator, used to check if the computation performed by this thread has been canceled, and, if yes, stop it immediately (by throwing an exception). Threads should call this frequently to allow for prompt cancellation. Failure to do this can cause UI freezes.

You might also want to use ProgressManager.checkCanceled() where you don't need to know current indicator and pass it around.

Throws:

ProcessCanceledException - if this progress has been canceled, i.e. isCanceled() returns true.

isShowing

boolean isShowing()