ImageScience 3.0.0

imagescience.utility
Class Progressor

java.lang.Object
  extended by imagescience.utility.Progressor

public class Progressor
extends java.lang.Object

Wrapper around ImageJ's progress bar. This class offers several advantages over ImageJ's native progress displaying methods. First, it allows to make sure the progress bar is always updated (repainting can be enforced) if displaying is enabled, even when it is used from within the event dispatching thread (in which case the bar - drawn within ImageJ using that same thread - would otherwise not be updated until the process using the bar is finished). Furthermore, it relieves the user of explicitly computing the progress percentage (all this class requires is the total number of steps before the start of a process and the same number of step calls during the process). Also, it allows to specify the number of progress updates (by default 20 from start to end), thereby limiting the number of repaint calls (which are relatively expensive), and thus reducing execution time for progress displaying. Finally, it allows specifying the progress range (the minimum / maximum displayed progress value for the start / end of the corresponding process), which facilitates progress displaying for subprocesses.


Constructor Summary
Progressor()
          Default constructor.
 
Method Summary
 boolean display()
          Indicates whether progress is displayed.
 void display(boolean enable)
          Determines whether progress is displayed.
 boolean enforce()
          Indicates whether repainting of the progress bar is enforced.
 void enforce(boolean enable)
          Determines whether repainting of the progress bar is enforced.
 double max()
          Returns the maximum displayed progress value.
 void max(double max)
          Specifies the maximum displayed progress value.
 double min()
          Returns the minimum displayed progress value.
 void min(double min)
          Specifies the minimum displayed progress value.
 Progressor parent()
          Returns the parent object for progress displaying.
 void parent(Progressor parent)
          Sets the parent object for progress displaying.
 void range(double min, double max)
          Specifies the minimum and maximum displayed progress value.
 void set(long n)
          Sets the internal step counter to the given value.
 void start()
          Starts the progress displaying.
 java.lang.String status()
          Returns the status message.
 void status(java.lang.String status)
          Sets the status message.
 void step()
          Increases the internal step counter.
 void step(long n)
          Increases the internal step counter by the given amount.
 long steps()
          Returns the number of steps in the process.
 void steps(long n)
          Specifies the number of steps in the process.
 void stop()
          Stops the progress displaying.
 long updates()
          Returns the number of progress updates displayed by the progress bar.
 void updates(long n)
          Specifies the number of progress updates displayed by the progress bar.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Progressor

public Progressor()
Default constructor.

Method Detail

updates

public void updates(long n)
Specifies the number of progress updates displayed by the progress bar. The default number of updates is 20.

Parameters:
n - The number of progress updates displayed by the progress bar.
Throws:
java.lang.IllegalArgumentException - If n is less than 0.

updates

public long updates()
Returns the number of progress updates displayed by the progress bar.

Returns:
The number of progress updates displayed by the progress bar.

steps

public void steps(long n)
Specifies the number of steps in the process.

Parameters:
n - The number of steps in the process.
Throws:
java.lang.IllegalArgumentException - If n is less than 0.

steps

public long steps()
Returns the number of steps in the process.

Returns:
The number of steps in the process.

step

public void step()
Increases the internal step counter.


step

public void step(long n)
Increases the internal step counter by the given amount.

Parameters:
n - The number of steps to be added to the internal step counter.
Throws:
java.lang.IllegalArgumentException - If n is less than 0.

set

public void set(long n)
Sets the internal step counter to the given value.

Parameters:
n - The value to set the internal step counter to.
Throws:
java.lang.IllegalArgumentException - If n is less than 0.

min

public void min(double min)
Specifies the minimum displayed progress value. The default minimum is 0.

Parameters:
min - The minimum displayed progress value.
Throws:
java.lang.IllegalArgumentException - If min is less than 0 or larger than the maximum displayed progress value.

min

public double min()
Returns the minimum displayed progress value. If a parent object has been set using parent(Progressor), the returned value is the minimum of the present object, mapped to the progress range of the parent. This recurses through all layers of parenthood.

Returns:
The minimum displayed progress value.

max

public void max(double max)
Specifies the maximum displayed progress value. The default maximum is 1.

Parameters:
max - The maximum displayed progress value.
Throws:
java.lang.IllegalArgumentException - If max is larger than 1 or less than the minimum displayed progress value.

