RedcrabX – DrawBox Guide

Pixel-canvas drawing on the worksheet  |  Version 1.0
Available in RedcrabX from version 10.2.0

← Back to Quick Start Guide

Table of Contents

• 1. Overview
• 2. Inserting a DrawBox
• 3. Box Name and Target Selection
• 4. Draw Functions
  • 4.1 drawtarget
  • 4.2 drawrect
  • 4.3 drawcircle
  • 4.4 drawline
  • 4.5 drawarrow
  • 4.6 drawdot
  • 4.7 drawellipse
  • 4.8 drawarc
  • 4.9 drawtext
  • 4.10 drawclear
  • 4.11 drawcross
  • 4.12 drawdim
  • 4.13 drawpoly
  • 4.14 drawgrid
• 5. Typical Workflow
• 6. Refresh and Canvas Clearing
• 7. Error Messages
• 8. Tips

1. Overview

The DrawBox provides a blank pixel canvas in the worksheet. MathBox cells can draw geometric shapes on it using side-effect draw commands. Draw commands do not produce a numeric result — they act purely as drawing instructions.

2. Inserting a DrawBox

Use the Insert menu on the main ribbon to add a DrawBox to the worksheet. The new box appears on the canvas and can be moved and resized like any other workspace box.

3. Box Name and Target Selection

Every DrawBox has a name shown in the status toolbar at the bottom of the box. The default name is D1. You can change it by clicking the name field and typing a new name.

Draw commands reference a DrawBox by its name. You can either set a persistent current target with drawtarget and then omit the name from each draw call, or pass the target name explicitly as the first argument of any draw function.

4. Draw Functions

All draw functions are side-effect commands. They do not display a numeric result in the MathBox; they act purely as drawing instructions. The available functions are: drawtarget, drawrect, drawcircle, drawline, drawarrow, drawdot, drawellipse, drawarc, drawtext, drawclear, drawcross, drawdim, drawpoly, and drawgrid.

4.1   drawtarget

Sets the active DrawBox target. Subsequent drawrect and drawcircle calls without an explicit target name will draw on this box.

Syntax

drawtarget(D1)

Examples

// Select D1 as the current drawing target
drawtarget(D1)

// All subsequent draw calls without an explicit name go to D1
drawrect(10, 20, 80, 120)
drawcircle(120, 120, 40)

4.2   drawrect

Draws a rectangle (unfilled, black border) on the active or specified DrawBox.

Syntax

// Implicit target (drawtarget must be called first)
drawrect(x, y, h, w)

// Explicit target as first argument
drawrect(D1, x, y, h, w)

Examples

// Draw a 120 × 80 px rectangle at (10, 20) on the current target
drawtarget(D1)
drawrect(10, 20, 80, 120)

// Draw directly on D2 without changing the global target
drawrect(D2, 50, 50, 60, 100)

// Negative dimensions are accepted: the rectangle is flipped automatically
drawrect(200, 150, -40, -60)   // same as drawrect(140, 110, 40, 60)

4.3   drawcircle

Draws a circle (unfilled, black border) by center point and radius on the active or specified DrawBox.

Syntax

// Implicit target (drawtarget must be called first)
drawcircle(x, y, r)

// Explicit target as first argument
drawcircle(D1, x, y, r)

Examples

// Draw a circle centered at (120, 120) with radius 40 px on the current target
drawtarget(D1)
drawcircle(120, 120, 40)

// Draw directly on D2 without changing the global target
drawcircle(D2, 80, 80, 30)

// Use a variable for the radius
r := 50
drawcircle(160, 100, r)

4.4   drawline

Draws a line (straight, 1 px black stroke) between two points on the active or specified DrawBox.

Syntax

// Implicit target (drawtarget must be called first)
drawline(x1, y1, x2, y2)

// Explicit target as first argument
drawline(D1, x1, y1, x2, y2)

Examples

// Draw a line from (10, 10) to (200, 100) on the current target
drawtarget(D1)
drawline(10, 10, 200, 100)

// Draw multiple lines to form a triangle scaffold
drawline(10, 10, 100, 10)
drawline(100, 10, 55, 90)
drawline(55, 90, 10, 10)

// Draw directly on D2 without changing the global target
drawline(D2, 0, 0, 150, 150)

// Use variables for dynamic line endpoints
x := 80
y := 60
drawline(x, y, x + 60, y + 80)

4.5   drawarrow

Draws a dimensioning arrow: a straight line from (x1, y1) to (x2, y2) with a small filled arrowhead at the end point. Typically used to annotate measurements on technical drawings.

Syntax

// Implicit target
drawarrow(x1, y1, x2, y2)

// Explicit target
drawarrow(D1, x1, y1, x2, y2)

