feat: better docs/examples and color support

src/main/java/paintingcanvas/animation/Animatable.java

@@ -1,6 +1,7 @@
 package paintingcanvas.animation;
 
 import paintingcanvas.drawable.Drawable;
+import paintingcanvas.misc.Hue;
 
 import java.awt.*;
 
@@ -25,14 +26,14 @@ private AnimationBuilder addAnimation(Animation animation, double duration) {
      *
      * <pre>{@code
      * Circle c = new Circle(200, 200, 50);
-     * // the circle will move to (100, 100), and then to (200, 200)
-     * c.moveTo(100, 100, 3).moveTo(200, 200, 3);
+     * // the circle will slowly move to (100, 100) over 3 seconds
+     * c.moveTo(100, 100, 3);
      * }</pre>
      *
-     * @param x        the x-position to move to
-     * @param y        the y-position to move to
+     * @param x        the x position to move to
+     * @param y        the y position to move to
      * @param duration the number of seconds it lasts
-     * @return an {@code this}
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder moveTo(int x, int y, double duration) {
         return this.addAnimation(Animation.moveTo(x, y), duration);
@@ -44,185 +45,237 @@ default AnimationBuilder moveTo(int x, int y, double duration) {
      *
      * <pre>{@code
      * Circle c = new Circle(200, 200, 50);
-     * // the circle will turn red, and then blue
-     * c.colorTo(255, 0, 0, 3).colorTo(0, 0, 255, 3);
+     * // the circle will slowly turn red over 3 seconds
+     * c.colorTo(255, 0, 0, 3);
      * }</pre>
      *
      * @param r        red (0-255)
      * @param g        green (0-255)
      * @param b        blue (0-255)
      * @param duration the number of seconds it lasts
-     * @return an {@code this}
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder colorTo(int r, int g, int b, double duration) {
         return this.addAnimation(Animation.colorTo(r, g, b), duration);
     }
 
     /**
      * Change the color of {@code this} to the specified {@code color} over {@code duration} seconds.
-     * See <a href="https://en.wikipedia.org/wiki/RGB_color_model#Numeric_representations">Wikipedia</a>
-     * for how this works.
+     * See <a href="https://en.wikipedia.org/wiki/RGBA_color_model">Wikipedia</a> for how this works.
      *
      * <pre>{@code
      * Circle c = new Circle(200, 200, 50);
-     * // the circle will turn red, and then blue
-     * c.colorTo(0xFF0000, 3).colorTo(0x0000FF, 3);
+     * // the circle will slowly turn red with with 100/255 opacity over three seconds
+     * c.colorTo(255, 0, 0, 100, 3);
      * }</pre>
      *
-     * @param hex      The number describing the RGB color
+     * @param r red (0-255)
+     * @param g green (0-255)
+     * @param b blue (0-255)
+     * @param a alpha (0-255)
      * @param duration the number of seconds it lasts
-     * @return an {@code this}
+     * @return an {@link AnimationBuilder}
+     */
+    default AnimationBuilder colorTo(int r, int g, int b, int a, double duration) {
+        return this.addAnimation(Animation.colorTo(r, g, b, a), duration);
+    }
+
+    /**
+     * Change the color of {@code this} to the specified {@code color} over {@code duration} seconds.
+     * See <a href="https://en.wikipedia.org/wiki/RGB_color_model#Numeric_representations">Wikipedia</a> for how this works.
+     *
+     * <pre>{@code
+     * Circle c = new Circle(200, 200, 50);
+     * // the circle will slowly turn red over three seconds
+     * c.colorTo(0xFF0000, 3);
+     * }</pre>
+     *
+     * @param hex      the number describing the RGB color
+     * @param duration the number of seconds it lasts
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder colorTo(int hex, double duration) {
         return this.addAnimation(Animation.colorTo(hex), duration);
     }
 
     /**
      * Change the color of {@code this} to the specified {@code color} over {@code duration} seconds.
-     * See {@link Color}
-     * for the full list of colors, and constructors for this class
      *
      * <pre>{@code
      * Circle c = new Circle(200, 200, 50);
-     * // the circle will turn red, and then blue
-     * c.colorTo(Color.RED, 3).colorTo(Color.BLUE, 3);
+     * // the circle will slowly turn red over 3 seconds
+     * c.colorTo(0xFF0000, 3);
+     * }</pre>
+     *
+     * @param hue the hue
+     * @param duration the number of seconds it lasts
+     * @return a {@link ColorAnimation}
+     */
+    default AnimationBuilder colorTo(Hue hue, double duration) {
+        return this.addAnimation(Animation.colorTo(hue), duration);
+    }
+
+    /**
+     * Change the color of {@code this} to the specified {@code color} over {@code duration} seconds.
+     *
+     * <pre>{@code
+     * Circle c = new Circle(200, 200, 50);
+     * // the circle will slowly turn red over 3 seconds
+     * // then, the circle will slowly turn blue over 3 seconds
+     * c.colorTo("red", 3).colorTo("#0000FF", 3);
+     * }</pre>
+     *
+     * @param name the hue name or the hex code
+     * @param duration the number of seconds it lasts
+     * @return an {@link AnimationBuilder}
+     */
+    default AnimationBuilder colorTo(String name, double duration) {
+        return this.addAnimation(Animation.colorTo(name), duration);
+    }
+
+    /**
+     * Change the color of {@code this} to the specified {@code color} over {@code duration} seconds.
+     * See {@link Color} for the full list of colors, and constructors for this class
+     *
+     * <pre>{@code
+     * Circle c = new Circle(200, 200, 50);
+     * // the circle will turn slowly red over 3 seconds
+     * c.colorTo(Color.RED, 3);
      * }</pre>
      *
-     * @param color    The color to fade to
+     * @param color    the color to fade to
      * @param duration the number of seconds it lasts
-     * @return an {@code this}
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder colorTo(Color color, double duration) {
         return this.addAnimation(Animation.colorTo(color), duration);
     }
 
     /**
-     * Fades {@code this} out over @{code duration} seconds.
+     * Fade {@code this} out over {@code duration} seconds.
      *
      * <pre>{@code
      * Circle c = new Circle(200, 200, 50);
-     * // the circle will fade out, then in
-     * c.fadeOut(3).fadeIn(3);
+     * // the circle will slowly fade out over 3 seconds
+     * c.fadeOut(3);
      * }</pre>
      *
-     * @param duration the amount of time it takes to fade out
-     * @return an {@code this}
-     * @see #fadeIn(double)
+     * @param duration the number of seconds it lasts
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder fadeOut(double duration) {
         return this.addAnimation(Animation.fadeOut(), duration);
     }
 
     /**
-     * Fades {@code this} in over @{code duration} seconds.
+     * Fade {@code this} in over {@code duration} seconds.
      *
      * <pre>{@code
      * Circle c = new Circle(200, 200, 50);
-     * // the circle will fade out, then in
+     * // the circle will slowly fade out over 3 seconds
+     * // then, fade back in over 3 seconds
      * c.fadeOut(3).fadeIn(3);
      * }</pre>
      *
-     * @param duration the amount of time it takes to fade out
-     * @return an {@code this}
-     * @see #fadeOut(double)
+     * @param duration the number of seconds it lasts
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder fadeIn(double duration) {
         return this.addAnimation(Animation.fadeIn(), duration);
     }
 
     /**
-     * Rotates {@code this} to the specified <code>angle°</code>.
+     * Rotate {@code this} to the specified {@code angle} degrees over {@code duration} seconds.
      * If you supply an angle {@code > 360} it will make more than one full rotation.
      *
      * <pre>{@code
      * Square s = new Square(200, 200, 50);
-     * // the square will rotate one turn counter-clockwise, then 2 turns clockwise
-     * c.rotateTo(360, 3).colorTo(-360, 3);
+     * // the square will slowly rotate one turn counter-clockwise over 3 seconds
+     * // then, slowly rotate two turns clockwise over 3 seconds
+     * c.rotateTo(360, 3).rotateTo(-360, 3);
      * }</pre>
      *
-     * @param angle    The absolute angle to rotate to in degrees.
+     * @param angle    the absolute angle to rotate to in degrees.
      * @param duration the number of seconds it lasts
-     * @return an {@code this}
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder rotateTo(int angle, double duration) {
         return this.addAnimation(Animation.rotateTo(angle), duration);
     }
 
     /**
-     * Rotates {@code this} by <code>angle°</code>.
+     * Rotate {@code this} by {@code angle} degrees over {@code duration} seconds.
+     * If you supply an angle {@code > 360} it will make more than one full rotation.
      *
      * <pre>{@code
      * Square s = new Square(200, 200, 50);
-     * // the square will rotate one turn counter-clockwise, then one turns clockwise
-     * c.rotateTo(360, 3).colorTo(-360, 3);
+     * // the square will slowly rotate one turn counter-clockwise over 3 seconds
+     * // then, slowly rotate one turn clockwise over 3 seconds
+     * c.rotateBy(360, 3).rotateBy(-360, 3);
      * }</pre>
      *
-     * @param angle    The relative angle to rotate to in degrees.
+     * @param angle    the relative angle to rotate to in degrees.
      * @param duration the number of seconds it lasts
-     * @return an {@code this}
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder rotateBy(int angle, double duration) {
         return this.addAnimation(Animation.rotateBy(angle), duration);
     }
 
     /**
-     * This method moves {@code this} by the specified {@code x} and {@code y}
+     * Move {@code this} by the specified {@code x} and {@code y} over {@code duration} seconds.
      *
      * <pre>{@code
      * Circle c = new Circle(200, 200, 50);
-     * // the circle will move down 100, and then right 200
+     * // the circle will slowly move down 100 over 3 seconds
+     * // then, slowly move right over 3 seconds
      * c.moveBy(0, 100, 3).moveBy(200, 0, 3);
      * }</pre>
      *
      * @param x        the x to move by
      * @param y        the y to move by
      * @param duration the number of seconds it lasts
-     * @return an {@code this}
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder moveBy(int x, int y, double duration) {
         return this.addAnimation(Animation.moveBy(x, y), duration);
     }
 
     /**
-     * <p>
-     * This method moves {@code this} by the specified {@code x} horizontally.
+     * Move {@code this} by the specified {@code x} horizontally over {@code duration} seconds.
      * Positive values move right, negative values move left.
-     * </p><p>
      * This method is equivalent to {@code moveBy(x, 0, duration)}
-     * </p>
      *
      * <pre>{@code
      * Circle c = new Circle(200, 200, 50);
-     * // the circle will move right 300 pixels over 3 seconds
-     * c.moveHorizontalBy(0, 100, 3);
+     * // the circle will move slowly right 300 pixels over 3 seconds
+     * c.moveHorizontalBy(100, 3);
      * }</pre>
      *
      * @param x        the x to move by
      * @param duration the number of seconds it lasts
-     * @return an {@code this}
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder moveHorizontalBy(int x, double duration) {
-        return this.addAnimation(Animation.moveBy(x, 0).relative(), duration);
+        return this.addAnimation(Animation.moveHorizontalBy(x), duration);
     }
 
     /**
-     * <p>
-     * This method moves {@code this} by the specified {@code x} horizontally.
-     * Positive values move right, negative values move left.
-     * </p><p>
+     * Move {@code this} by the specified {@code y} vertically over {@code duration} seconds.
+     * Positive values move down, negative values move up.
      * This method is equivalent to {@code moveBy(0, y, duration)}
-     * </p>
+     *
      * <pre>{@code
      * Circle c = new Circle(200, 200, 50);
      * // the circle will move right 300 pixels over 3 seconds
-     * c.moveHorizontalBy(0, 100, 3);
+     * c.moveVerticalBy(100, 3);
      * }</pre>
      *
      * @param y        the y to move by
      * @param duration the number of seconds it lasts
-     * @return an {@code this}
+     * @return an {@link AnimationBuilder}
      */
     default AnimationBuilder moveVerticalBy(int y, double duration) {
-        return this.addAnimation(Animation.moveBy(0, y).relative(), duration);
+        return this.addAnimation(Animation.moveVerticalBy(y), duration);
     }
 }