Package org.openstreetmap.josm.gui.progress

Interface ProgressMonitor

All Known Implementing Classes:

AbstractProgressMonitor, ChildProgress, CLIProgressMonitor, NullProgressMonitor, PleaseWaitProgressMonitor, SplashScreen.SplashProgressMonitor, SwingRenderingProgressMonitor

public interface ProgressMonitor

An interface for displaying the progress of a task.

Typical use case is:

   monitor.beginTask()
   try {
     .. do some work
     monitor.worked()
     monitor.subTask()/monitor.intermediateTask()
     .. do some work
     monitor.worked()
   } finally {
     monitor.finishTask();
   }
 

subTask(String) and indeterminateSubTask(String) has nothing to do with logical structure of the work, they just show task title to the user.

If task consists of multiple tasks then createSubTaskMonitor(int, boolean) may be used. It will create new ProgressMonitor, then can be passed to the subtask. Subtask doesn't know whether it runs standalone or as a part of other task. Progressbar will be updated so that total progress is shown, not just progress of the subtask

All ProgressMonitor implementations should be thread safe.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ProgressMonitor.CancelListener	A listener that listens to cancel events on the progress monitor

Field Summary

Fields

Modifier and Type	Field	Description
static int	ALL_TICKS	Can be used with worked(int) and createSubTaskMonitor(int, boolean) to express that the task should use all remaining ticks
static int	DEFAULT_TICKS	Ticks count used, when no other value is supplied

Method Summary

Modifier and Type	Method	Description
void	addCancelListener(ProgressMonitor.CancelListener listener)	Add listener for user abort action
void	appendLogMessage(java.lang.String message)	Appends a message to the log managed by the progress monitor.
void	beginTask(java.lang.String title)	Starts this progress monitor.
void	beginTask(java.lang.String title, int ticks)	Starts this progress monitor.
void	cancel()	Abort current operation, usually called when user somehow requested an abort
ProgressMonitor	createSubTaskMonitor(int ticks, boolean internal)	Creates subtasks monitor.
void	finishTask()	Finish this progress monitor, close the dialog or inform the parent progress monitor that it can continue with other tasks.
ProgressTaskId	getProgressTaskId()	Returns the task ID of the progress dialog Should be used only by PleaseWaitRunnable
int	getTicks()	Get the current number of work units
int	getTicksCount()	Get the total number of work units
java.awt.Component	getWindowParent()	Return the parent windows of progress dialog
void	indeterminateSubTask(java.lang.String title)	Subtask that will show progress running back and forth
void	invalidate()	Can be used if method receives ProgressMonitor, but it's not interested progress monitoring.
boolean	isCanceled()	Returns the state of user aborts
void	removeCancelListener(ProgressMonitor.CancelListener listener)	Remove listener for user abort action
void	setCustomText(java.lang.String text)	Shows additional text
void	setExtraText(java.lang.String text)	Show extra text after normal task title.
void	setProgressTaskId(ProgressTaskId taskId)	Set the task ID of the progress dialog Should be used only by PleaseWaitRunnable.
void	setTicks(int ticks)	Set the current number of work units
void	setTicksCount(int ticks)	Set the total number of work units
void	subTask(java.lang.String title)	Normal subtask
void	worked(int ticks)	Increase number of already done work units by ticks

Field Detail

DEFAULT_TICKS

static final int DEFAULT_TICKS

Ticks count used, when no other value is supplied

See Also:

Constant Field Values

ALL_TICKS

static final int ALL_TICKS

Can be used with worked(int) and createSubTaskMonitor(int, boolean) to express that the task should use all remaining ticks

See Also:

Constant Field Values

Method Detail

beginTask

void beginTask(java.lang.String title)

Starts this progress monitor. Must be called exactly once Ticks count is set to default value

Parameters:

title - title text of the task

beginTask

void beginTask(java.lang.String title,
               int ticks)

Starts this progress monitor. Must be called exactly once

Parameters:

title - title text of the task

ticks - number of work units (see setTicksCount(int ticks))

finishTask

void finishTask()

Finish this progress monitor, close the dialog or inform the parent progress monitor that it can continue with other tasks. Must be called at least once (if called multiply times then further calls are ignored)

invalidate

void invalidate()

Can be used if method receives ProgressMonitor, but it's not interested progress monitoring. Basically replaces beginTask(String) and finishTask() This method can be also used in finally section if method expects that some exceptions might prevent it from passing progressMonitor away. If beginTask(String) was already called then this method does nothing.

setTicksCount

void setTicksCount(int ticks)

Set the total number of work units

Parameters:

ticks - Number of total work units

getTicksCount

int getTicksCount()

Get the total number of work units

Returns:

Number of total work units

setTicks

void setTicks(int ticks)

Set the current number of work units

Parameters:

ticks - Number of work units already done

getTicks

int getTicks()

Get the current number of work units

Returns:

Number of work units already done

worked

void worked(int ticks)

Increase number of already done work units by ticks

Parameters:

ticks - number of ticks to add

indeterminateSubTask

void indeterminateSubTask(java.lang.String title)

Subtask that will show progress running back and forth

Parameters:

title - Can be null, in that case task title is not changed

subTask

void subTask(java.lang.String title)

Normal subtask

Parameters:

title - Can be null, in that case task title is not changed

setCustomText

void setCustomText(java.lang.String text)

Shows additional text

Parameters:

text - custom text

setExtraText

void setExtraText(java.lang.String text)

Show extra text after normal task title. Hack for ProgressInputStream to show number of kB already downloaded

Parameters:

text - extra text

createSubTaskMonitor

ProgressMonitor createSubTaskMonitor(int ticks,
                                     boolean internal)

Creates subtasks monitor.

Parameters:

ticks - Number of work units that should be done when subtask finishes

internal - If true then subtask can't modify task title/custom text

Returns:

subtasks monitor

isCanceled

boolean isCanceled()

Returns the state of user aborts

Returns:

true if user aborted operation

cancel

void cancel()

Abort current operation, usually called when user somehow requested an abort

addCancelListener

void addCancelListener(ProgressMonitor.CancelListener listener)

Add listener for user abort action

Parameters:

listener - the listener for cancel operation

removeCancelListener

void removeCancelListener(ProgressMonitor.CancelListener listener)

Remove listener for user abort action

Parameters:

listener - the listener for cancel operation

appendLogMessage

void appendLogMessage(java.lang.String message)

Appends a message to the log managed by the progress monitor.

Parameters:

message - the log message. Ignored if null or white space only.

setProgressTaskId

void setProgressTaskId(ProgressTaskId taskId)

Set the task ID of the progress dialog Should be used only by PleaseWaitRunnable. If taskId <> null then "In background" button will be shown

Parameters:

taskId - the task ID

getProgressTaskId

ProgressTaskId getProgressTaskId()

Returns the task ID of the progress dialog Should be used only by PleaseWaitRunnable

Returns:

the task ID

getWindowParent

java.awt.Component getWindowParent()

Return the parent windows of progress dialog

Returns:

component suitable as parent for dialogs that wants to be shown in front of progress dialog