# Class CompositeProgressListener

java.lang.Object
jebl.util.ProgressListener
jebl.util.CompositeProgressListener

All Implemented Interfaces:
  `Cancelable`

public final class CompositeProgressListener extends ProgressListener
A `ProgressListener` that is suitable for a task that consists of several subtasks. You specify the relative duration of each subtask, and then the subtasks' setProgress() calls with values between 0 and 1 are translated to reflect the overall progress on the whole (combined) task. In other words, each subtask reports progress as if it were the whole task, and the CompositeProgressListener translates this into overall progress. This also implies that calling `setComplete()` or `setProgress(1.0)` marks the current subtask rather than the entire task completed.

As the combined progress listener cannot know which subtask it is currently being called from, you have to explicitely let it know when a new subtask (not the first) starts, by calling `beginNextSubtask()`. Thus when the constructor is passed an array of N doubles as its second argument, `beginNextSubtask()` should be called precisely N-1 times.

Alternatively, instead of calling `beginNextSubtask()` after each subtask (except the last), you can instead call `beginSubtask()` before each subtask (including the first).

Version:
  $Id: CompositeProgressListener.java 1068 2010-09-08 23:59:59Z matt_kearse $
Author:
  Tobias Thierer

## Nested Class Summary

### Nested classes/interfaces inherited from class ProgressListener

`ProgressListener.Wrapper`

## Field Summary

### Fields inherited from class ProgressListener

`EMPTY`

## Constructor Summary

Constructors
Constructor
Description
`CompositeProgressListener(ProgressListener listener, double... operationDuration)`
construct a new composite ProgressListener.
`CompositeProgressListener(ProgressListener listener, int numberOfEvenlyWeightedSubTasks)`
Construct a CompositeProgressListener with a number of evenly weighted subtasks.

## 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)`
`boolean`
`addProgress(double fractionCompletedDiff)`
Increments the progress of the current sub task by this much.
`void`
`beginNextSubtask()`
begins the next subtask.
`void`
`beginNextSubtask(String message)`
Convenience method to start the next operation AND set a new message.
`void`
`beginSubtask()`
Used as an alternative to `beginNextSubtask()`.
`void`
`beginSubtask(String message)`
Used as an alternative to `beginNextSubtask()`.
`void`
`clearAllProgress()`
Clear all progress, including that of previous subtasks.
`static CompositeProgressListener`
`forFiles(ProgressListener listener, List<File> files)`
`ProgressListener`
`getRootProgressListener()`
`boolean`
`hasNextSubtask()`
`boolean`
`isCanceled()`
This method must be implemented by all subclasses.
`void`
`removeFeedbackAction(String label)`
Removes a feedback action previously added using `ProgressListener.addFeedbackAction(String, jebl.util.SimpleListener)`.
`final boolean`
`setComplete()`
`void`
`setTitle(String title)`
Sets a title associated with whatever is being done.

### Methods inherited from class ProgressListener

`setImage, setIndeterminateProgress, setMessage, setProgress, setProgress, setProgress`

### Methods inherited from class Object

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

## Constructor Details

### CompositeProgressListener

public CompositeProgressListener(ProgressListener listener, double... operationDuration)
construct a new composite ProgressListener.

Parameters:
  `listener` - the ProgressListener that all progress reports are forwarded to after adjusting them for the currently active sub-task
  `operationDuration` - a list of relative weightings to give each sub task.

### CompositeProgressListener

public CompositeProgressListener(ProgressListener listener, int numberOfEvenlyWeightedSubTasks)
Construct a CompositeProgressListener with a number of evenly weighted subtasks.

Parameters:
  `listener` - the ProgressListener that all progress reports are forwarded to after adjusting them for the currently active sub-task
  `numberOfEvenlyWeightedSubTasks` - the number of evenly weighted sub-tasks.

## Method Details

### forFiles

public static CompositeProgressListener forFiles(ProgressListener listener, List<File> files)

### beginSubtask

public void beginSubtask()
Used as an alternative to `beginNextSubtask()`. Instead of calling `beginNextSubtask()` once after each subtask (except the last), you can instead call beginSubTask at the beginning of every subtask including the first.

### beginSubtask

public void beginSubtask(String message)
Used as an alternative to `beginNextSubtask()`. Instead of calling `beginNextSubtask()` once after each subtask (except the last), you can instead call beginSubTask at the beginning of every subtask including the first.

Parameters:
  `message` - a message to be displayed to the user as a prefix in the progress message

### isCanceled

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

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

### addProgress

public boolean addProgress(double fractionCompletedDiff)
Increments the progress of the current sub task by this much. Using this method is generally a bad idea. Use `ProgressListener.setProgress(double)` instead.

Parameters:
  `fractionCompletedDiff` - the amount ot increase the current progress by between 0 and 1.
Returns:
  true if canceled.

### hasNextSubtask

public boolean hasNextSubtask()

Returns:
  true if there is another subtask available after the current one

### clearAllProgress

public void clearAllProgress()
Clear all progress, including that of previous subtasks. Note: if the task has already been canceled, this does not reset its status to non-canceled.

### beginNextSubtask

public void beginNextSubtask(String message)
Convenience method to start the next operation AND set a new message.

Parameters:
  `message` - message to set (will be passed to setMessage()

### beginNextSubtask

public void beginNextSubtask()
begins the next subtask. Should not be called on the first subtask, but should only be called to start tasks after the first one. If you wish to call a begin subtask method for each task including the first, use `beginSubtask()` instead.

### setComplete

public final boolean setComplete()

### getRootProgressListener

public ProgressListener getRootProgressListener()

Returns:
  The root `ProgressListener` that this forwards adjusted progress reports to.

### addFeedbackAction

public void addFeedbackAction(String label, SimpleListener listener)
Description copied from class: `ProgressListener`
Equivalent to `addFeedbackAction(label,"",listener)`

Overrides:
  `addFeedbackAction` in class `ProgressListener`

### addFeedbackAction

public void addFeedbackAction(String label, String description, SimpleListener listener)
Description copied from class: `ProgressListener`
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.

Overrides:
  `addFeedbackAction` in class `ProgressListener`
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)
Description copied from class: `ProgressListener`
Removes a feedback action previously added using `ProgressListener.addFeedbackAction(String, jebl.util.SimpleListener)`.

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

### setTitle

public void setTitle(String title)
Description copied from class: `ProgressListener`
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.

Overrides:
  `setTitle` in class `ProgressListener`
Parameters:
  `title` - the title of a progress window (if any). Must not be null.