feat(ecl-auto): More documentation and "useCustom" methods for JVM+Android

Author: rafaellins-swile

src/androidMain/kotlin/qrcode/render/QRCodeGraphics.android.kt

@@ -23,16 +23,45 @@ actual open class QRCodeGraphics actual constructor(
     val height: Int,
 ) {
     companion object {
-        val AVAILABLE_FORMATS: Array<String> = CompressFormat.values().map { it.name }.toTypedArray()
+        val AVAILABLE_FORMATS: Array<String> = CompressFormat.entries.map { it.name }.toTypedArray()
     }
 
     protected fun createCanvas(image: Bitmap) = Canvas(image)
 
+    /** [Bitmap] being used for the drawing operations. */
     private var image: Bitmap = Bitmap.createBitmap(width, height, ARGB_8888)
+
+    /** [Canvas] that handles the presenting. */
     private var canvas: Canvas = createCanvas(image)
+
+    /** Cache of [Paint] objects being used. Just to try and use the least amount of CPU/memory possible. */
     private val paintCache = mutableMapOf<Int, Paint>()
+
+    /** Whether any drawing operations were done or not. */
     private var changed: Boolean = false
 
+    /** Whether the user set the value of [canvas]. */
+    private var customCanvas = false
+    private var customCanvasOffsetX: Int = 0
+    private var customCanvasOffsetY: Int = 0
+
+    /**
+     * Allows this object to draw directly to a user specified [Canvas].
+     *
+     * It'll invoke [Canvas.setBitmap] with the [Bitmap] being used to draw.
+     *
+     * @see image
+     */
+    fun useCustomCanvas(canvas: Canvas, offsetX: Int = 0, offsetY: Int = 0): QRCodeGraphics {
+        customCanvas = true
+        this.canvas = canvas
+        this.canvas.setBitmap(image)
+        customCanvasOffsetX = offsetX
+        customCanvasOffsetY = offsetY
+
+        return this
+    }
+
     /**
      * Keeps a simple color cache. The default style is [FILL].
      */
@@ -48,8 +77,13 @@ actual open class QRCodeGraphics actual constructor(
         }
     }
 
-    protected fun rect(x: Int, y: Int, w: Int, h: Int): RectF =
-        RectF(x.toFloat(), y.toFloat(), (x + w).toFloat(), (y + h).toFloat())
+    protected fun buildRectF(x: Int, y: Int, w: Int, h: Int): RectF =
+        RectF(
+            (x + customCanvasOffsetX).toFloat(),
+            (y + customCanvasOffsetY).toFloat(),
+            (x + w + customCanvasOffsetX).toFloat(),
+            (y + h + customCanvasOffsetY).toFloat(),
+        )
 
     /** Returns `true` if **any** drawing was performed */
     actual open fun changed() = changed
@@ -59,7 +93,12 @@ actual open class QRCodeGraphics actual constructor(
         if (changed) {
             changed = false
             image = Bitmap.createBitmap(width, height, ARGB_8888)
-            canvas = createCanvas(image)
+
+            if (!customCanvas) {
+                canvas = createCanvas(image)
+            } else {
+                this.canvas.setBitmap(image)
+            }
         }
     }
 
