Draw Text

draw_text

Draw UTF-8 text using a bounded box and one or more styled spans. This replaces draw_string; bitmap identifiers such as font16 are not supported.

Text box arguments

Field	Type	Required/default	Meaning
x, y	integer	Required	Box origin
width, height	integer	Required, positive	Box dimensions in pixels
spans	array	Required, nonempty	Styled text spans
background	string	transparent	Transparent or an opaque palette color
horizontal_align	string	left	left, center, right
vertical_align	string	top	top, middle, bottom
wrap	string	word	Accepted field; see limitations below
overflow	string	ellipsis	clip or ellipsis; see limitations below
line_spacing	integer	0	Additional pixels between lines; use nonnegative values

Span fields

Field	Type	Required/default	Meaning
text	string	Required	UTF-8 text
family	string	Send explicitly	Bundled family is helvetica
size	integer	Required	Font height, 6–96 pixels
weight	string	regular	regular or bold
color	string	black	Opaque palette color
letter_spacing	integer	0	Added glyph advance in pixels
underline	boolean	false	Underline decoration
strikeout	boolean	false	Strikeout decoration

The parser default for family is sans, but the checked-in font registry contains only helvetica. Always supply "family": "helvetica" unless you have embedded another family. An unsupported family, weight, or size skips the text command.

Example

{
  "cmd": "draw_text",
  "args": {
    "x": 20,
    "y": 20,
    "width": 700,
    "height": 90,
    "background": "white",
    "horizontal_align": "left",
    "vertical_align": "top",
    "line_spacing": 4,
    "spans": [
      {
        "text": "Status: ",
        "family": "helvetica",
        "size": 24,
        "weight": "bold",
        "color": "black"
      },
      {
        "text": "Ready – 21 °C",
        "family": "helvetica",
        "size": 24,
        "color": "red"
      }
    ]
  }
}

Current rendering behavior

• The renderer uses embedded TrueType fonts through stb_truetype. See Fonts.
• Spans flow into the same layout and may have different sizes, weights, colors, and decorations.
• Newlines start lines, carriage returns are ignored, and tabs expand to four spaces. Missing glyphs fall back to U+FFFD; coverage depends on the font.
• Wrapping currently happens at glyph boundaries when the next glyph exceeds the box width. The word field does not implement word-aware wrapping.
• The renderer reads overflow but does not use it to add an ellipsis. Do not rely on ellipsis truncation.
• Horizontal alignment is per line. Vertical alignment uses the computed visible lines.
• Glyph pixels are checked against the box, but the canvas point path shifts painted glyphs by one pixel up and left. Decorations do not use the same box-clipping path. Background fill does not have that glyph shift.

Keep boxes within display bounds and preview important layouts. These are implementation limitations, not guarantees of additional text layout features.

Implementation references

• Arduino/src/core/command/draw_text.cpp
• Arduino/src/e-paper/paper_command.h
• Emulator/src/network/request.cpp