Package jebl.util

# Class ProgressListener

java.lang.Object
jebl.util.ProgressListener

All Implemented Interfaces:
  `Cancelable`

Direct Known Subclasses:
  `BasicProgressListener`, `CompositeProgressListener`, `ProgressListener.Wrapper`

public abstract class ProgressListener extends Object implements Cancelable

Version:
  $Id: ProgressListener.java 1068 2010-09-08 23:59:59Z matt_kearse $ ProgressListener guarantees the following contract: A call to any of the methods setProgress(), setMessage(), isCanceled() and setIndeterminateProgress() at a given time yields the same result as a call to another of these methods would have resulted at the same time. Once the task whose progress we are observing has been canceled, calls to either of these methods reflect this. This does not prevent subclasses from introducing a way to "reset" a ProgressListener that was previously canceled from not being canceled any more. Any object may exhibit undefined behaviour when dealing with a ProgressListener that is not fulfilling this contract.
Author:
  Matt Kearse

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`ProgressListener.Wrapper`
A decorator progress listener which delegates all method calls to an internal progress listener.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final ProgressListener`
`EMPTY`
A ProgressListener that ignores all events and always returns false from `isCanceled()`.

## Constructor Summary

Constructors
Constructor
Description
`ProgressListener()`

## Method Summary

Modifier and Type
Method
Description
`void`
`addFeedbackAction(String label, String description, SimpleListener listener)`
Adds an action that can choose to provide feedback.
`void`
`addFeedbackAction(String label, SimpleListener listener)`
Equivalent to `addFeedbackAction(label,"",listener)`
`abstract boolean`
`isCanceled()`
This method must be implemented by all subclasses.
`void`
`removeFeedbackAction(String label)`
Removes a feedback action previously added using `addFeedbackAction(String, jebl.util.SimpleListener)`.
`final boolean`
`setImage(Image image)`
Set an image associated with the current progress.
`final boolean`
`setIndeterminateProgress()`
Sets indefinite progress (i.e.
`final boolean`
`setMessage(String message)`
Set visible user message.
`final boolean`
`setProgress(double fractionCompleted)`
`final boolean`
`setProgress(int currentStep, int numberOfSteps)`
Same as calling `setProgress(((double)currentStep)/numberOfSteps)`
`final boolean`
`setProgress(long currentStep, long numberOfSteps)`
Same as calling `setProgress(((double)currentStep)/numberOfSteps)`
`void`
`setTitle(String title)`
Sets a title associated with whatever is being done.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### EMPTY

public static final ProgressListener EMPTY
A ProgressListener that ignores all events and always returns false from `isCanceled()`. Useful when you don't care about the progress results or canceling the operation.

## Constructor Details

### ProgressListener

public ProgressListener()

## Method Details

### setProgress

public final boolean setProgress(double fractionCompleted)

Parameters:
  `fractionCompleted` - a number between 0 and 1 inclusive representing the fraction of the operation completed. If you are unsure of the fraction completed, call `setIndeterminateProgress()` instead.
Returns:
  true if the user has requested that this operation be canceled.

### setProgress

public final boolean setProgress(int currentStep, int numberOfSteps)
Same as calling `setProgress(((double)currentStep)/numberOfSteps)`

Parameters:
  `currentStep` - between 0 and numberOfSteps inclusive
  `numberOfSteps` - the total number of steps. Must be greater than 0.
Returns:
  true if the user has requested that this operation be canceled.

### setProgress

public final boolean setProgress(long currentStep, long numberOfSteps)
Same as calling `setProgress(((double)currentStep)/numberOfSteps)`

Parameters:
  `currentStep` - between 0 and numberOfSteps inclusive
  `numberOfSteps` - the total number of steps. Must be greater than 0.
Returns:
  true if the user has requested that this operation be canceled.

### setIndeterminateProgress

public final boolean setIndeterminateProgress()
Sets indefinite progress (i.e. "some progress has happened, but I don't know how close we are to finishing").

Returns:
  true if the user has requested that this operation be canceled.

### setMessage

public final boolean setMessage(String message)
Set visible user message.

Parameters:
  `message` - a user visible message. If this is null, it will be automatically replaced with an empty string.
Returns:
  true if the user has requested that this operation be canceled.

### setImage

public final boolean setImage(Image image)
Set an image associated with the current progress. A progress listener may choose to optionally display this image wherever is appropriate.

Parameters:
  `image` - an image
Returns:
  true if the user has requested that this operation be canceled.

### addFeedbackAction

public void addFeedbackAction(String label, SimpleListener listener)
Equivalent to `addFeedbackAction(label,"",listener)`

### addFeedbackAction

public void addFeedbackAction(String label, String description, SimpleListener listener)
Adds an action that can choose to provide feedback. For example, an operation may choose to provide a "Skip to next step" button alongside the cancel button. There is no requirement that a ProgressListener actually present this to the user - it may choose to ignore this method, in which case `listener` will never be fired.

Parameters:
  `label` - a label describing this feedback action. For example, "Skip to next step"
  `listener` - a listener to be notified when the user chooses to invoke this action

### removeFeedbackAction

public void removeFeedbackAction(String label)
Removes a feedback action previously added using `addFeedbackAction(String, jebl.util.SimpleListener)`.

Parameters:
  `label` - The label used as a parameter to `addFeedbackAction(String, jebl.util.SimpleListener)`

### setTitle

public void setTitle(String title)
Sets a title associated with whatever is being done. This will not necessarily even be presented to the user, but typically will be presented as the title of a progress window.

Parameters:
  `title` - the title of a progress window (if any). Must not be null.

### isCanceled

public abstract boolean isCanceled()
This method must be implemented by all subclasses. It is called from `setProgress(double)`, `setIndeterminateProgress()` and `setMessage(java.lang.String)` to determine the return value of these methods.

Specified by:
  `isCanceled` in interface `Cancelable`
Returns:
  true if the user has requested that this operation be canceled.