.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

.h2 Canvas

A freeform drawing surface with a fixed-size pixel buffer. Provides drawing primitives (lines, rectangles, circles, text, individual pixels) and supports save/load to BMP files. Mouse interaction is available via a callback.

Header: widgets/widgetCanvas.h

.h3 Creation

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

.h3 Macros

.index wgtCanvasSetPenColor
.index wgtCanvasSetPenSize
.index wgtCanvasSetMouseCallback

.table
  Macro                                    Description
  -----                                    -----------
  wgtCanvas(parent, w, h)                  Create a canvas with the given pixel dimensions.
  wgtCanvasClear(w, color)                 Fill the entire canvas with a solid color.
  wgtCanvasSetPenColor(w, color)           Set the drawing pen color.
  wgtCanvasSetPenSize(w, size)             Set the drawing pen size in pixels.
  wgtCanvasDrawLine(w, x0, y0, x1, y1)    Draw a line from (x0,y0) to (x1,y1).
  wgtCanvasDrawRect(w, x, y, width, height)    Draw a rectangle outline.
  wgtCanvasFillRect(w, x, y, width, height)    Draw a filled rectangle.
  wgtCanvasFillCircle(w, cx, cy, radius)   Draw a filled circle.
  wgtCanvasSetPixel(w, x, y, color)        Set a single pixel to the given color.
  wgtCanvasGetPixel(w, x, y)              Get the color of a single pixel.
  wgtCanvasDrawText(w, x, y, text)         Draw text at the given position using the current pen color.
  wgtCanvasSetMouseCallback(w, cb)         Set a mouse interaction callback. Signature: void (*cb)(WidgetT *w, int32_t cx, int32_t cy, bool drag). Receives canvas-relative coordinates and whether the mouse is being dragged.
  wgtCanvasSave(w, path)                   Save the canvas contents to a BMP file.
  wgtCanvasLoad(w, path)                   Load a BMP file into the canvas.
.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 Methods (BASIC Interface)

.table
  Method       Description
  ------       -----------
  Clear        Clear the canvas to a given color.
.endtable