Importer item: cleanup + jdoc

diff --git a/src/be/nikiroo/fanfix_swing/gui/importer/ImporterItem.java b/src/be/nikiroo/fanfix_swing/gui/importer/ImporterItem.java
index 7ac8384db8f96711bd1dceafb4b5a1d1c2bfd318..bf28498030a2ddc7d714f83ff63f240e634ea982 100644 (file)
--- a/src/be/nikiroo/fanfix_swing/gui/importer/ImporterItem.java
+++ b/src/be/nikiroo/fanfix_swing/gui/importer/ImporterItem.java
@@ -3,8 +3,8 @@ package be.nikiroo.fanfix_swing.gui.importer;
 import java.awt.BorderLayout;
 import java.awt.Color;
 import java.awt.Font;
-import java.awt.Graphics;
-import java.awt.Rectangle;
+import java.awt.event.ActionEvent;
+import java.awt.event.ActionListener;
 
 import javax.swing.JLabel;
 import javax.swing.SwingUtilities;
@@ -16,7 +16,21 @@ import be.nikiroo.utils.Progress.ProgressListener;
 import be.nikiroo.utils.ui.ListModel.Hoverable;
 import be.nikiroo.utils.ui.ListenerPanel;
 
+/**
+ * The visual representation of a {@link Progress} used to download/convert a
+ * book.
+ * 
+ * @author niki
+ */
 public class ImporterItem extends ListenerPanel implements Hoverable {
+       private static final long serialVersionUID = 1L;
+
+       /**
+        * The {@link ActionEvent} you receive from
+        * {@link ImporterItem#addActionListener(ActionListener)} can return this as
+        * a command (see {@link ActionEvent#getActionCommand()}) for change event
+        * on this {@link ImporterItem}.
+        */
        static public final String CHANGE = "change";
 
        private String basename = "";
@@ -32,6 +46,17 @@ public class ImporterItem extends ListenerPanel implements Hoverable {
        private JLabel labelName;
        private JLabel labelAction;
 
+       /**
+        * Create a new item for the given book conversion/download process.
+        * 
+        * @param pg
+        *            the {@link Progress} to track (must not be NULL)
+        * @param basename
+        *            the base name to use for the process, usually the web site it
+        *            is from (can be NULL)
+        * @param storyName
+        *            the name of the story (can be NULL)
+        */
        public ImporterItem(Progress pg, String basename, String storyName) {
                this.basename = basename == null ? "" : basename;
                this.storyName = storyName == null ? "" : storyName;
@@ -49,10 +74,22 @@ public class ImporterItem extends ListenerPanel implements Hoverable {
                init(pg);
        }
 
+       /**
+        * Return the full story name (including the base name, so the <i>source</i>
+        * of this download/conversion.
+        * 
+        * @return the story name (never NULL)
+        */
        public String getStoryName() {
                return basename + ": " + storyName;
        }
 
+       /**
+        * Return the current action that is being done (more precise tha just
+        * "download" or "convert").
+        * 
+        * @return the current action
+        */
        public String getAction() {
                // space is for the default size
                if (done) {
@@ -62,6 +99,11 @@ public class ImporterItem extends ListenerPanel implements Hoverable {
                return action.isEmpty() ? " " : action;
        }
 
+       /**
+        * This item is currently selected.
+        * 
+        * @return TRUE for selected, FALSE for unselected
+        */
        public boolean isSelected() {
                return selected;
        }
@@ -75,6 +117,11 @@ public class ImporterItem extends ListenerPanel implements Hoverable {
                }
        }
 
+       /**
+        * The element is currently under the mouse cursor.
+        * 
+        * @return TRUE if it is, FALSE if not
+        */
        public boolean isHovered() {
                return hovered;
        }
@@ -97,10 +144,24 @@ public class ImporterItem extends ListenerPanel implements Hoverable {
                }
        }
 
+       /**
+        * The process is done.
+        * 
+        * @param acceptFailure
+        *            TRUE will also report "done" if we have a failure
+        * 
+        * @return TRUE if it is done
+        */
        public boolean isDone(boolean acceptFailure) {
                return done && (acceptFailure || !failed);
        }
 
+       /**
+        * The process is done.
+        * 
+        * @param done
+        *            the new state
+        */
        public void setDone(boolean done) {
                if (this.done != done) {
                        this.done = done;
@@ -108,10 +169,21 @@ public class ImporterItem extends ListenerPanel implements Hoverable {
                }
        }
 
+       /**
+        * The process encountered an error.
+        * 
+        * @return TRUE if it has
+        */
        public boolean isFailed() {
                return failed;
        }
 
+       /**
+        * The process encountered an error.
+        * 
+        * @param failed
+        *            the new value
+        */
        public void setFailed(boolean failed) {
                if (this.failed != failed) {
                        this.failed = failed;
@@ -119,6 +191,10 @@ public class ImporterItem extends ListenerPanel implements Hoverable {
                }
        }
 
+       /**
+        * Update the highlight of the action label depending upon the current state
+        * (normal, done, failed).
+        */
        private void setHighlight() {
                Color highlight = null;
                if (failed) {
@@ -136,6 +212,12 @@ public class ImporterItem extends ListenerPanel implements Hoverable {
                }
        }
 
+       /**
+        * Initialise the system and listen on the {@link Progress} events.
+        * 
+        * @param pg
+        *            the {@link Progress} (must not be NULL)
+        */
        private void init(final Progress pg) {
                pg.addProgressListener(new ProgressListener() {
                        @Override
@@ -170,16 +252,4 @@ public class ImporterItem extends ListenerPanel implements Hoverable {
                        }
                });
        }
-
-       @Override
-       public void paint(Graphics g) {
-               Rectangle clip = g.getClipBounds();
-               if (!(clip == null || clip.getWidth() <= 0 || clip.getHeight() <= 0)) {
-                       g.setColor(new Color(200, 200, 255, 128));
-                       g.fillRect(clip.x, clip.y, (int) Math.round(clip.width * progress),
-                                       clip.height);
-               }
-
-               super.paint(g);
-       }
 }
\ No newline at end of file