Interface IProgressReporter
-
- All Superinterfaces:
java.lang.Comparable
- All Known Implementing Classes:
ProgressReporter
public interface IProgressReporter extends java.lang.Comparable
The interface for a progress reporter
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addListener(IProgressReporterListener listener)
void
appendDetailMessage(java.lang.String detailMessage)
Appends the detail message to this reporter.void
cancel()
Marks this reporter as canceled and notify any listeners about itvoid
dispose()
Disposes any resources or listeners that this reporter has references to or otherwise is responsible forboolean
getCancelCloses()
IMessage[]
getMessageHistory()
Returns an array ofIMessage
's that has been generated since the reporter was createdIProgressReport
getProgressReport()
Returns anIProgressReport
which is a snapshot of this reportervoid
removeListener(IProgressReporterListener listener)
void
retry()
Notifies listener that a retry is requestedvoid
setCancelAllowed(boolean cancelAllowed)
Sets whether the process associated with this reporter is allowed to be canceled by the user.void
setCancelCloses(boolean cancelCloses)
void
setDone()
Indicates that the associated process is donevoid
setErrorMessage(java.lang.String errorMessage)
Sets an error message to this reporter; subsequentlyisInErrorState
will be set totrue
void
setImage(org.eclipse.swt.graphics.Image image)
Sets the image corresponding to this reporter; this image may be used by the UI to decorate this reportervoid
setIndeterminate(boolean isIndeterminate)
Set this reporter into indeterminate mode; use this when an accurate ratio of amount of work done vs.void
setMaximum(int max)
void
setMessage(java.lang.String message)
Sets the current status message for this reporter; this is typically used to display a message at each incremental updatevoid
setMinimum(int min)
void
setName(java.lang.String name)
void
setObjectData(java.lang.Object objectData)
An arbitrary object reference that can be used to further identify the reporter.void
setPercentage(int percentage, java.lang.String message)
Sets thepercentage
value to the progress reporter; this is used when a simple percentage is specified as opposed to setting min, max, and selection.void
setReporterType(java.lang.String reporterType)
Sets the type of a reporter.void
setRetryAllowed(boolean retryOnError)
This is a hint to any UI components displaying this reporter to determine if the user should be prompted to retry on errorvoid
setSelection(int selection, java.lang.String message)
Sets theselection
to the progress reporter; this is used when a traditional min, max, selection is specified.void
setTitle(java.lang.String title)
Sets the title that may be used by a UI component.
-
-
-
Method Detail
-
setReporterType
void setReporterType(java.lang.String reporterType)
Sets the type of a reporter. This is a user defined property and no duplication check is ensured. This optional property can be used to identify particular types of reports so that report consumers have a way to ignore uninteresting report types- Parameters:
reporterType
-
-
dispose
void dispose()
Disposes any resources or listeners that this reporter has references to or otherwise is responsible forAlso removes it from the global
ProgressReportingManager
so that any subsequent event from this reporter is no longer forwarded
-
getProgressReport
IProgressReport getProgressReport()
Returns anIProgressReport
which is a snapshot of this reporterNOTE: Each call to this method creates a new snapshot therefore the correct usage pattern is:
IProgressReport report = getProgressReport(); if( report.isDone() == false ){ // Do something { else if( report.isCanceled() == false ){ // Do something else { ...
It may be tempting to use the less verbose pattern by repeatedly calling this method directly such as:if( getProgressReport().isDone == false ){ // Do something { else if( getProgressReport().isCanceled == false ){ // Do something else {
BUT this can produce inconsistent results since each successive call to getProgressReport() is returning a different snapshot.- Returns:
-
setSelection
void setSelection(int selection, java.lang.String message)
Sets theselection
to the progress reporter; this is used when a traditional min, max, selection is specified.NOTE: this selection value also synchronize the
percentage
value of this reporter- Parameters:
selection
-message
-
-
setPercentage
void setPercentage(int percentage, java.lang.String message)
Sets thepercentage
value to the progress reporter; this is used when a simple percentage is specified as opposed to setting min, max, and selection.NOTE: this percentage value also synchronize the
selection
value of this reporter- Parameters:
percentage
- an integer from 0-100message
- a textual message to display;null
to leave the previous message untouched, empty String to clear any previous message
-
setIndeterminate
void setIndeterminate(boolean isIndeterminate)
Set this reporter into indeterminate mode; use this when an accurate ratio of amount of work done vs. total amount of work can not be calculated- Parameters:
isIndeterminate
-
-
setDone
void setDone()
Indicates that the associated process is done
-
setMinimum
void setMinimum(int min)
- Parameters:
min
- the min to set
-
setMaximum
void setMaximum(int max)
- Parameters:
max
- the max to set
-
cancel
void cancel()
Marks this reporter as canceled and notify any listeners about itNOTE: This is only a hint back to the processes listening to this reporter; it is up to that process to determine the correct course of action in response to this flag
-
retry
void retry()
Notifies listener that a retry is requested
-
setCancelAllowed
void setCancelAllowed(boolean cancelAllowed)
Sets whether the process associated with this reporter is allowed to be canceled by the user. This serves as a hint to the progress manager handling this reporter. If set totrue
the manager may enable a UI component allowing the user to cancel the associated process if appropriate.The holder of this reporter can register a listener to receive the cancel event
- Parameters:
cancelAllowed
-true
to indicate that this process may solicit aREPORT_TYPE_CANCEL
input from the user; default isfalse
- See Also:
addListener(IProgressReporterListener)
,removeListener(IProgressReporterListener)
-
setCancelCloses
void setCancelCloses(boolean cancelCloses)
-
getCancelCloses
boolean getCancelCloses()
-
addListener
void addListener(IProgressReporterListener listener)
- Parameters:
listener
-
-
removeListener
void removeListener(IProgressReporterListener listener)
- Parameters:
listener
-
-
setName
void setName(java.lang.String name)
- Parameters:
name
- a textual name to identify the process this reporter represents; need not be unique (should not be used as a lookup key), and may benull
.
-
setTitle
void setTitle(java.lang.String title)
Sets the title that may be used by a UI component. A typical usage would be for the title of a progress dialog- Parameters:
title
- the title to set
-
setImage
void setImage(org.eclipse.swt.graphics.Image image)
Sets the image corresponding to this reporter; this image may be used by the UI to decorate this reporterNOTE: Though not strictly required (nor enforced) the image should be 32X32 pixels with transparency. If not then cropping or enlargement may be applied as required by the particular UI
- Parameters:
image
- the image; may benull
-
setErrorMessage
void setErrorMessage(java.lang.String errorMessage)
Sets an error message to this reporter; subsequentlyisInErrorState
will be set totrue
- Parameters:
errorMessage
-- See Also:
#reInit()
-
setMessage
void setMessage(java.lang.String message)
Sets the current status message for this reporter; this is typically used to display a message at each incremental update- Parameters:
message
- a textual message
-
appendDetailMessage
void appendDetailMessage(java.lang.String detailMessage)
Appends the detail message to this reporter. This is typically a more verbose message that is optionally displayed by the UI. This is an optional property so UI components displaying this can decide to show nothing for it (if it'snull
)or show the regular message in its placeAdditionally this is an appending message so that reporters can send smaller units of the message rather than having to store and send the entire (and ever increasing) messages for each update
- Parameters:
detailMessage
-
-
setRetryAllowed
void setRetryAllowed(boolean retryOnError)
This is a hint to any UI components displaying this reporter to determine if the user should be prompted to retry on error- Parameters:
isRetryAllowed
-true
if the user should be prompted to retry when an error has occurred;false
otherwise. Default isfalse
-
setObjectData
void setObjectData(java.lang.Object objectData)
An arbitrary object reference that can be used to further identify the reporter. This object is also accessible to listeners of the reporter throughProgressReporter.ProgressReport.objectData
so that it can be used to pass information to and from the listeners.- Parameters:
objectData
- the objectData to set
-
getMessageHistory
IMessage[] getMessageHistory()
Returns an array ofIMessage
's that has been generated since the reporter was created- Returns:
-
-