@@ -106,7 +145,7 @@ actual open class QRCodeGraphics actual constructor(
     private fun toCompressFormat(format: String) =
         try {
             CompressFormat.valueOf(format.uppercase())
-        } catch (e: Throwable) {
+        } catch (_: Throwable) {
             PNG
         }
 
@@ -116,7 +155,6 @@ actual open class QRCodeGraphics actual constructor(
      * @see CompressFormat
      * @see CompressFormat.PNG
      * @see CompressFormat.JPEG
-     * @see CompressFormat.WEBP
      */
     actual open fun availableFormats(): Array<String> = AVAILABLE_FORMATS
 
@@ -126,24 +164,37 @@ actual open class QRCodeGraphics actual constructor(
     /** Draw a straight line from point `(x1,y1)` to `(x2,y2)`. */
     actual open fun drawLine(x1: Int, y1: Int, x2: Int, y2: Int, color: Int, thickness: Double) {
         canvas.drawLine(
-            x1.toFloat(),
-            y1.toFloat(),
-            x2.toFloat(),
-            y2.toFloat(),
+            (x1 + customCanvasOffsetX).toFloat(),
+            (y1 + customCanvasOffsetY).toFloat(),
+            (x2 + customCanvasOffsetX).toFloat(),
+            (y2 + customCanvasOffsetY).toFloat(),
             paintFromCache(color, STROKE, thickness),
         )
     }
 
     /** Draw the edges of a rectangle starting at point `(x,y)` and having `width` by `height`. */
     actual open fun drawRect(x: Int, y: Int, width: Int, height: Int, color: Int, thickness: Double) {
         val halfThickness = (thickness / 2.0).roundToInt()
-        val rect = Rect(x + halfThickness, y + halfThickness, x + width - halfThickness, y + height - halfThickness)
+        val rect = Rect(
+            x + halfThickness + customCanvasOffsetX,
+            y + halfThickness + customCanvasOffsetY,
+            x + width - halfThickness + customCanvasOffsetX,
+            y + height - halfThickness + customCanvasOffsetY,
+        )
         canvas.drawRect(rect, paintFromCache(color, STROKE, thickness))
     }
 
     /** Fills the rectangle starting at point `(x,y)` and having `width` by `height`. */
     actual open fun fillRect(x: Int, y: Int, width: Int, height: Int, color: Int) {
-        canvas.drawRect(Rect(x, y, x + width, y + height), paintFromCache(color))
+        canvas.drawRect(
+            Rect(
+                x + customCanvasOffsetX,
+                y + customCanvasOffsetY,
+                x + width + customCanvasOffsetX,
+                y + height + customCanvasOffsetY,
+            ),
+            paintFromCache(color),
+        )
     }
 
     /** Fill the whole area of this canvas with the specified [color]. */
@@ -184,7 +235,7 @@ actual open class QRCodeGraphics actual constructor(
         val halfThickness = (thickness / 2.0).roundToInt()
 
         canvas.drawRoundRect(
-            rect(x + halfThickness, y + halfThickness, width - halfThickness * 2, height - halfThickness * 2),
+            buildRectF(x + halfThickness, y + halfThickness, width - halfThickness * 2, height - halfThickness * 2),
             borderRadius.toFloat(),
             borderRadius.toFloat(),
             paintFromCache(color, STROKE, thickness),
@@ -214,7 +265,7 @@ actual open class QRCodeGraphics actual constructor(
      */
     actual open fun fillRoundRect(x: Int, y: Int, width: Int, height: Int, borderRadius: Int, color: Int) {
         canvas.drawRoundRect(
-            rect(x, y, width, height),
+            buildRectF(x, y, width, height),
             borderRadius.toFloat(),
             borderRadius.toFloat(),
             paintFromCache(color),
@@ -226,7 +277,7 @@ actual open class QRCodeGraphics actual constructor(
      */
     actual fun drawEllipse(x: Int, y: Int, width: Int, height: Int, color: Int, thickness: Double) {
         canvas.drawOval(
-            rect(x, y, width, height),
+            buildRectF(x, y, width, height),
             paintFromCache(color, STROKE, thickness),
         )
     }
@@ -237,7 +288,7 @@ actual open class QRCodeGraphics actual constructor(
      */
     actual fun fillEllipse(x: Int, y: Int, width: Int, height: Int, color: Int) {
         canvas.drawOval(
-            rect(x, y, width, height),
+            buildRectF(x, y, width, height),
             paintFromCache(color),
         )
     }
@@ -246,12 +297,15 @@ actual open class QRCodeGraphics actual constructor(
      * Reads the specified image from [rawData] and draws it at `(x,y)`
      */
     actual fun drawImage(rawData: ByteArray?, x: Int, y: Int) {
-        if (rawData != null && rawData.isNotEmpty()) {
+        if (rawData != null && rawData.isNotEmpty()) { // NOSONAR
             val imgBitmap = BitmapFactory.decodeByteArray(rawData, 0, rawData.size)
             drawImage(imgBitmap, x, y)
         }
     }
 
+    /**
+     * Draws a [Bitmap] at the specified `(x,y)`
+     */
     open fun drawImage(img: Bitmap, x: Int, y: Int) {
         changed = true
         canvas.drawBitmap(img, x.toFloat(), y.toFloat(), null)

src/jvmMain/kotlin/qrcode/render/QRCodeGraphics.jvm.kt

@@ -21,15 +21,41 @@ actual open class QRCodeGraphics actual constructor(
     private lateinit var image: BufferedImage
     private val colorCache = HashMap<Int, Color>()
     private var changed: Boolean = false
+    private var customImage = false
+    private var customImageOffsetX: Int = 0
+    private var customImageOffsetY: Int = 0
 
+    /**
+     * Use a custom, user-defined [BufferedImage] instead of the internal, default one.
+     *
+     * After calling this method, all drawing operations will be offset by [offsetX], [offsetY] as to make the QRCode
+     * look like it was drawn at that position within the image.
+     */
+    fun useCustomBufferedImage(bufferedImage: BufferedImage, offsetX: Int = 0, offsetY: Int = 0): QRCodeGraphics {
+        customImage = true
+        image = bufferedImage
+        customImageOffsetX = offsetX
+        customImageOffsetY = offsetY
+
+        return this
+    }
+
+    /**
+     * Creates a [BufferedImage] if needed. Does nothing if [customImage] is `true`.
+     */
     protected open fun createImage(force: Boolean = false): BufferedImage {
-        if (force || !this::image.isInitialized) {
+        if (!customImage && (force || !this::image.isInitialized)) {
             image = BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB)
+            customImageOffsetX = 0
+            customImageOffsetY = 0
         }
 
         return image
     }
 
+    /**
+     * Create instances of [Graphics2D] so that drawing operations can be done.
+     */
     protected open fun createGraphics(): Graphics2D = createImage().createGraphics()
 
     /**
@@ -114,25 +140,37 @@ actual open class QRCodeGraphics actual constructor(
 
     /** Draw a straight line from point `(x1,y1)` to `(x2,y2)`. */
     actual open fun drawLine(x1: Int, y1: Int, x2: Int, y2: Int, color: Int, thickness: Double) {
-        draw(color, thickness) { it.drawLine(x1, y1, x2, y2) }
+        draw(color, thickness) {
+            it.drawLine(
+                x1 + customImageOffsetX,
+                y1 + customImageOffsetY,
+                x2 + customImageOffsetX,
+                y2 + customImageOffsetY,
+            )
+        }
     }
 
     /** Draw the edges of a rectangle starting at point `(x,y)` and having `width` by `height`. */
     actual open fun drawRect(x: Int, y: Int, width: Int, height: Int, color: Int, thickness: Double) {
         draw(color, thickness) {
             val halfThickness = (thickness / 2.0).roundToInt().coerceAtLeast(0)
-            it.drawRect(x + halfThickness, y + halfThickness, width - halfThickness * 2, height - halfThickness * 2)
+            it.drawRect(
+                x + halfThickness + customImageOffsetX,
+                y + halfThickness + customImageOffsetY,
+                width - halfThickness * 2,
+                height - halfThickness * 2,
+            )
         }
     }
 
     /** Fills the rectangle starting at point `(x,y)` and having `width` by `height`. */
     actual open fun fillRect(x: Int, y: Int, width: Int, height: Int, color: Int) {
-        draw(color) { it.fillRect(x, y, width, height) }
+        draw(color) { it.fillRect(x + customImageOffsetX, y + customImageOffsetY, width, height) }
     }
 
     /** Fill the whole area of this canvas with the specified [color]. */
     actual open fun fill(color: Int) {
-        fillRect(0, 0, width, height, color)
+        fillRect(0 + customImageOffsetX, 0 + customImageOffsetY, width, height, color)
     }
 
     /**
@@ -168,8 +206,8 @@ actual open class QRCodeGraphics actual constructor(
         draw(color, thickness) {
             val halfThickness = (thickness / 2.0).roundToInt().coerceAtLeast(0)
             it.drawRoundRect(
-                x + halfThickness,
-                y + halfThickness,
+                x + halfThickness + customImageOffsetX,
+                y + halfThickness + customImageOffsetY,
                 width - halfThickness * 2,
                 height - halfThickness * 2,
                 borderRadius,
@@ -200,7 +238,16 @@ actual open class QRCodeGraphics actual constructor(
      *
      */
     actual open fun fillRoundRect(x: Int, y: Int, width: Int, height: Int, borderRadius: Int, color: Int) {
-        draw(color) { it.fillRoundRect(x, y, width, height, borderRadius, borderRadius) }
+        draw(color) {
+            it.fillRoundRect(
+                x + customImageOffsetX,
+                y + customImageOffsetY,
+                width,
+                height,
+                borderRadius,
+                borderRadius,
+            )
+        }
     }
 
     /**
@@ -211,8 +258,8 @@ actual open class QRCodeGraphics actual constructor(
             val halfThickness = (thickness / 2.0).roundToInt().coerceAtLeast(0)
             // The docs say the dimensions are width+1 and height+1... why? because f.u.
             it.drawOval(
-                x + halfThickness,
-                y + halfThickness,
+                x + halfThickness + customImageOffsetX,
+                y + halfThickness + customImageOffsetY,
                 width - 1 - halfThickness * 2,
                 height - 1 - halfThickness * 2,
             )
@@ -225,18 +272,18 @@ actual open class QRCodeGraphics actual constructor(
      */
     actual open fun fillEllipse(x: Int, y: Int, width: Int, height: Int, color: Int) {
         draw(color) {
-            it.fillOval(x, y, width, height)
+            it.fillOval(x + customImageOffsetX, y + customImageOffsetY, width, height)
         }
     }
 
     /**
      * Reads the specified image from [rawData] and draws it at `(x,y)`
      */
     actual open fun drawImage(rawData: ByteArray?, x: Int, y: Int) {
-        if (rawData != null && rawData.isNotEmpty()) {
+        if (rawData != null && rawData.isNotEmpty()) { // NOSONAR
             draw(0) {
                 ByteArrayInputStream(rawData).use { inStream ->
-                    drawImage(ImageIO.read(inStream), x, y)
+                    drawImage(ImageIO.read(inStream), x + customImageOffsetX, y + customImageOffsetY)
                 }
             }
         }
@@ -245,7 +292,7 @@ actual open class QRCodeGraphics actual constructor(
     open fun drawImage(image: BufferedImage?, x: Int, y: Int) {
         if (image != null) {
             draw(0) {
-                it.drawImage(image, x, y, null)
+                it.drawImage(image, x + customImageOffsetX, y + customImageOffsetY, null)
             }
         }
     }