package org.gudy.azureus2.ui.swt.progress; import org.eclipse.swt.graphics.Image; /** * The interface for a progress reporter * @author knguyen * */ public interface IProgressReporter extends Comparable { /** * 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 * @param reporterType */ public void setReporterType(String reporterType); /** * Disposes any resources or listeners that this reporter has references to or otherwise is responsible for * <p>Also removes it from the global <code>ProgressReportingManager</code> so that any subsequent event * from this reporter is no longer forwarded </p> */ public void dispose(); /** * Returns an <code>IProgressReport</code> which is a snapshot of this reporter * <p> * * <b>NOTE</b>: Each call to this method creates a new snapshot therefore the correct * usage pattern is:</p> * <pre> * * IProgressReport report = getProgressReport(); * if( report.isDone() == false ){ * // Do something * { * else if( report.isCanceled() == false ){ * // Do something else * { * ... * * </pre> * It may be tempting to use the less verbose pattern by repeatedly calling this * method directly such as: * <pre> * * if( getProgressReport().isDone == false ){ * // Do something * { * else if( getProgressReport().isCanceled == false ){ * // Do something else * { * * </pre> * * BUT this can produce inconsistent results since each successive call to getProgressReport() * is returning a different snapshot. * * * @return */ public IProgressReport getProgressReport(); /** * Sets the <code>selection</code> to the progress reporter; this is used when a traditional min, max, selection is specified. * <p><b>NOTE: </b> this selection value also synchronize the <code>percentage</code> value of this reporter</p> * @param selection * @param message */ public void setSelection(int selection, String message); /** * Sets the <code>percentage</code> value to the progress reporter; this is used when a simple percentage is specified as opposed to setting min, max, and selection. * <p><b>NOTE: </b> this percentage value also synchronize the <code>selection</code> value of this reporter</p> * @param percentage an integer from 0-100 * @param message a textual message to display; <code>null</code> to leave the previous message untouched, empty String to clear any previous message */ public void setPercentage(int percentage, String message); /** * 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 * @param isIndeterminate */ public void setIndeterminate(boolean isIndeterminate); /** * Indicates that the associated process is done */ public void setDone(); /** * @param min the min to set */ public void setMinimum(int min); /** * @param max the max to set */ public void setMaximum(int max); /** * Marks this reporter as canceled and notify any listeners about it * <p><b>NOTE: </b> 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 */ public void cancel(); /** * Notifies listener that a retry is requested */ public void retry(); /** * 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 <code>true</code> the manager may * enable a UI component allowing the user to cancel the associated process if appropriate. * <P>The holder of this reporter can register a listener to receive the cancel event</p> * @see #addListener(IProgressReporterListener) * @see #removeListener(IProgressReporterListener) * * @param cancelAllowed <code>true</code> to indicate that this process may solicit a <code>REPORT_TYPE_CANCEL</code> input from the user; * default is <code>false</code> */ public void setCancelAllowed(boolean cancelAllowed); /** * * @param listener */ public void addListener(IProgressReporterListener listener); /** * * @param listener */ public void removeListener(IProgressReporterListener listener); /** * @param 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 <code>null</code>. */ public void setName(String name); /** * Sets the title that may be used by a UI component. * A typical usage would be for the title of a progress dialog * @param title the title to set */ public void setTitle(String title); /** * Sets the image corresponding to this reporter; this image may be used by the UI to decorate this reporter * <p><b>NOTE</b>: 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</p> * @param image the image; may be <code>null</code> */ public void setImage(Image image); /** * Sets an error message to this reporter; subsequently <code>isInErrorState</code> will be set to <code>true</code> * @see #reInit() * @param errorMessage */ public void setErrorMessage(String errorMessage); /** * Sets the current status message for this reporter; this is typically used to display a message at each incremental update * @param message a textual message */ public void setMessage(String message); /** * 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 <code>null</code>)or show the regular message in its place * * <p>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</p> * @param detailMessage */ public void appendDetailMessage(String detailMessage); /** * This is a hint to any UI components displaying this reporter * to determine if the user should be prompted to retry on error * @param isRetryAllowed <code>true</code> if the user should be prompted to retry when an error has occurred; <code>false</code> otherwise. Default is <code>false</code> */ public void setRetryAllowed(boolean retryOnError); /** * An arbitrary object reference that can be used to further identify the reporter. * This object is also accessible to listeners of the reporter through {@link ProgressReporter.ProgressReport#objectData} * so that it can be used to pass information to and from the listeners. * @param objectData the objectData to set */ public void setObjectData(Object objectData); /** * Returns an array of <code>IMessage</code>'s that has been generated since the reporter was created * @return */ public IMessage[] getMessageHistory(); }