Examples

// Horizontal dimension arrow on D1
drawtarget(D1)
drawarrow(40, 135, 160, 135)

// Vertical dimension arrow pointing upward
drawarrow(180, 160, 180, 40)

// Use on a second box without changing the global target
drawarrow(D2, 10, 50, 190, 50)

4.6   drawdot

Draws a filled circle (solid black disk) at the given center point. Useful for marking joints, origins, and notable points in technical sketches.

Syntax

// Implicit target
drawdot(x, y, r)

// Explicit target
drawdot(D1, x, y, r)

Examples

// Mark the corner of a rectangle
drawtarget(D1)
drawrect(40, 40, 80, 120)
drawdot(40, 40, 4)   // top-left corner
drawdot(160, 40, 4)  // top-right corner

// Mark a midpoint computed from variables
x := 100
y := 60
drawdot(x, y, 3)

4.7   drawellipse

Draws an unfilled ellipse (black stroke) by center point and the two half-axes. A circle is the special case where rx = ry; use drawcircle for that.

Syntax

// Implicit target
drawellipse(x, y, rx, ry)

// Explicit target
drawellipse(D1, x, y, rx, ry)

Examples

// Flat ellipse 60 × 30 px centered at (120, 100)
drawtarget(D1)
drawellipse(120, 100, 60, 30)

// Tall ellipse for an isometric projection
drawellipse(160, 80, 20, 50)

// Ellipse on D2 without changing the global target
drawellipse(D2, 80, 60, 40, 25)

4.8   drawarc

Draws a circular arc by center, radius, and two angles. The arc is drawn clockwise from a1 to a2. Angles follow the toolbar setting (degrees / radians).

Syntax

// Implicit target
drawarc(x, y, r, a1, a2)

// Explicit target
drawarc(D1, x, y, r, a1, a2)

Examples

// Quarter-circle arc (0° to 90°, i.e. right → down) at corner (40, 40)
drawtarget(D1)
drawarc(40, 40, 20, 0, 90)

// Semicircle (top half of a circle, 180° to 360°)
drawarc(120, 100, 50, 180, 360)

// Full circle via drawarc (same as drawcircle)
drawarc(100, 100, 40, 0, 360)

// Arc on D2 without changing the global target
drawarc(D2, 80, 80, 30, 45, 315)

4.9   drawtext

Places a text label on the canvas at pixel position (x, y). The text is rendered in 11 pt black using the default UI font. Typically used for dimension labels and annotations.

Syntax

// Implicit target
drawtext(x, y, "label")

// Explicit target
drawtext(D1, x, y, "label")

Examples

// Dimension label below a rectangle
drawtarget(D1)
drawrect(40, 40, 80, 120)
drawarrow(40, 135, 160, 135)
drawtext(90, 148, "120 mm")

// Axis labels
drawtext(5, 5, "Y")
drawtext(285, 115, "X")

// Annotate a point
drawdot(100, 80, 4)
drawtext(106, 74, "P")

4.10   drawclear

Removes all shapes from the DrawBox canvas. Useful when you want to repaint the canvas from a button or script without a full worksheet refresh.

drawclear()           // clear current target
drawclear(D1)         // clear box D1 explicitly

Examples

drawtarget(D1)
drawgrid(20)
drawcircle(100, 80, 40)
// later, wipe everything and redraw:
drawclear()
drawrect(10, 10, 60, 80)

4.11   drawcross

Draws a crosshair marker (two perpendicular lines) centered at (x, y). Useful for marking origins, center points, or joints.

drawcross(x, y, size)
drawcross(D1, x, y, size)

Examples

drawtarget(D1)
drawcross(100, 80, 20)    // 20 px cross at (100,80)
drawcross(160, 40, 10)    // small marker at corner

4.12   drawdim

Draws a complete dimension line: a double-headed arrow parallel to the measured edge, offset perpendicularly, with extension lines from both endpoints. Replaces the manual drawarrow + drawarrow + drawtext pattern for annotation.

drawdim(x1, y1, x2, y2, offset)
drawdim(D1, x1, y1, x2, y2, offset)

Examples

drawtarget(D1)
drawrect(40, 40, 80, 120)
// Horizontal dimension below
drawdim(40, 120, 160, 120, 20)
drawtext(88, 148, "120 mm")
// Vertical dimension to the right
drawdim(160, 40, 160, 120, 20)
drawtext(184, 76, "80 mm")

4.13   drawpoly

Draws a closed polygon from a flat list of coordinate pairs (x1,y1, x2,y2, x3,y3, …). At least three pairs are required. The last point is automatically connected back to the first.

drawpoly(x1,y1, x2,y2, x3,y3, ...)
drawpoly(D1, x1,y1, x2,y2, x3,y3, ...)

