# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.section Widgets
.topic widget.canvas
.title Canvas
.toc 0 Canvas
.index Canvas
.index wgtCanvas
.index wgtCanvasClear
.index wgtCanvasDrawLine
.index wgtCanvasDrawRect
.index wgtCanvasFillRect
.index wgtCanvasFillCircle
.index wgtCanvasSetPixel
.index wgtCanvasGetPixel
.index wgtCanvasDrawText
.index wgtCanvasSave
.index wgtCanvasLoad
.index wgtCanvasResize

.h2 Canvas

A freeform drawing surface with a fixed-size pixel buffer stored in the display's native pixel format. Provides drawing primitives (lines, rectangles, circles, text, individual pixels) and supports save/load to image files (BMP/PNG/etc. via dvxLoadImage/dvxSaveImage). Mouse interaction is available via a callback. The buffer is rendered to screen as a straight blit with no per-pixel conversion.

Canvas coordinates are independent of widget position: (0,0) is the top-left of the canvas content, not the widget. The widget frames the buffer with a 2-pixel sunken bevel.

Header: widgets/canvas.h

.h3 Creation

.code
WidgetT *cv = wgtCanvas(parent, 320, 200);
.endcode

.h3 API Functions

.index wgtCanvasSetPenColor
.index wgtCanvasSetPenSize
.index wgtCanvasSetMouseCallback

.table
  Function                                                             Description
  --------                                                             -----------
  WidgetT *wgtCanvas(parent, w, h)                                     Create a canvas with the given pixel dimensions. Buffer is initialized to white.
  void wgtCanvasClear(w, color)                                        Fill the entire canvas with a packed color.
  void wgtCanvasSetPenColor(w, color)                                  Set the drawing pen color (packed display color).
  void wgtCanvasSetPenSize(w, size)                                    Set the drawing pen size in pixels (affects DrawLine dot thickness).
  void wgtCanvasDrawLine(w, x0, y0, x1, y1)                           Draw a line using Bresenham's algorithm with the current pen color and size.
  void wgtCanvasDrawRect(w, x, y, width, height)                      Draw a 1-pixel rectangle outline using the current pen color.
  void wgtCanvasFillRect(w, x, y, width, height)                      Fill a rectangle using the current pen color.
  void wgtCanvasFillCircle(w, cx, cy, radius)                         Fill a circle using the current pen color (integer sqrt; no FPU needed).
  void wgtCanvasSetPixel(w, x, y, color)                              Set a single pixel to the given packed color.
  uint32_t wgtCanvasGetPixel(w, x, y)                                 Read a single pixel. Returns packed color.
  void wgtCanvasDrawText(w, x, y, text)                               Draw text at the given canvas coordinates using the current pen color.
  void wgtCanvasSetMouseCallback(w, cb)                                Set a mouse callback. Signature: void (*cb)(WidgetT *w, int32_t cx, int32_t cy, bool drag). cx/cy are canvas-relative, drag=true on mouse-move during press.
  int32_t wgtCanvasSave(w, path)                                       Save the canvas buffer to an image file. Returns 0 on success, -1 on error.
  int32_t wgtCanvasLoad(w, path)                                       Load an image file into the canvas (resizes buffer to match). Returns 0 on success, -1 on error.
  void wgtCanvasResize(w, newW, newH)                                 Resize the canvas buffer. New pixels are filled with white.
.endtable

.h3 API Struct (wgtRegisterApi "canvas")

.table
  Slot                 Function
  ----                 --------
  create               wgtCanvas
  clear                wgtCanvasClear
  setPenColor          wgtCanvasSetPenColor
  setPenSize           wgtCanvasSetPenSize
  setMouseCallback     wgtCanvasSetMouseCallback
  save                 wgtCanvasSave
  load                 wgtCanvasLoad
  drawLine             wgtCanvasDrawLine
  drawRect             wgtCanvasDrawRect
  fillRect             wgtCanvasFillRect
  fillCircle           wgtCanvasFillCircle
  setPixel             wgtCanvasSetPixel
  getPixel             wgtCanvasGetPixel
  drawText             wgtCanvasDrawText
  resize               wgtCanvasResize
.endtable

.h3 Properties

Canvas has no widget-specific properties registered with the interface system. Drawing state (pen color, pen size) is managed by the API functions above.

.h3 Methods (BASIC Interface)

.table
  Method                                        Description
  ------                                        -----------
  Clear color%                                  Fill the entire canvas with a 0x00RRGGBB color.
  DrawLine x0%, y0%, x1%, y1%, color%           Draw a line between two points.
  DrawRect x%, y%, w%, h%, color%               Draw a rectangle outline.
  DrawText x%, y%, text$                        Draw text at the given position.
  FillCircle cx%, cy%, radius%, color%          Fill a circle.
  FillRect x%, y%, w%, h%, color%               Fill a rectangle.
  GetPixel(x%, y%)                              Returns the 0x00RRGGBB color at a pixel.
  Load path$                                    Load an image file onto the canvas.
  Resize w%, h%                                 Resize the canvas (fills new area with white).
  Save path$                                    Save the canvas to an image file.
  SetPenColor color%                            Set the drawing color (0x00RRGGBB).
  SetPenSize size%                              Set the pen size in pixels.
  SetPixel x%, y%, color%                       Set a single pixel.
.endtable

.h3 Events

.table
  Callback                                          Description
  --------                                          -----------
  onClick                                           Fires when the canvas is clicked.
  Mouse callback (via wgtCanvasSetMouseCallback)    Fires on mouse down and drag with canvas-local coordinates.
.endtable

.h3 Default Event

"Click" (VB basName: PictureBox, namePrefix: Picture).
