Fix progress tests, update Progress jDoc

[nikiroo-utils.git] / src / be / nikiroo / utils / Progress.java

diff --git a/src/be/nikiroo/utils/Progress.java b/src/be/nikiroo/utils/Progress.java
index 473e80662a4a816a1fb8af21d82421c654f6ee3d..62e46874c3e0918ff49877f74b4d7314bae0be83 100644 (file)
--- a/src/be/nikiroo/utils/Progress.java
+++ b/src/be/nikiroo/utils/Progress.java
@@ -6,6 +6,7 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
+import java.util.Set;
 
 /**
  * Progress reporting system, possibly nested.
@@ -18,7 +19,10 @@ public class Progress {
                 * A progression event.
                 * 
                 * @param progress
-                *            the {@link Progress} object that generated it, or a parent
+                *            the {@link Progress} object that generated it, not
+                *            necessarily the same as the one where the listener was
+                *            attached (it could be a child {@link Progress} of this
+                *            {@link Progress}).
                 * @param name
                 *            the first non-null name of the {@link Progress} step that
                 *            generated this event
@@ -92,6 +96,18 @@ public class Progress {
                return name;
        }
 
+       /**
+        * The name of this {@link Progress} step.
+        * 
+        * @param name
+        *            the new name
+        */
+       public void setName(String name) {
+               this.name = name;
+               // will fire an action event:
+               setProgress(this.localProgress);
+       }
+
        /**
         * The minimum progress value.
         * 
@@ -188,7 +204,7 @@ public class Progress {
        public void setProgress(int progress) {
                int diff = this.progress - this.localProgress;
                this.localProgress = progress;
-               setTotalProgress(name, progress + diff);
+               setTotalProgress(this, name, progress + diff);
        }
 
        /**
@@ -211,27 +227,43 @@ public class Progress {
                return (((double) progress) / (max - min));
        }
 
+       /**
+        * Return the list of direct children of this {@link Progress}.
+        * 
+        * @return the children (who will think of them??)
+        */
+       public Set<Progress> getChildren() {
+               return children.keySet();
+       }
+
        /**
         * Set the total progress value (including the optional children
         * {@link Progress}), on a {@link Progress#getMin()} to
         * {@link Progress#getMax()} scale.
         * 
+        * @param pg
+        *            the {@link Progress} to report as the progression emitter
         * @param name
         *            the current name (if it is NULL, the first non-null name in
-        *            the hierarchy will overwrite it)
+        *            the hierarchy will overwrite it) of the {@link Progress} who
+        *            emitted this change
         * @param progress
         *            the progress to set
         */
-       private void setTotalProgress(String name, int progress) {
+       private void setTotalProgress(Progress pg, String name, int progress) {
                this.progress = progress;
 
                for (ProgressListener l : listeners) {
-                       l.progress(this, name);
+                       l.progress(pg, name);
                }
        }
 
        /**
         * Add a {@link ProgressListener} that will trigger on progress changes.
+        * <p>
+        * Note: the {@link Progress} that will be reported will be the active
+        * progress, not necessarily the same as the current one (it could be a
+        * child {@link Progress} of this {@link Progress}).
         * 
         * @param l
         *            the listener
@@ -240,6 +272,18 @@ public class Progress {
                this.listeners.add(l);
        }
 
+       /**
+        * Remove a {@link ProgressListener} that would trigger on progress changes.
+        * 
+        * @param l
+        *            the listener
+        * 
+        * @return TRUE if it was found (and removed)
+        */
+       public boolean removeProgressListener(ProgressListener l) {
+               return this.listeners.remove(l);
+       }
+
        /**
         * Add a child {@link Progress} of the given weight.
         * 
@@ -259,7 +303,7 @@ public class Progress {
                // Note: this is quite inefficient, especially with many children
                // TODO: improve it?
                progress.addProgressListener(new ProgressListener() {
-                       public void progress(Progress progress, String name) {
+                       public void progress(Progress pg, String name) {
                                double total = ((double) localProgress) / (max - min);
                                for (Entry<Progress, Double> entry : children.entrySet()) {
                                        total += (entry.getValue() / (max - min))
@@ -270,7 +314,8 @@ public class Progress {
                                        name = Progress.this.name;
                                }
 
-                               setTotalProgress(name, (int) Math.round(total * (max - min)));
+                               setTotalProgress(pg, name,
+                                               (int) Math.round(total * (max - min)));
                        }
                });