Examples

drawtarget(D1)
// Triangle
drawpoly(50, 10, 100, 90, 10, 90)
// Hexagon (regular, radius 50 around center 120,100)
r := 50 ; cx := 120 ; cy := 100
drawpoly(cx+r,cy, cx+r/2,cy-r*sin(60), cx-r/2,cy-r*sin(60),
         cx-r,cy, cx-r/2,cy+r*sin(60), cx+r/2,cy+r*sin(60))

4.14   drawgrid

Draws a light gray background grid across the entire canvas. Grid lines are placed at regular intervals and rendered behind all other shapes. Call before other draw functions.

drawgrid(spacing)         // square grid
drawgrid(sx, sy)          // rectangular grid
drawgrid(D1, spacing)     // explicit target

Examples

drawtarget(D1)
drawgrid(20)              // 20 px square grid
drawcircle(100, 80, 40)

// Grid with different x/y spacing
drawgrid(40, 30)

The following examples show how the draw functions work together, from a simple shape to a fully annotated technical sketch.

Basic shapes on one target

// MathBox — select target once, then draw
drawtarget(D1)
drawrect(10, 10, 60, 100)
drawcircle(60, 40, 30)
drawline(10, 10, 100, 40)

Multi-target workflow

// MathBox 1 — draw on D1
drawtarget(D1)
drawrect(5, 5, 80, 120)

// MathBox 2 — draw on a second box without changing the global target
drawcircle(D2, 100, 100, 50)
drawrect(D2, 20, 20, 40, 60)

Computed geometry

// Scale a shape from a variable
s := 80
drawrect(10, 10, s, s)
drawcircle(10 + s/2, 10 + s/2, s/2)

Annotated technical sketch (dimensioning)

// Draw a rectangle and annotate its width with a dimension arrow and label
drawtarget(D1)

// Shape
drawrect(40, 40, 80, 120)

// Corner dots
drawdot(40, 40, 3)
drawdot(160, 40, 3)

// Angle arc at top-left corner
drawarc(40, 40, 18, 0, 90)

// Horizontal dimension line (offset below the rectangle)
drawarrow(40, 140, 160, 140)   // arrow right
drawarrow(160, 140, 40, 140)   // arrow left (double arrow)
drawtext(88, 148, "120 mm")

// Vertical dimension line (offset to the right)
drawarrow(175, 40, 175, 120)   // arrow down
drawarrow(175, 120, 175, 40)   // arrow up
drawtext(180, 76, "80 mm")

// Ellipse decoration
drawellipse(100, 80, 15, 8)

6. Refresh and Canvas Clearing

Every time the worksheet is recalculated (e.g. after editing a MathBox or pressing Refresh), all DrawBox canvases are automatically cleared before the draw commands are re-executed. This ensures the canvas always reflects the current state of the expressions without accumulating stale shapes from previous runs.

7. Error Messages

8. Tips

• Use variables for coordinates. Store computed values in MathBox variables and pass them to draw functions for dynamic, formula-driven graphics.
• Multiple DrawBoxes. You can have several DrawBoxes on the same worksheet. Give each a unique name (e.g. D1, D2) and address them with the explicit-target form or by switching targets with drawtarget.
• Resize the canvas. Drag the DrawBox border to make it larger. All pixel coordinates stay the same — only the visible area changes.
• Filled vs. unfilled shapes. drawdot draws a solid filled disk. All other shapes (drawrect, drawcircle, drawellipse, drawarc) are unfilled with a 1 px black border. Colored or custom-fill shapes are not yet supported.
• Arc angles. drawarc uses the toolbar angle unit (degrees or radians). Angles are measured clockwise from east (right), matching screen convention (Y-axis points down). A span of 360° draws a complete circle.
• Text positioning. The (x, y) position in drawtext is the top-left corner of the text block. Add an offset to center a label over an arrow or shape.
• Coordinate system. Origin (0, 0) is the top-left corner. Y increases downward, which is the standard screen convention.
• Dimension lines. drawdim draws the full double-headed dimension line in one call. Use a positive offset to place it below a horizontal edge or to the right of a vertical one. Combine with drawtext to add the measurement label.
• Grid as background. Call drawgrid first so it is rendered behind all other shapes. The grid extends to the full canvas size and uses a light Gainsboro color.
• Polygons and star shapes. drawpoly accepts any number of vertex pairs and automatically closes the polygon. Use loop expressions or precomputed arrays for regular polygons and stars.

RedcrabX DrawBox Guide  —  further topics: Quick Start Guide  |  ProgramBox Guide  |  MathBox Guide  |  Geometry Guide  |  Chart Guide  |  ImageBox Guide