From: Niki Roo <niki@nikiroo.be>
Date: Mon, 4 May 2020 09:36:10 +0000 (+0200)
Subject: Importer item: cleanup + jdoc
X-Git-Tag: fanfix-swing-1.2.0~32
X-Git-Url: http://git.nikiroo.be/?a=commitdiff_plain;h=f1b1a671961fe22823453cbbc0dcb88baaee85a9;p=fanfix-swing.git

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 7ac8384d..bf284980 100644
--- 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