org.gudy.azureus2.ui.swt.progress
Interface IProgressReporter

All Superinterfaces:
Comparable
All Known Implementing Classes:
ProgressReporter

public interface IProgressReporter
extends Comparable

The interface for a progress reporter

Author:
knguyen

Method Summary
 void addListener(IProgressReporterListener listener)
           
 void appendDetailMessage(String detailMessage)
          Appends the detail message to this reporter.
 void cancel()
          Marks this reporter as canceled and notify any listeners about it
 void dispose()
          Disposes any resources or listeners that this reporter has references to or otherwise is responsible for
 boolean getCancelCloses()
           
 IMessage[] getMessageHistory()
          Returns an array of IMessage's that has been generated since the reporter was created
 IProgressReport getProgressReport()
          Returns an IProgressReport which is a snapshot of this reporter
 void removeListener(IProgressReporterListener listener)
           
 void retry()
          Notifies listener that a retry is requested
 void 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 done
 void setErrorMessage(String errorMessage)
          Sets an error message to this reporter; subsequently isInErrorState will be set to true
 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 reporter
 void 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(String message)
          Sets the current status message for this reporter; this is typically used to display a message at each incremental update
 void setMinimum(int min)
           
 void setName(String name)
           
 void setObjectData(Object objectData)
          An arbitrary object reference that can be used to further identify the reporter.
 void setPercentage(int percentage, String message)
          Sets the percentage value to the progress reporter; this is used when a simple percentage is specified as opposed to setting min, max, and selection.
 void setReporterType(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 error
 void setSelection(int selection, String message)
          Sets the selection to the progress reporter; this is used when a traditional min, max, selection is specified.
 void setTitle(String title)
          Sets the title that may be used by a UI component.
 
Methods inherited from interface java.lang.Comparable
compareTo
 

Method Detail

setReporterType

void setReporterType(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 for

Also removes it from the global ProgressReportingManager so that any subsequent event from this reporter is no longer forwarded


getProgressReport

IProgressReport getProgressReport()
Returns an IProgressReport which is a snapshot of this reporter

NOTE: 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,
                  String message)
Sets the selection 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,
                   String message)
Sets the percentage 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-100
message - 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 it

NOTE: 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 to true 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 a REPORT_TYPE_CANCEL input from the user; default is false
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(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 be null.

setTitle

void setTitle(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 reporter

NOTE: 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 be null

setErrorMessage

void setErrorMessage(String errorMessage)
Sets an error message to this reporter; subsequently isInErrorState will be set to true

Parameters:
errorMessage -
See Also:
#reInit()

setMessage

void setMessage(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(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's null)or show the regular message in its place

Additionally 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 is false

setObjectData

void setObjectData(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 through ProgressReporter.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 of IMessage's that has been generated since the reporter was created

Returns: