lib/graphics: improve API

- Add more documentation
- Rename FilmStripCanvas to GuiFilmStripCanvas to match naming of other
  classes
- Move Graphics#renderableColor to Colors#toAwtColor

Author: bvlj

lib/src/main/java/jtamaro/graphic/CircularSector.java

@@ -53,7 +53,7 @@ public Color getColor() {
 
   @Override
   protected void render(Graphics2D g2d, RenderOptions options) {
-    g2d.setPaint(renderableColor(color));
+    g2d.setPaint(Colors.toAwtColor(color));
     g2d.fill(getPath());
   }
 

lib/src/main/java/jtamaro/graphic/Colors.java

@@ -178,6 +178,17 @@ static String htmlString(Color color) {
         : "#ffffff";
     return String.format(
         "<font bgcolor=\"rgba(%1$d,%2$d,%3$d,%4$.2f)\" color=\"%5$s\">&nbsp;#%1$02x%2$02x%3$02x&nbsp;</font>",
-        color.red(), color.green(), color.blue(), color.opacity(), foregroundColor);
+        color.red(),
+        color.green(),
+        color.blue(),
+        color.opacity(),
+        foregroundColor);
+  }
+
+  /**
+   * Convert a given jtamaro color to an equivalent awt {@link java.awt.Color}.
+   */
+  public static java.awt.Color toAwtColor(Color color) {
+    return new java.awt.Color(color.red(), color.green(), color.blue(), color.alpha());
   }
 }

lib/src/main/java/jtamaro/graphic/Ellipse.java

@@ -50,7 +50,7 @@ public Color getColor() {
 
   @Override
   protected void render(Graphics2D g2d, RenderOptions options) {
-    g2d.setPaint(renderableColor(color));
+    g2d.setPaint(Colors.toAwtColor(color));
     g2d.fill(getPath());
   }
 

lib/src/main/java/jtamaro/graphic/Graphic.java

@@ -1,6 +1,5 @@
 package jtamaro.graphic;
 
-import java.awt.Color;
 import java.awt.Graphics2D;
 import java.awt.geom.Path2D;
 import java.awt.geom.Rectangle2D;
@@ -67,10 +66,18 @@ protected Graphic(Path2D.Double path, Point pinPoint) {
 
   /* **** Location **** */
 
+  /**
+   * Get pinning point of the graphic.
+   *
+   * @see Point
+   */
   public Point getPin() {
     return pinPoint;
   }
 
+  /**
+   * Get the (tight) bounding box of this graphic.
+   */
   Rectangle2D getBBox() {
     return bbox;
   }
@@ -95,6 +102,11 @@ public final double getBoundsMinY() {
     return getBBox().getMinY();
   }
 
+  /**
+   * Get the relative location for the given point with respect to this graphic.
+   *
+   * @implNote The location is computed with respect to the origin point of this graphic.
+   */
   RelativeLocation getLocation(Point point) {
     /*
      * switch (point.x) {
@@ -136,7 +148,7 @@ RelativeLocation getLocation(Point point) {
    * Return the location coordinates relative to the (child) graphic corresponding to the given
    * absolute coordinates.
    *
-   * <p>The two coordinates must be given with respect to the origin point of the graphic.
+   * @apiNote The two coordinates must be given with respect to the origin point of the graphic.
    */
   Option<RelativeLocation> relativeLocationOf(double x, double y) {
     return path.contains(x, y)
@@ -147,33 +159,46 @@ Option<RelativeLocation> relativeLocationOf(double x, double y) {
   /* **** Rendering **** */
 
   /**
-   * Render this Graphic into the given Graphics2D graphics context, using the given RenderOptions.
+   * Render this Graphic into the given {@link Graphics2D} graphics context, using the given
+   * {@link RenderOptions}.
    *
    * <p>The context can represent a GUI component (used when visualizing the graphic), or a bitmap
    * (used when writing the graphic into a bitmap file).
    */
   protected abstract void render(Graphics2D g2d, RenderOptions options);
 
+  /**
+   * Draw debug information for this graphic on the given {@link Graphics2D} graphics context.
+   */
   final void drawDebugInfo(Graphics2D g2d) {
     GraphicsDebugInfo.render(g2d, getPath(), getBBox());
   }
 
+  /**
+   * Get the path of this graphic.
+   */
   Path2D.Double getPath() {
     return path;
   }
 
+  /**
+   * Get the width of this graphic.
+   *
+   * @implNote Computed using the tight bounding box.
+   */
   public double getWidth() {
     return bbox.getWidth();
   }
 
+  /**
+   * Get the height of this graphic.
+   *
+   * @implNote Computed using the tight bounding box.
+   */
   public double getHeight() {
     return bbox.getHeight();
   }
 
-  public static Color renderableColor(jtamaro.graphic.Color color) {
-    return new Color(color.red(), color.green(), color.blue(), color.alpha());
-  }
-
   /**
    * Return an <b>ordered</b> map that contains children (and their "names" as key) of this
    * graphic.

…ava/jtamaro/graphic/FilmStripCanvas.java …/jtamaro/graphic/GuiFilmStripCanvas.javalib/src/main/java/jtamaro/graphic/FilmStripCanvas.java renamed to lib/src/main/java/jtamaro/graphic/GuiFilmStripCanvas.java lib/src/main/java/jtamaro/graphic/FilmStripCanvas.java renamed to lib/src/main/java/jtamaro/graphic/GuiFilmStripCanvas.java

@@ -19,7 +19,7 @@
  * @apiNote Not for public use.
  * @hidden
  */
-public final class FilmStripCanvas extends JComponent {
+public final class GuiFilmStripCanvas extends JComponent {
 
   private static final double GAP_FRACTION = 0.05;
 
@@ -55,7 +55,7 @@ public final class FilmStripCanvas extends JComponent {
 
   private int position;
 
-  public FilmStripCanvas(Sequence<Graphic> graphics, int frameWidth, int frameHeight) {
+  public GuiFilmStripCanvas(Sequence<Graphic> graphics, int frameWidth, int frameHeight) {
     super();
     this.indexedGraphics = graphics.zipWithIndex();
     this.frameWidth = frameWidth;

lib/src/main/java/jtamaro/graphic/Rectangle.java

@@ -46,7 +46,7 @@ public double getHeight() {
 
   @Override
   protected void render(Graphics2D g2d, RenderOptions options) {
-    g2d.setPaint(renderableColor(color));
+    g2d.setPaint(Colors.toAwtColor(color));
     g2d.fill(getPath());
   }
 

lib/src/main/java/jtamaro/graphic/Text.java

@@ -64,7 +64,7 @@ public Color getColor() {
 
   @Override
   protected void render(Graphics2D g2d, RenderOptions options) {
-    g2d.setPaint(renderableColor(color));
+    g2d.setPaint(Colors.toAwtColor(color));
     g2d.fill(getPath());
   }
 

lib/src/main/java/jtamaro/graphic/Triangle.java

@@ -60,7 +60,7 @@ public Color getColor() {
 
   @Override
   protected void render(Graphics2D g2d, RenderOptions options) {
-    g2d.setPaint(renderableColor(color));
+    g2d.setPaint(Colors.toAwtColor(color));
     g2d.fill(getPath());
   }
 

lib/src/main/java/jtamaro/io/ColorFrame.java

@@ -7,7 +7,7 @@
 import javax.swing.JFrame;
 import javax.swing.JLabel;
 import jtamaro.graphic.Color;
-import jtamaro.graphic.Graphic;
+import jtamaro.graphic.Colors;
 
 final class ColorFrame extends JFrame {
 
@@ -30,7 +30,7 @@ public Dimension getPreferredSize() {
 
       @Override
       protected void paintComponent(Graphics g) {
-        g.setColor(Graphic.renderableColor(color));
+        g.setColor(Colors.toAwtColor(color));
         g.fillRect(0, 0, getWidth(), getHeight());
       }
     };

lib/src/main/java/jtamaro/io/FilmStripFrame.java

@@ -9,7 +9,7 @@
 import javax.swing.JPanel;
 import javax.swing.JScrollBar;
 import jtamaro.data.Sequence;
-import jtamaro.graphic.FilmStripCanvas;
+import jtamaro.graphic.GuiFilmStripCanvas;
 import jtamaro.graphic.Graphic;
 
 final class FilmStripFrame extends JFrame {
@@ -20,16 +20,16 @@ final class FilmStripFrame extends JFrame {
 
   private final int completeFrameWidth;
 
-  private final FilmStripCanvas canvas;
+  private final GuiFilmStripCanvas canvas;
 
   public FilmStripFrame(Sequence<Graphic> graphics, int frameWidth, int frameHeight) {
     super();
     setTitle("Film Strip (" + length(graphics) + " frames)");
     setDefaultCloseOperation(DISPOSE_ON_CLOSE);
     setLayout(new BorderLayout());
 
-    completeFrameWidth = FilmStripCanvas.computeCompleteFrameWidth(frameWidth);
-    canvas = new FilmStripCanvas(graphics, frameWidth, frameHeight);
+    completeFrameWidth = GuiFilmStripCanvas.computeCompleteFrameWidth(frameWidth);
+    canvas = new GuiFilmStripCanvas(graphics, frameWidth, frameHeight);
     add(canvas, BorderLayout.CENTER);
     final JPanel bar = new JPanel(new BorderLayout());
     final JButton prevButton = new JButton("<");