diff --git a/README.md b/README.md index f20c888..253e9dd 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,6 @@ Here is an example : `1.5.7-3-g2aabbbf.dirty` ## How to release (and have a nice version number) 1. `git commit` -1. `git tag -a MAJOR.MINOR.SUB -m "tag vMAJOR.MINOR.SUB"` -1. `git push origin MAJOR.MINOR.SUB` -2. This commits everyhing and tags it adequately. When this has been done, you can then draft a new release and upload the corresponding `jar` file from above in Github releases. Creating a tag triggers the documentation update. Voilà, you're all set. +2. `git tag -a MAJOR.MINOR.SUB -m "tag vMAJOR.MINOR.SUB"` +3. `git push origin MAJOR.MINOR.SUB` +4. This commits everyhing and tags it adequately. When this has been done, you can then draft a new release and upload the corresponding `jar` file from above in GitHub releases. Creating a tag triggers the documentation update. Voilà, you're all set. diff --git a/src/main/scala/hevs/graphics/AcceleratedDisplay.scala b/src/main/scala/hevs/graphics/AcceleratedDisplay.scala index e2fa7dc..7bdf451 100644 --- a/src/main/scala/hevs/graphics/AcceleratedDisplay.scala +++ b/src/main/scala/hevs/graphics/AcceleratedDisplay.scala @@ -1,21 +1,10 @@ package hevs.graphics import hevs.graphics.utils.GraphicTimer -import java.awt.Color -import java.awt.Dimension -import java.awt.DisplayMode -import java.awt.Graphics2D -import java.awt.GraphicsConfiguration -import java.awt.GraphicsDevice -import java.awt.GraphicsEnvironment -import java.awt.RenderingHints -import java.awt.Toolkit -import java.awt.Transparency -import java.awt.image.BufferStrategy -import java.awt.image.BufferedImage -import javax.swing.JFrame -import javax.swing.SwingWorker -import javax.swing.UIManager + +import java.awt._ +import java.awt.image.{BufferStrategy, BufferedImage} +import javax.swing.{JFrame, SwingWorker, UIManager} object AcceleratedDisplay { @@ -77,11 +66,11 @@ abstract class AcceleratedDisplay { } /** - * @see #AcceleratedDisplay(int, int, int, int, String, boolean) - * @param width - * @param height - * @param title - * @param high_quality + * @see AcceleratedDisplay(Int, Int, Int, Int, String, Boolean) + * @param width the width of the window (in pixels) + * @param height the height of the window (in pixels) + * @param title the title of the window + * @param high_quality whether to enable antialiasing or not */ def this(width: Int, height: Int, title: String, high_quality: Boolean) = { this() @@ -91,14 +80,14 @@ abstract class AcceleratedDisplay { /** * - * @param width - * @param height - * @param xPos x offset position of the window on the screen, -1 for + * @param width the width of the window (in pixels) + * @param height the height of the window (in pixels) + * @param xPos the x offset position of the window on the screen, -1 for * centered - * @param yPos y offset position of the window on the screen, -1 for + * @param yPos the y offset position of the window on the screen, -1 for * centered - * @param title - * @param high_quality + * @param title the title of the window + * @param high_quality whether to enable antialiasing or not */ def this(width: Int, height: Int, xPos: Int, yPos: Int, title: String, high_quality: Boolean) = { this() @@ -107,11 +96,11 @@ abstract class AcceleratedDisplay { } /** - * @param title - * @param width - * @param height - * @param xOffset The x offset of the window on the screen, -1 if centered - * @param yOffset The y offset of the window on the screen, -1 if centered + * @param title the title of the window + * @param width the width of the window (in pixels) + * @param height the height of the window (in pixels) + * @param xOffset the x offset of the window on the screen, -1 if centered + * @param yOffset the y offset of the window on the screen, -1 if centered */ private def initFrame(title: String, width: Int, height: Int, xOffset: Int, yOffset: Int): Unit = { // Shall we try a different look for the window ? try UIManager.setLookAndFeel("javax.swing.plaf.nimbus.NimbusLookAndFeel") @@ -244,7 +233,7 @@ abstract class AcceleratedDisplay { /** * Call this method periodically to have a constant frame rate * - * @param FPS + * @param FPS the target frame rate */ def syncGameLogic(FPS: Int): Unit = { gt.sync(FPS) diff --git a/src/main/scala/hevs/graphics/FunGraphics.scala b/src/main/scala/hevs/graphics/FunGraphics.scala index 3b228dc..a62a385 100644 --- a/src/main/scala/hevs/graphics/FunGraphics.scala +++ b/src/main/scala/hevs/graphics/FunGraphics.scala @@ -1,20 +1,18 @@ package hevs.graphics -import hevs.graphics.interfaces.DualLayerGraphics -import hevs.graphics.interfaces.Graphics -import hevs.graphics.utils.GraphicsBitmap -import hevs.graphics.utils.RepeatingReleasedEventsFixer +import hevs.graphics.interfaces.{DualLayerGraphics, Graphics} +import hevs.graphics.utils.{GraphicsBitmap, RepeatingReleasedEventsFixer} -import javax.imageio.ImageIO import java.awt._ import java.awt.event._ -import java.awt.font.{LineMetrics, TextLayout} +import java.awt.font.LineMetrics import java.awt.geom.{AffineTransform, Rectangle2D} import java.io._ +import javax.imageio.ImageIO import javax.swing.SwingConstants /** - * Factory for [[hevs.graphics.FunGraphics]]. + * Factory for [[FunGraphics]]. */ object FunGraphics { var major = 0 @@ -275,8 +273,8 @@ class FunGraphics(val width: Int, val height: Int, val xoffset: Int, val yoffset g2d.drawOval(posX, posY, f, f) } - override def drawFilledCircle(posX: Int, posY: Int, radius: Int): Unit = { - g2d.fillOval(posX, posY, radius, radius) + override def drawFilledCircle(posX: Int, posY: Int, diameter: Int): Unit = { + g2d.fillOval(posX, posY, diameter, diameter) } override def drawFilledOval(posX: Int, posY: Int, width: Int, height: Int): Unit = { @@ -455,13 +453,14 @@ class FunGraphics(val width: Int, val height: Int, val xoffset: Int, val yoffset override def getAvailableFonts(): Array[String] = GraphicsEnvironment.getLocalGraphicsEnvironment.getAvailableFontFamilyNames - /** - * A sample game loop using explicit synchronization (if display flickers) - */ + private[graphics] var pressedUp = false private[graphics] var pressedDown = false private[graphics] var size = 1 + /** + * A sample game loop using explicit synchronization (if display flickers) + */ private[graphics] def gameloopSample(): Unit = { var i = 1 var direction = 1 diff --git a/src/main/scala/hevs/graphics/ImageGraphics.scala b/src/main/scala/hevs/graphics/ImageGraphics.scala index 93da4d8..bff08be 100644 --- a/src/main/scala/hevs/graphics/ImageGraphics.scala +++ b/src/main/scala/hevs/graphics/ImageGraphics.scala @@ -1,15 +1,12 @@ package hevs.graphics -import java.awt.Color -import java.awt.Graphics -import java.awt.Toolkit import java.awt.image.BufferedImage +import java.awt.{Color, Graphics, Toolkit} import javax.imageio.ImageIO import javax.swing.JFrame - /** - * [ImageGraphics] helpers. + * [[ImageGraphics]] helpers. */ @SerialVersionUID(6832022057915586803L) object ImageGraphics { @@ -35,6 +32,11 @@ object ImageGraphics { values } + /** + * Converts a color array to a black-or-white array as Int values + * @param c The color array + * @return The array converted to BW + */ def convertToGrayInt(c: Array[Array[Color]]): Array[Array[Int]] = { val w = c.length val h = c(0).length @@ -49,6 +51,10 @@ object ImageGraphics { values } + /** + * Test of the class + * @param args unused + */ def main(args: Array[String]): Unit = { val imageUsed = "/images/lena.bmp" val org = new ImageGraphics(imageUsed, "Original", 0, 0) @@ -57,7 +63,7 @@ object ImageGraphics { /** * This class was made to deal with images as multidimensional arrays. - * Mainly used in the ImageProcessing lab. It expects the images to reside in the src directory + * Mainly used in the `ImageProcessing` lab. It expects the images to reside in the `src` directory * * @author Pierre-André Mudry * @version 1.0 @@ -65,7 +71,7 @@ object ImageGraphics { * @param backGroundFilePath the path of the file * @param windowTitle the title * @param xPositionOffset the x offset - * @param yPositionOffset the y offet + * @param yPositionOffset the y offset */ @SerialVersionUID(6832022057915586803L) class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val xPositionOffset: Int, val yPositionOffset: Int) extends JFrame { @@ -110,9 +116,9 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val * is slow. If required, please call [[java.awt.Component#repaint()]] if needed after * you have updated all the pixels you need. * - * @param x - * @param y - * @param intensity + * @param x X position of the pixel + * @param y Y position of the pixel + * @param intensity grayscale value of the pixel */ def setPixelBW(x: Int, y: Int, intensity: Int): Unit = { if (!((x < 0) || (y < 0) || (x >= w) || (y >= h))) backgroundBitmap.setRGB(x, y, intensity << 16 | intensity << 8 | intensity) @@ -121,7 +127,7 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val /** * Sets an array of grayscale pixels (from 0 to 255) and displays them * - * @param pixels + * @param pixels the 2D array of grayscale pixels */ def setPixelsBW(pixels: Array[Array[Int]]): Unit = { try { @@ -140,9 +146,9 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val } /** - * Sets an array of pixels of Color and displays them + * Sets an array of pixels of [[Color]] and displays them * - * @param pixels + * @param pixels the 2D of [[Color]] pixels */ def setPixelsColor(pixels: Array[Array[Color]]): Unit = { try { @@ -165,7 +171,7 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val * * @param x the x coordinate * @param y the y coordinate - * @return the pixel + * @return the pixel's grayscale value */ def getPixelBW(x: Int, y: Int): Int = if ((x < 0) || (y < 0) || (x >= w) || (y >= h)) 0 else { // Inside the image. Make the gray conversion and return the value @@ -177,7 +183,7 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val * Gets the array of the pixels (which have been converted to grayscale * if required) * - * @return The arrays of gray pixels + * @return the 2D array of grayscale pixels */ def getPixelsBW(): Array[Array[Int]] = { val values = Array.ofDim[Int](w, h) @@ -191,9 +197,9 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val } /** - * Gets the array of the pixels as Colors (see #Color) + * Gets the array of the pixels as [[Color]]s * - * @return The arrays of pixels + * @return the 2D array of [[Color]] pixels */ def getPixelsColor(): Array[Array[Color]] = { val values = Array.ofDim[Color](w, h) diff --git a/src/main/scala/hevs/graphics/TurtleGraphics.scala b/src/main/scala/hevs/graphics/TurtleGraphics.scala index 48aa67f..4cb8ea0 100644 --- a/src/main/scala/hevs/graphics/TurtleGraphics.scala +++ b/src/main/scala/hevs/graphics/TurtleGraphics.scala @@ -1,17 +1,14 @@ package hevs.graphics -import java.awt.BasicStroke -import java.awt.Color -import java.awt.Point +import java.awt.{BasicStroke, Color, Point} import java.awt.event.MouseMotionListener - /** * Graphics class that emulates the tortoise in the Logo programming language * * The turtle starts at the center of the window, looking up with a black color and pen down * - * Basic port implementation by Pierre Roduit, rewritten for use with {@link FunGraphics} + * Basic port implementation by Pierre Roduit, rewritten for use with [[FunGraphics]] * by Pierre-André Mudry. * * @see Wikipedia @@ -41,6 +38,11 @@ class TurtleGraphics(width: Int, height: Int, windowName: String) extends FunGra this(width, height, null) } + /** + * Rounds a Double value and converts it to Int + * @param a the value to round + * @return the rounded value + */ private def round(a: Double) = a.round.toInt /** @@ -55,7 +57,7 @@ class TurtleGraphics(width: Int, height: Int, windowName: String) extends FunGra /** * Change the color of drawing * - * @param color + * @param color the new color */ def changeColor(color: Color): Unit = { setColor(color) @@ -99,27 +101,29 @@ class TurtleGraphics(width: Int, height: Int, windowName: String) extends FunGra } /** + * Gets the turtle's current position * @return The location of the turtle */ - def getPosition() = new Point(round(x), round(y)) + def getPosition(): Point = new Point(round(x), round(y)) /** * Sets the width of the pen * - * @param w + * @param w the new width */ def setWidth(w: Float): Unit = { g2d.setStroke(new BasicStroke(w)) } /** + * Gets the turtle's current angle * @return The current turtle angle (in degrees) * Angle 0 is east (right). A positive angle is clockwise. */ def getTurtleAngle(): Double = this.angle * 180.0 / Math.PI /** - * Turn the direction of writing with the specified angle + * Turn the direction of writing with by specified angle * A positive angle is clockwise. * * @param angle specified angle in degrees @@ -140,7 +144,7 @@ class TurtleGraphics(width: Int, height: Int, windowName: String) extends FunGra } /** - * Turn the direction of writing with the specified angle. + * Turn the direction of writing by the specified angle. * A positive angle is clockwise. * * @param angle @@ -169,6 +173,10 @@ class TurtleGraphics(width: Int, height: Int, windowName: String) extends FunGra */ def getTurtleAngleRad(): Double = this.angle + /** + * Adds a [[MouseMotionListener]] to the window to react on mouse movements + * @param mouseMotionListener the [[MouseMotionListener]] + */ def setMouseMotionManager(mouseMotionListener: MouseMotionListener): Unit = { this.mainFrame.addMouseMotionListener(mouseMotionListener) } diff --git a/src/main/scala/hevs/graphics/advanced/ListGraphics.scala b/src/main/scala/hevs/graphics/advanced/ListGraphics.scala index 18f9603..bfd05bb 100644 --- a/src/main/scala/hevs/graphics/advanced/ListGraphics.scala +++ b/src/main/scala/hevs/graphics/advanced/ListGraphics.scala @@ -3,51 +3,69 @@ package hevs.graphics.advanced import hevs.graphics.FunGraphics import java.awt.Color -import java.awt.event.KeyListener -import java.awt.event.MouseListener -import java.util.{Collections, List} +import java.awt.event.{KeyListener, MouseListener} import java.util +import java.util.Collections import java.util.concurrent.CopyOnWriteArrayList import javax.swing.JFrame - /** - * Extension of {@link hevs.graphics.FunGraphics} that manages a list of {@link hevs.graphics.advanced.Drawable} - * objects that are displayed using the {@link # repaint ( )} method. + * Extension of [[hevs.graphics.FunGraphics]] that manages a list of [[hevs.graphics.advanced.Drawable]] + * objects that are displayed using the [[repaint]] method. + * + * @param width Width of the window + * @param height Height of the window + * @param title Title of the window + * @param highQuality Use high quality rendering */ class ListGraphics(override val width: Int, override val height: Int, override val title: String, val highQuality: Boolean) extends FunGraphics(width, height, title, highQuality) { private[advanced] var mouseListener:MouseListener = null private[advanced] val backgroundColor = Color.white + /** + * Creates a graphic window to draw onto. + * + * @param width Width of the display window + * @param height Height of the display window + * @param title Title of the display window + */ def this(width: Int, height: Int, title: String) = { this(width, height, title, true) } private val objectsToBeDrawn:util.List[Drawable] = Collections.synchronizedList(new CopyOnWriteArrayList[Drawable]) + /** + * Sets the [[MouseListener]] to the window to react on mouse events + * + * @param mouseListener The [[MouseListener]] + */ def setMouseListener(mouseListener: MouseListener): Unit = { this.mouseListener = mouseListener mainFrame.addMouseListener(mouseListener) } + /** + * Sets the background color used when clearing the window + * @param c the new background color + */ def setBackgroundColor(c: Color): Unit = { g2d.setBackground(c) } /** - * register a new keyboard listener to main window + * Register a new keyboard listener to main window * - * @param listener + * @param listener the [[KeyListener]] */ def registerKeyListener(listener: KeyListener): Unit = { mainFrame.addKeyListener(listener) } /** - * Add a new object that will be drawn + * Adds a new object that will be drawn * - * @param d - * The object to draw + * @param d the object to draw */ def addDrawableObject(d: Drawable): Unit = { objectsToBeDrawn.add(d) @@ -61,16 +79,18 @@ class ListGraphics(override val width: Int, override val height: Int, override v } /** - * Remove an object to the list + * Removes an object from the list * - * @param d - * The object to remove + * @param d the object to remove */ def removeDrawableObjects(d: Drawable): Unit = { objectsToBeDrawn synchronized objectsToBeDrawn.remove(d) - } + /** + * Gets the main [[JFrame]] + * @return the [[JFrame]] of the window + */ def getDisplayFrame: JFrame = this.mainFrame /** diff --git a/src/main/scala/hevs/graphics/advanced/samples/ComplexTesterWithImage.scala b/src/main/scala/hevs/graphics/advanced/samples/ComplexTesterWithImage.scala index b75906f..b0d9137 100644 --- a/src/main/scala/hevs/graphics/advanced/samples/ComplexTesterWithImage.scala +++ b/src/main/scala/hevs/graphics/advanced/samples/ComplexTesterWithImage.scala @@ -1,17 +1,13 @@ package hevs.graphics.advanced.samples -import hevs.graphics.advanced.Drawable -import hevs.graphics.advanced.ListGraphics +import hevs.graphics.advanced.{Drawable, ListGraphics} import hevs.graphics.utils.GraphicsBitmap + import java.awt.Color import java.util.Random - /** - * Performance testers for {@link ListGraphics} - * - * @author Pierre-Andre Mudry - * @version 1.0 + * A simple class representing a drawable image */ class ImageBackground extends Drawable { private[samples] val bmp = new GraphicsBitmap("/res/img/mandrill.jpg") @@ -24,7 +20,17 @@ class ImageBackground extends Drawable { } } +/** + * Performance testers for [[ListGraphics]] + * + * @author Pierre-Andre Mudry + * @version 1.0 + */ object ComplexTesterWithImage { + /** + * Complex tests with [[ListGraphics]] + * @param args unused + */ def main(args: Array[String]): Unit = { new ComplexTesterWithImage } diff --git a/src/main/scala/hevs/graphics/advanced/samples/DrawableCircle.scala b/src/main/scala/hevs/graphics/advanced/samples/DrawableCircle.scala index af5ec55..d5f0e01 100644 --- a/src/main/scala/hevs/graphics/advanced/samples/DrawableCircle.scala +++ b/src/main/scala/hevs/graphics/advanced/samples/DrawableCircle.scala @@ -1,10 +1,17 @@ package hevs.graphics.advanced.samples -import hevs.graphics.advanced.Drawable -import hevs.graphics.advanced.ListGraphics -import java.awt.Color +import hevs.graphics.advanced.{Drawable, ListGraphics} +import java.awt.Color +/** + * A simple class representing a drawable circle + * @param width the width of the circle (diameter) + * @param height the height of the circle (unused) + * @param x the X position of the top-left corner + * @param y the Y position of the top-left corner + * @param c the color of the circle + */ class DrawableCircle private[samples](var width: Int, var height: Int, var x: Int, var y: Int, var c: Color) extends Drawable { override def draw(g: ListGraphics): Unit = { g.setColor(c) diff --git a/src/main/scala/hevs/graphics/advanced/samples/ListGraphicsTester.scala b/src/main/scala/hevs/graphics/advanced/samples/ListGraphicsTester.scala index 0680175..01e7933 100644 --- a/src/main/scala/hevs/graphics/advanced/samples/ListGraphicsTester.scala +++ b/src/main/scala/hevs/graphics/advanced/samples/ListGraphicsTester.scala @@ -1,17 +1,21 @@ package hevs.graphics.advanced.samples import hevs.graphics.advanced.ListGraphics + import java.awt.Color import java.util.Random - /** - * Performance test application for {@link ListGraphics} + * Performance test application for [[ListGraphics]] * * @author Pierre-Andre Mudry * @version 1.0 */ object ListGraphicsTester { + /** + * Simple tests with [[ListGraphics]] + * @param args unused + */ def main(args: Array[String]): Unit = { new ListGraphicsTester } diff --git a/src/main/scala/hevs/graphics/interfaces/Graphics.scala b/src/main/scala/hevs/graphics/interfaces/Graphics.scala index 70ab847..be853f7 100644 --- a/src/main/scala/hevs/graphics/interfaces/Graphics.scala +++ b/src/main/scala/hevs/graphics/interfaces/Graphics.scala @@ -53,7 +53,7 @@ trait Graphics { * @param y * Y coordinate * @param c - * Color to use for this pixel (this pixel only, see {@link # setColor ( Color )} + * Color to use for this pixel (this pixel only, see [[setColor setColor(Color)]] */ def setPixel(x: Int, y: Int, c: Color): Unit @@ -78,7 +78,7 @@ trait Graphics { def setPenWidth(width: Float): Unit /** - * Draw a line from P1 to P2 in the color selected with setColor. + * Draw a line from `P1` to `P2` in the color selected with [[setColor]]. * * @param p1x * X coordinate of P1 @@ -94,13 +94,13 @@ trait Graphics { /** * Draw a filled polygon * - * @param p - * @param c + * @param p the polygon to draw + * @param c the color of the polygon */ def drawFilledPolygon(p: Polygon, c: Color): Unit /** - * Draw an empty rectangle in the color selected with setColor(). + * Draw an empty rectangle in the color selected with [[setColor]]. * * @param posX * X coordinate of the top left corner of the rectangle @@ -114,7 +114,7 @@ trait Graphics { def drawRect(posX: Int, posY: Int, width: Int, height: Int): Unit /** - * Draw a filled rectangle in the color selected with setColor. + * Draw a filled rectangle in the color selected with [[setColor]]. * * @param posX * X coordinate of the top left corner of the rectangle @@ -128,7 +128,7 @@ trait Graphics { def drawFillRect(posX: Int, posY: Int, width: Int, height: Int): Unit /** - * Draw an empty rectangle in the color selected with setColor + * Draw an empty rectangle in the color selected with [[setColor]] * * @param rect * rectangle to draw @@ -136,7 +136,7 @@ trait Graphics { def drawRect(rect: Rectangle): Unit /** - * Draw a filled rectangle in the color selected with setColor. + * Draw a filled rectangle in the color selected with [[setColor]]. * * @param rect * rectangle to draw @@ -162,10 +162,10 @@ trait Graphics { * X top-left position of the circle * @param posY * Y top-left position of the circle - * @param radius - * Radius of the drawn circle + * @param diameter + * Diameter of the drawn circle */ - def drawFilledCircle(posX: Int, posY: Int, radius: Int): Unit + def drawFilledCircle(posX: Int, posY: Int, diameter: Int): Unit /** * Draws an oval starting from (Top left X, Top left Y) @@ -234,9 +234,11 @@ trait Graphics { * @param color * the text color * @param halign - * the horizontal alignment (see {@link javax.swing.SwingConstants}) + * the horizontal alignment (see [[javax.swing.SwingConstants]]) + * Valid values: LEFT, CENTER and RIGHT * @param valign - * the vertical alignment (see {@link javax.swing.SwingConstants}) + * the vertical alignment (see [[javax.swing.SwingConstants]]) + * Valid values: TOP, CENTER and BOTTOM */ def drawString(posX: Int, posY: Int, @@ -259,15 +261,17 @@ trait Graphics { * @param fontFamily * the font family * @param fontStyle - * the font style (plain, bold, italics, ...) + * the font style ([[Font.PLAIN]], [[Font.BOLD]], [[Font.ITALIC]], ...) * @param fontSize * the font size * @param color * the text color * @param halign - * the horizontal alignment (see {@link javax.swing.SwingConstants}) + * the horizontal alignment (see [[javax.swing.SwingConstants]]) + * Valid values: LEFT, CENTER and RIGHT * @param valign - * the vertical alignment (see {@link javax.swing.SwingConstants}) + * the vertical alignment (see [[javax.swing.SwingConstants]]) + * Valid values: TOP, CENTER and BOTTOM */ def drawString(posX: Int, posY: Int, @@ -280,7 +284,7 @@ trait Graphics { valign: Int): Unit /** - * Write the given string at posX, posY + * Write the given string at `(posX, posY)` * * @param posX * Position x of the string @@ -299,15 +303,20 @@ trait Graphics { * Draws a text with a shadow * * @param posX + * X position of the string * @param posY + * Y position of the string * @param str + * the string to draw * @param color + * the text color * @param size + * the font size */ def drawFancyString(posX: Int, posY: Int, str: String, color: Color, size: Int): Unit /** - * Draws a text with a shadow or outline + * Draws a text with a shadow and/or outline * @param posX * X position of the string * @param posY @@ -317,15 +326,17 @@ trait Graphics { * @param fontFamily * the font family * @param fontStyle - * the font style (plain, bold, italics, ...) + * the font style ([[Font.PLAIN]], [[Font.BOLD]], [[Font.ITALIC]], ...) * @param fontSize * the font size * @param color * the text color * @param halign - * the horizontal alignment (see {@link javax.swing.SwingConstants}) + * the horizontal alignment (see [[javax.swing.SwingConstants]]) + * Valid values: LEFT, CENTER and RIGHT * @param valign - * the vertical alignment (see {@link javax.swing.SwingConstants}) + * the vertical alignment (see [[javax.swing.SwingConstants]]) + * Valid values: TOP, CENTER and BOTTOM * @param shadowX * the shadow's X offset * @param shadowY @@ -342,7 +353,7 @@ trait Graphics { def drawFancyString(posX: Int, posY: Int, str: String, fontFamily: String, fontStyle: Int, fontSize: Int, color: Color, halign: Int, valign: Int, shadowX: Int, shadowY: Int, shadowColor: Color, shadowThickness: Int, outlineColor: Color, outlineThickness: Int): Unit /** - * Draw a centered picture from a file (gif, jpg, png) to (posX, posY) + * Draw a centered picture from a file (gif, jpg, png) to `(posX, posY)` * * @param posX * X position of the image @@ -354,7 +365,7 @@ trait Graphics { def drawPicture(posX: Int, posY: Int, bitmap: GraphicsBitmap): Unit /** - * Draw a centered picture from a file (gif, jpg, png) to (posX, posY). Warning, + * Draw a centered picture from a file (gif, jpg, png) to `(posX, posY)`. Warning, * very slow because the image has to be * reloaded * @@ -364,13 +375,15 @@ trait Graphics { * Y position of the image * @param angle * The rotation angle of the image to be drawn + * @param scale + * The scale factor of the image to be drawn * @param imageName * path of the image file */ def drawTransformedPicture(posX: Int, posY: Int, angle: Double, scale: Double, imageName: String): Unit /** - * Draw a centered picture from a file (gif, jpg, png) to (posX, posY) + * Draw a centered picture from a file (gif, jpg, png) to `(posX, posY)` * * @param posX * X position of the image @@ -378,13 +391,15 @@ trait Graphics { * Y position of the image * @param angle * The rotation angle of the image to be drawn + * @param scale + * The scale factor of the image to be drawn * @param bitmap * A bitmap */ def drawTransformedPicture(posX: Int, posY: Int, angle: Double, scale: Double, bitmap: GraphicsBitmap): Unit /** - * Draw a mirrored centered picture from a file (gif, jpg, png) to (posX, posY) + * Draw a mirrored centered picture from a file (gif, jpg, png) to `(posX, posY)` * * @param posX * X position of the image diff --git a/src/main/scala/hevs/graphics/samples/TestDrawString.scala b/src/main/scala/hevs/graphics/samples/TestDrawString.scala index 4d0a755..b70aefe 100644 --- a/src/main/scala/hevs/graphics/samples/TestDrawString.scala +++ b/src/main/scala/hevs/graphics/samples/TestDrawString.scala @@ -3,11 +3,10 @@ package hevs.graphics.samples import hevs.graphics.FunGraphics import java.awt.{Color, Font} -import java.awt.geom.Rectangle2D import javax.swing.SwingConstants /** - * Sample for drawString methods + * Sample for `drawString` and `drawFancyString` methods of [[FunGraphics]] * * @author Louis Heredero */ diff --git a/src/main/scala/hevs/graphics/samples/TestTurtleGraphics.scala b/src/main/scala/hevs/graphics/samples/TestTurtleGraphics.scala index 8227481..2e75b07 100644 --- a/src/main/scala/hevs/graphics/samples/TestTurtleGraphics.scala +++ b/src/main/scala/hevs/graphics/samples/TestTurtleGraphics.scala @@ -2,12 +2,10 @@ package hevs.graphics.samples import hevs.graphics.TurtleGraphics - /** - * Sample for {@link TurtleGraphics} class + * Sample for [[TurtleGraphics]] class * * @author Pierre-André Mudry - * */ object TestTurtleGraphics extends App { val t = new TurtleGraphics(500, 500, "Test of Turtle Graphics") diff --git a/src/main/scala/hevs/graphics/utils/GraphicTimer.scala b/src/main/scala/hevs/graphics/utils/GraphicTimer.scala index e4cb3bf..4490131 100644 --- a/src/main/scala/hevs/graphics/utils/GraphicTimer.scala +++ b/src/main/scala/hevs/graphics/utils/GraphicTimer.scala @@ -2,11 +2,11 @@ package hevs.graphics.utils /** - * Provides a way to get a fixed framerate when calling the - * sync method in the game loop with the desired - * frame-rate + * Provides a way to get a fixed frame rate when calling the + * [[sync]] method in the game loop with the desired + * frame rate * - * Adapted from http://www.java-gaming.org/index.php?topic=22933.5 + * Adapted from [[http://www.java-gaming.org/index.php?topic=22933.5]] * * @author Pierre-Andre Mudry */ @@ -16,11 +16,11 @@ class GraphicTimer() { /** * Periodic call to this method in the main loop - * insures a constant frame-rate. This is achieved in the + * insures a constant frame rate. This is achieved in the * method itself by waiting a variable amount of time to get - * a constant frame-rate + * a constant frame rate * - * @param fps The desired frame-rate + * @param fps The desired frame rate */ def sync(fps: Int): Unit = { Thread.`yield`() diff --git a/src/main/scala/hevs/graphics/utils/GraphicsBitmap.scala b/src/main/scala/hevs/graphics/utils/GraphicsBitmap.scala index c634553..ae08be7 100644 --- a/src/main/scala/hevs/graphics/utils/GraphicsBitmap.scala +++ b/src/main/scala/hevs/graphics/utils/GraphicsBitmap.scala @@ -1,15 +1,13 @@ package hevs.graphics.utils -import java.awt.GraphicsConfiguration -import java.awt.GraphicsEnvironment +import java.awt.{GraphicsConfiguration, GraphicsEnvironment} import java.awt.image.BufferedImage -import java.net.URL import javax.imageio.ImageIO /** - * GraphicsBitmap contains the methods required to create a BufferedImage from a - * String if the file exists + * GraphicsBitmap contains the methods required to create a [[BufferedImage]] from a + * [[String]] if the file exists * * 1.3 : Added acceleration for images using graphics card * @@ -48,8 +46,8 @@ class GraphicsBitmap(val name: String) { // Get optimized image def getHeight: Int = HEIGHT /** - * @return the {@link BufferedImage} corresponding to the - * {@link GraphicsBitmap} + * @return the [[BufferedImage]] corresponding to the + * [[GraphicsBitmap]] */ def getBufferedImage: BufferedImage = mBitmap } diff --git a/src/main/scala/hevs/graphics/utils/RepeatingReleasedEventsFixer.scala b/src/main/scala/hevs/graphics/utils/RepeatingReleasedEventsFixer.scala index b68e33e..7306938 100644 --- a/src/main/scala/hevs/graphics/utils/RepeatingReleasedEventsFixer.scala +++ b/src/main/scala/hevs/graphics/utils/RepeatingReleasedEventsFixer.scala @@ -1,22 +1,15 @@ package hevs.graphics.utils -import java.awt.AWTEvent -import java.awt.Component -import java.awt.EventQueue -import java.awt.Toolkit -import java.awt.event.AWTEventListener -import java.awt.event.ActionEvent -import java.awt.event.ActionListener -import java.awt.event.KeyEvent +import java.awt.{AWTEvent, Component, EventQueue, Toolkit} +import java.awt.event.{AWTEventListener, ActionEvent, ActionListener, KeyEvent} import java.util -import java.util.{HashMap, Map} import javax.swing.Timer -/** * +/** * Fixes the discrepancies between keyboard handling under Windows and linux - * for repeated keys. Taken from http://tech.stolsvik.com/2010/05/linux-java-repeats-released-keyevents.html + * for repeated keys. Taken from [[http://tech.stolsvik.com/2010/05/linux-java-repeats-released-keyevents.html]] * * @author Pierre-André Mudry */ @@ -36,7 +29,12 @@ object RepeatingReleasedEventsFixer { class RepostedKeyEvent(@SuppressWarnings(Array("hiding")) source: Component, @SuppressWarnings(Array("hiding")) id: Int, when: Long, modifiers: Int, keyCode: Int, keyChar: Char, keyLocation: Int) extends KeyEvent(source, id, when, modifiers, keyCode, keyChar, keyLocation) with RepeatingReleasedEventsFixer.Reposted { } - private def assertEDT = { + /** + * Asserts that the current thread is the event dispatching thread + * @throws AssertionError the current thread is not the EDT + * @return `true` if the current thread is the EDT + */ + private def assertEDT: Boolean = { if (!EventQueue.isDispatchThread) throw new AssertionError("Not EDT, but [" + Thread.currentThread + "].") true } @@ -45,10 +43,16 @@ object RepeatingReleasedEventsFixer { class RepeatingReleasedEventsFixer extends AWTEventListener { final private val _map = new util.HashMap[Integer, RepeatingReleasedEventsFixer#ReleasedAction] + /** + * Installs the key event listener + */ def install(): Unit = { Toolkit.getDefaultToolkit.addAWTEventListener(this, AWTEvent.KEY_EVENT_MASK) } + /** + * Removes the key event listener + */ def remove(): Unit = { Toolkit.getDefaultToolkit.removeAWTEventListener(this) } @@ -96,10 +100,13 @@ class RepeatingReleasedEventsFixer extends AWTEventListener { } /** - * The ActionListener that posts the RELEASED {@link RepostedKeyEvent} if the {@link Timer} times out (and hence the + * The [[ActionListener]] that posts the [[KeyEvent.KEY_RELEASED]] [[RepeatingReleasedEventsFixer.RepostedKeyEvent]] if the [[Timer]] times out (and hence the * repeat-action was over). */ private class ReleasedAction private[utils](val _originalKeyEvent: KeyEvent, var _timer: Timer) extends ActionListener { + /** + * Stops the timer and removes the the key event from the map of repeating actions + */ private[utils] def cancel(): Unit = { assert(RepeatingReleasedEventsFixer.assertEDT) _timer.stop() diff --git a/src/main/scala/hevs/utils/DateUtils.scala b/src/main/scala/hevs/utils/DateUtils.scala index 88a0073..3c4e966 100644 --- a/src/main/scala/hevs/utils/DateUtils.scala +++ b/src/main/scala/hevs/utils/DateUtils.scala @@ -30,17 +30,21 @@ object DateUtils { theDate } - private def nMsec(a: Date, b: Date) = if (b.after(a)) b.getTime - a.getTime + /** + * Computes the number of milliseconds between two dates + * @param a the first date + * @param b the second date + * @return the number of milliseconds between the two dates + */ + private def nMsec(a: Date, b: Date): Long = if (b.after(a)) b.getTime - a.getTime else a.getTime - b.getTime /** * Computes the number of hours between two dates * - * @param a - * The first date - * @param b - * The second date - * @return The number of hours between the two dates + * @param a the first date + * @param b the second date + * @return the number of hours between the two dates */ def nHours(a: Date, b: Date): Int = { val n = nMsec(a, b) / msPerHour @@ -48,20 +52,21 @@ object DateUtils { } /** - * Computes the number of day between two dates + * Computes the number of days between two dates * - * @param a - * The first date - * @param b - * The second date - * @return The number of days between the two dates + * @param a the first date + * @param b the second date + * @return the number of days between the two dates */ def nDays(a: Date, b: Date): Int = { val nDays = nMsec(a, b) / msPerDay nDays.toInt } - // Some samples + /** + * Some sample tests + * @param args unused + */ def main(args: Array[String]): Unit = { val first = DateUtils.createDate("1/1/2000") val second = DateUtils.createDate("1/1/2001") diff --git a/src/main/scala/hevs/utils/Input.scala b/src/main/scala/hevs/utils/Input.scala index e222182..034ad87 100644 --- a/src/main/scala/hevs/utils/Input.scala +++ b/src/main/scala/hevs/utils/Input.scala @@ -2,28 +2,29 @@ package hevs.utils import java.io.{BufferedReader, InputStreamReader} - /** - * * The Class Input is here to enter data with the keyboard.
- * The types below are supported by the Input class.
+ * The class [[Input]] is here to enter data with the keyboard.
+ * The types below are supported by the [[Input]] class.
*
- * - String
- * - Integer (int)
- * - Double (double) - Boolean (boolean)
- * - Character (char)
+ * - [[String]]
+ * - [[Int]]
+ * - [[Double]]
+ * - [[Boolean]]
+ * - [[Char]]
*
* - * @see #readString() - * @see #readDouble() - * @see #readBoolean() - * @see #readChar() + * @see [[readString]] + * @see [[readInt]] + * @see [[readDouble]] + * @see [[readBoolean]] + * @see [[readChar]] */ object Input { /** - * * Reads a valid char value from the console. + * Reads a valid [[Char]] value from the console. * - * @return The typed char - * @see java.lang.Character + * @return The typed [[Char]] + * @see [[java.lang.Character]] */ def readChar(): Char = { var ok = false @@ -42,10 +43,10 @@ object Input { } /** - * * Reads a String from the console. + * Reads a [[String]] from the console. * - * @return The typed string - * @see java.lang.String + * @return The typed [[String]] + * @see [[java.lang.String]] */ def readString(): String = { val stdin = new BufferedReader(new InputStreamReader(System.in)) @@ -57,10 +58,12 @@ object Input { } /** - * * Reads a valid integer value from the console. + * Reads a valid integer value from the console. + * + * This method also accepts hexadecimal values prefixed by "0x" or "0X" * - * @return The typed value - * @see java.lang.Integer + * @return The typed [[Int]] + * @see [[java.lang.Integer]] */ def readInt(): Int = { var ok = false @@ -81,10 +84,10 @@ object Input { } /** - * * Reads a valid double value from the console. + * Reads a valid [[Double]] value from the console. * - * @return The typed double value - * @see java.lang.Double + * @return The typed [[Double]] value + * @see [[java.lang.Double]] */ def readDouble(): Double = { var ok = false @@ -103,10 +106,10 @@ object Input { } /** - * * Reads a valid boolean value from the console. + * Reads a valid [[Boolean]] value from the console. * - * @return the value true if the typed value is true, false otherwise. - * @see java.lang.Boolean + * @return the value `true` if the typed value is true, `false` otherwise. + * @see [[java.lang.Boolean]] */ def readBoolean(): Boolean = { var ok = false diff --git a/src/main/scala/hevs/utils/ResourceList.scala b/src/main/scala/hevs/utils/ResourceList.scala index f534d31..5ebbc65 100644 --- a/src/main/scala/hevs/utils/ResourceList.scala +++ b/src/main/scala/hevs/utils/ResourceList.scala @@ -5,23 +5,21 @@ import java.util import java.util.regex.Pattern import java.util.zip.{ZipEntry, ZipException, ZipFile} -/* - * source : https://stackoverflow.com/a/3923182/2069348 - * licence : CC BY-SA 4.0 - * author : jmj (https://stackoverflow.com/users/260990/jmj) - */ - - /** - * list resources available from the classpath @ * + * List resources available from the classpath + * + * Licence : CC BY-SA 4.0 + * @author jmj + * @see [[https://stackoverflow.com/a/3923182/2069348]] */ object ResourceList { /** - * for all elements of java.class.path get a Collection of resources Pattern - * pattern = Pattern.compile(".*"); gets all resources + * Gets all resources matching the specified pattern + * in the classpath + * To get all resources, pass the pattern ".*": + * {{{Pattern pattern = Pattern.compile(".*")}}} * - * @param pattern - * the pattern to match + * @param pattern the pattern to match * @return the resources in the order they are found */ def getResources(pattern: Pattern): util.Collection[String] = { @@ -34,7 +32,14 @@ object ResourceList { retval } - private def getResources(element: String, pattern: Pattern) = { + /** + * Gets all resources matching the specified pattern + * in the given path element + * @param element the path element (a directory or .jar file) + * @param pattern the pattern to match + * @return the resources in the order they are found + */ + private def getResources(element: String, pattern: Pattern): util.Collection[String] = { val retval = new util.ArrayList[String] val file = new File(element) if (file.isDirectory) retval.addAll(getResourcesFromDirectory(file, pattern)) @@ -42,7 +47,14 @@ object ResourceList { retval } - private def getResourcesFromJarFile(file: File, pattern: Pattern) = { + /** + * Gets all resources matching the specified pattern + * in the given .jar file + * @param file the .jar file + * @param pattern the pattern to match + * @return the resources in the order they are found + */ + private def getResourcesFromJarFile(file: File, pattern: Pattern): util.Collection[String] = { val retval = new util.ArrayList[String] var zf: ZipFile = null try zf = new ZipFile(file) @@ -69,6 +81,13 @@ object ResourceList { retval } + /** + * Gets all resources matching the specified pattern + * in the given directory + * @param directory the directory to search in + * @param pattern the pattern to match + * @return the resources in the order they are found + */ private def getResourcesFromDirectory(directory: File, pattern: Pattern): util.ArrayList[String] = { val retval = new util.ArrayList[String] val fileList = directory.listFiles @@ -87,10 +106,10 @@ object ResourceList { } /** - * list the resources that match args[0] + * Lists the resources that match `args(0)` * * @param args - * args[0] is the pattern to match, or list all resources if + * args(0) is the pattern to match, or list all resources if * there are no args */ def main(args: Array[String]): Unit = { diff --git a/src/main/scala/hevs/utils/StringFunctions.scala b/src/main/scala/hevs/utils/StringFunctions.scala index d4d7be5..6b40d6c 100644 --- a/src/main/scala/hevs/utils/StringFunctions.scala +++ b/src/main/scala/hevs/utils/StringFunctions.scala @@ -1,24 +1,27 @@ package hevs.utils +/** + * Utility class with useful methods for string manipulation + */ object StringFunctions { /** - * Get the number of characters in a String + * Get the number of characters in a [[String]] * * @param s the string - * @return The length (number of characters) of the String s + * @return The length (number of characters) of the [[String]] s */ def stringLength(s: String): Int = s.length /** - * Get one character from a String + * Get one character from a [[String]] * * Example : - * stringCharAt("hello", 0) returns 'h' - * stringCharAt("hello", 1) returns 'e' + * - `stringCharAt("hello", 0)` returns 'h' + * - `stringCharAt("hello", 1)` returns 'e' * - * @param s the String + * @param s the [[String]] * @param pos the position of the character - * @return The char at position pos in s + * @return The [[Char]] at position `pos` in `s` */ def stringCharAt(s: String, pos: Int): Char = s.charAt(pos) } diff --git a/src/main/scala/hevs/utils/TextTools.scala b/src/main/scala/hevs/utils/TextTools.scala index 93ab1d4..911c4a6 100644 --- a/src/main/scala/hevs/utils/TextTools.scala +++ b/src/main/scala/hevs/utils/TextTools.scala @@ -1,12 +1,10 @@ package hevs.utils -import java.io.BufferedReader -import java.io.InputStreamReader - +import java.io.{BufferedReader, InputStreamReader} /** * A class with functions to manipulate text strings. Based on an old - * TextTools version that hid all the strings in static variables + * `TextTools` version that hid all the strings in static variables * inside the class. This has all been removed and now everything is explicit * and exposed. * @@ -27,8 +25,10 @@ object TextTools { } /** - * Get an integer value from the console. Can read octal and hexadecimal - * formats as well + * Get an integer value from the console. + * Can read octal and hexadecimal formats as well (prefixed by `0`, respectively `0x`/`0X`) + * @return the typed [[Int]] + * @see [[Integer]] */ def readInt(): Int = { System.out.print("Enter an integer value in decimal, octal or hexadecimal format : ") @@ -46,6 +46,8 @@ object TextTools { /** * Get a double value from the console. + * @return they typed [[Double]] + * @see [[java.lang.Double]] */ def readDouble(): Double = { System.out.print("Enter a double value : ") @@ -58,7 +60,9 @@ object TextTools { } /** - * Read a boolean value (true, false) from the console. + * Get a boolean value (`true`, `false`) from the console. + * @return `true` if the typed value is true, `false` otherwise + * @see [[java.lang.Boolean]] */ def readBoolean(): Boolean = { System.out.print("Enter a boolean value : ") @@ -71,7 +75,9 @@ object TextTools { } /** - * Get a char from the console. + * Get a [[Char]] from the console. + * @return the typed [[Char]] + * @see [[Character]] */ def readChar(): Char = { System.out.print("Enter a character : ") @@ -84,10 +90,10 @@ object TextTools { } /** - * Reverse the given string input ... + * Reverse the given string `input` * - * @param input - * as string : the given string + * @param input the string to reverse + * @return the reversed string */ def reverse(input: String): String = { var output = new String("") @@ -98,26 +104,26 @@ object TextTools { } /** - * Converts all of the characters in this String to upper case. + * Converts all of the characters in this [[String]] to upper case. * - * @param input - * as string : the given string + * @param input the string to convert + * @return the converted string */ def toUpperCase(input: String): String = input.toUpperCase /** - * Converts all of the characters in this String to lower case. + * Converts all of the characters in this [[String]] to lower case. * - * @param input - * as string : the given string + * @param input the string to convert + * @return the converted string */ def toLowerCase(input: String): String = input.toLowerCase /** - * Converts the first character of this String to upper case. + * Converts the first character of this [[String]] to upper case. * - * @param input - * as string : the given string + * @param input the string to convert + * @return the converted string */ def capitalize(input: String): String = { var output = String.valueOf(input.charAt(0)).toUpperCase @@ -128,23 +134,26 @@ object TextTools { } /** - * Inverts a complete String + * Inverts a complete [[String]] (left to right) * - * @param input + * @param input the string to invert * @return the inverted String + * @see [[reverse]] */ def invert(input: String): String = invert(input, input.length) /** - * Inverts the characters of the input string by group of - * number characters + * Inverts the characters of the input string by groups of + * `number` characters + * + * Example : + * - invert("Hello World !", 4) returns "lleHoW o dlr!" * - * @param input - * as string : the given string - * @param number - * as int : the number of charaters to invert + * @param input the string to invert + * @param number the size of each group + * @return the inverted string */ - private def invert(input: String, number: Int) = { + private def invert(input: String, number: Int): String = { var i = 0 var output = new String("") if (input.length >= number) { @@ -169,10 +178,10 @@ object TextTools { } /** - * Hide any vowel in a string + * Replaces every vowel in the given string with ' ' * - * @param input - * as string : the given string + * @param input the string to obfuscate + * @return the obfuscated string */ def deleteVowels(input: String): String = { var ASCII = 0 @@ -186,10 +195,10 @@ object TextTools { } /** - * Deletes each consonant in a string + * Replaces every consonant in the given string with ' ' * - * @param input - * as string : the given string + * @param input the string to obfuscate + * @return the obfuscated string */ def deleteConsonants(input: String): String = { var ASCII = 0 @@ -203,10 +212,10 @@ object TextTools { } /** - * Encrypts a string + * Encrypts a string using a variant of the Caesar-5 cipher (using all values in [0,255]) * - * @param input - * as string : the given string + * @param input the string to encrypt + * @return the encrypted string */ def encrypt(input: String): String = { var output = new String("") @@ -217,10 +226,10 @@ object TextTools { } /** - * Decrypts an encrypted string + * Decrypts a string using a variant of the Caesar-5 cipher (using all values in [0,255]) * - * @param input - * as string : the given string + * @param input the string to decrypt + * @return the decrypted string */ def decrypt(input: String): String = { var output = new String("")