max

public double max()
Returns the maximum displayed progress value. If a parent object has been set using parent(Progressor), the returned value is the maximum of the present object, mapped to the progress range of the parent. This recurses through all layers of parenthood.

Returns:
The maximum displayed progress value.

range

public void range(double min,
                  double max)
Specifies the minimum and maximum displayed progress value. The default minimum is 0 and the default maximum is 1.

Parameters:
min - The minimum displayed progress value.
max - The maximum displayed progress value.
Throws:
java.lang.IllegalArgumentException - If min is less than 0 or larger than max, or if max is larger than 1.
See Also:
min(), min(double), max(), max(double)

start

public void start()
Starts the progress displaying. Should be called at the start of the process whose progress is to be displayed.


stop

public void stop()
Stops the progress displaying. Should be called at the end of the process whose progress was displayed.


display

public boolean display()
Indicates whether progress is displayed. If a parent object has been set using parent(Progressor), that object instead determines whether progress is displayed. This recurses through all layers of parenthood, so that effectively the returned value is that of the highest parent in the hierarchy.

Returns:
Value true if progress is displayed, or false if this is not the case.

display

public void display(boolean enable)
Determines whether progress is displayed. By default progress is not displayed.

Parameters:
enable - If true (or false) progress is (or is not) displayed.

enforce

public boolean enforce()
Indicates whether repainting of the progress bar is enforced. If a parent object has been set using parent(Progressor), that object instead determines whether repainting is enforced. This recurses through all layers of parenthood, so that effectively the returned value is that of the highest parent in the hierarchy.

Returns:
Value true if repainting of the progress bar is displayed, or false if this is not the case.

enforce

public void enforce(boolean enable)
Determines whether repainting of the progress bar is enforced. By default it is not enforced. Under normal circumstances the progress bar gets repainted in the event dispatching thread. This precludes progress displaying for processes running in that same thread. By enabling enforced repainting, the progress bar gets repainted explicitly, outside of that thread.

Parameters:
enable - If true (or false) repainting of the progress bar is (or is not) enforced.

parent

public void parent(Progressor parent)
Sets the parent object for progress displaying. By default no parent object is set. If a parent object is specified, that object determines whether progress is displayed and whether this is enforced or not, overruling the values set using display(boolean) and enforce(boolean), and the minimum and maximum displayed progress values set using min(double) and max(double) or range(double,double) are mapped to the progress range of the parent.

Parameters:
parent - The parent object for progress displaying. Parameter value null means no parent object is set.

parent

public Progressor parent()
Returns the parent object for progress displaying.

Returns:
The parent object for progress displaying. The returned value is either null (indicating no parent has been set) or a valid Progressor object.

status

public void status(java.lang.String status)
Sets the status message. The message is displayed in the status area on the left of the progress bar and is rewritten each time the progress bar is updated. By default no message is displayed.

Parameters:
status - The status message. Parameter value null means no status message is displayed.

status

public java.lang.String status()
Returns the status message. If a parent object has been set using parent(Progressor), and its status message is not null, the returned value is the status message of the parent. This recurses through all layers of parenthood, so that effectively the returned value is that of the highest parent in the hierarchy whose status message is not null, and if no such parent exists the returned value is null.

Returns:
The status message. The returned value is either null (indicating no status message has been set) or a valid String object.

ImageScience 3.0.0

Copyright (C) Erik Meijering. Permission to use this software and corresponding documentation for educational, research, and not-for-profit purposes, without a fee and without a signed licensing agreement, is granted, subject to the following terms and conditions.

IT IS NOT ALLOWED TO REDISTRIBUTE, SELL, OR LEASE THIS SOFTWARE, OR DERIVATIVE WORKS THEREOF, WITHOUT PERMISSION IN WRITING FROM THE COPYRIGHT HOLDER. THE COPYRIGHT HOLDER IS FREE TO MAKE VERSIONS OF THE SOFTWARE AVAILABLE FOR A FEE OR COMMERCIALLY ONLY.

IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, OF ANY KIND WHATSOEVER, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE EXPRESS OR IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE AND CORRESPONDING DOCUMENTATION IS PROVIDED "AS IS". THE COPYRIGHT HOLDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.