Display — Text Rendering

M5GFX source: lgfx/v1/LGFXBase.hpp
Back to: Display overview

All text is drawn at the cursor position or a specified (x, y), using the currently set font, size, color, and alignment datum.

`setFont()`

void setFont(const IFont* font);

Sets the active font. M5GFX includes built-in bitmap fonts and supports VLW fonts loaded from SD.

Parameter	Type	Description
`font`	`const IFont*`	Pointer to font object

// Built-in fonts
M5Cardputer.Display.setFont(&fonts::Font0);      // Tiny (Adafruit 5x7)
M5Cardputer.Display.setFont(&fonts::Font2);      // Medium (16px)
M5Cardputer.Display.setFont(&fonts::Font4);      // Large (26px)
M5Cardputer.Display.setFont(&fonts::Font6);      // Extra Large (52px)
M5Cardputer.Display.setFont(&fonts::Font7);      // Giant (7-seg)

// eFont (embedded Japanese/Chinese)
M5Cardputer.Display.setFont(&fonts::efontCN_16);
M5Cardputer.Display.drawString("你好世界", 10, 10);

// Load custom VLW font from SD
M5Cardputer.Display.loadFont("/myfont.vlw");

`getFont()`

const IFont* getFont() const;

Returns the currently active font.

`setTextSize()`

void setTextSize(float size);           // Uniform scale
void setTextSize(float sx, float sy);   // Separate X/Y scale

Scales text rendering. A size of 1 is the font's native size.

Parameter	Type	Description
`size`	`float`	Uniform scale factor
`sx`	`float`	X scale factor
`sy`	`float`	Y scale factor

M5Cardputer.Display.setFont(&fonts::Font2);
M5Cardputer.Display.setTextSize(2);    // 2x native size
M5Cardputer.Display.drawString("Big text", 10, 10);

M5Cardputer.Display.setTextSize(1, 2); // Squashed vertically
M5Cardputer.Display.drawString("Tall", 10, 50);

`getTextSizeX()` / `getTextSizeY()`

float getTextSizeX() const;
float getTextSizeY() const;

Returns the current text size factors.

`setTextColor()`

void setTextColor(uint16_t color);                     // Foreground only
void setTextColor(uint16_t fg, uint16_t bg);           // Foreground + background

Sets the text rendering color.

Parameter	Type	Description
`color`	`uint16_t`	Text color
`fg`	`uint16_t`	Foreground (text) color
`bg`	`uint16_t`	Background color

M5Cardputer.Display.fillScreen(TFT_BLACK);
M5Cardputer.Display.setTextColor(TFT_WHITE);               // White text
M5Cardputer.Display.drawString("Normal", 10, 10);

M5Cardputer.Display.setTextColor(TFT_YELLOW, TFT_BLUE);    // Yellow on blue
M5Cardputer.Display.drawString("Highlighted", 10, 30);

`setTextDatum()`

void setTextDatum(uint8_t datum);

Sets the text alignment anchor point. All drawString() calls position text relative to this datum.

Datum	Shorthand	Anchor
`top_left`	`TL_DATUM`	Top-left corner
`top_center`	`TC_DATUM`	Top center
`top_right`	`TR_DATUM`	Top right
`middle_left`	`ML_DATUM`	Middle left
`middle_center`	`MC_DATUM`	Absolute center
`middle_right`	`MR_DATUM`	Middle right
`bottom_left`	`BL_DATUM`	Bottom left
`bottom_center`	`BC_DATUM`	Bottom center
`bottom_right`	`BR_DATUM`	Bottom right

M5Cardputer.Display.fillScreen(TFT_BLACK);
M5Cardputer.Display.setTextColor(TFT_WHITE);

M5Cardputer.Display.setTextDatum(TC_DATUM);
M5Cardputer.Display.drawString("Top Center", 160, 0);

M5Cardputer.Display.setTextDatum(MC_DATUM);
M5Cardputer.Display.drawString("Dead Center", 160, 120);

M5Cardputer.Display.setTextDatum(BR_DATUM);
M5Cardputer.Display.drawString("Bottom Right", 320, 240);

`setCursor()`

void setCursor(int32_t x, int32_t y);
int32_t getCursorX() const;
int32_t getCursorY() const;

Position for print() / println() / printf(). The cursor advances automatically with each write.

M5Cardputer.Display.setCursor(10, 10);
M5Cardputer.Display.print("Line 1");
M5Cardputer.Display.println(" continued");   // Cursor moves to next line
M5Cardputer.Display.printf("Cursor at (%d, %d)\n",
    M5Cardputer.Display.getCursorX(),
    M5Cardputer.Display.getCursorY());

`drawString()`

size_t drawString(const char* str, int32_t x, int32_t y);
size_t drawString(const String& str, int32_t x, int32_t y);

Draws text at (x, y) aligned by the current setTextDatum().

Parameter	Type	Description
`str`	`const char*` / `String`	Text to draw
`x, y`	`int32_t`	Position (relative to datum)

Return	Description
`size_t`	Width drawn in pixels

M5Cardputer.Display.setTextDatum(TL_DATUM);
M5Cardputer.Display.drawString("Left aligned", 10, 10);

M5Cardputer.Display.setTextDatum(TC_DATUM);
M5Cardputer.Display.drawString("Centered title", 160, 20);

`drawCenterString()` / `drawRightString()`

size_t drawCenterString(const char* str, int32_t x, int32_t y);
size_t drawRightString(const char* str, int32_t x, int32_t y);

Force center or right alignment at (x, y), ignoring the current datum setting.

// Center at screen center regardless of datum
M5Cardputer.Display.drawCenterString("Hello", 160, 120);

// Right-aligned timestamp
M5Cardputer.Display.drawRightString("14:30:00", 310, 10);

`drawNumber()` / `drawFloat()`

size_t drawNumber(long num, int32_t x, int32_t y);
size_t drawFloat(float num, uint8_t decimalPlaces, int32_t x, int32_t y);

Parameter	Type	Description
`num`	`long` / `float`	Value to render
`decimalPlaces`	`uint8_t`	Decimal digits for float
`x, y`	`int32_t`	Position

// Score display
int score = 1420;
M5Cardputer.Display.drawNumber(score, 10, 10);

// Temperature
float temp = 23.7f;
M5Cardputer.Display.drawFloat(temp, 1, 10, 40);  // "23.7"

`drawChar()`

size_t drawChar(uint16_t unicode, int32_t x, int32_t y);

Draws a single Unicode character.

M5Cardputer.Display.drawChar('A', 10, 10);
M5Cardputer.Display.drawChar(0x2603, 30, 10);  // Snowman ☃

`printf()`

size_t printf(const char* format, ...);

Formatted output at current cursor position. Uses standard printf formatting.

M5Cardputer.Display.setCursor(10, 10);
M5Cardputer.Display.printf("Battery: %d%%\n", 85);
M5Cardputer.Display.printf("IP: %d.%d.%d.%d\n", 192, 168, 1, 100);

`print()` / `println()`

size_t print(const char str[]);
size_t print(int n, int base = DEC);
size_t print(float n, int decimals = 2);
size_t println();                         // Just a newline
size_t println(const char str[]);         // Text + newline

Standard Arduino Print interface. Uses current cursor position.

M5Cardputer.Display.setCursor(0, 0);
M5Cardputer.Display.print("Hello ");
M5Cardputer.Display.print(42);
M5Cardputer.Display.println();            // Newline
M5Cardputer.Display.println("World");

`fontHeight()` / `fontWidth()` / `textWidth()`

int32_t fontHeight() const;                      // Height of current font
int32_t textWidth(const char* str);              // Pixel width of string

int32_t h = M5Cardputer.Display.fontHeight();
int32_t w = M5Cardputer.Display.textWidth("Hello");
M5Cardputer.Display.printf("Font: %d x %d\n", w, h);

`setTextWrap()`

void setTextWrap(bool wrapX, bool wrapY = false);

Enables automatic line wrapping when text exceeds the display width.

// Auto-wrap text in a 200px wide column
M5Cardputer.Display.setClipRect(10, 10, 200, 220);
M5Cardputer.Display.setTextWrap(true);
M5Cardputer.Display.setCursor(10, 10);
M5Cardputer.Display.print("This is a very long sentence that will wrap automatically.");
M5Cardputer.Display.clearClipRect();

`setTextScroll()`

void setTextScroll(bool scroll);

Auto-scrolls the screen up when output reaches the bottom, like a terminal.

M5Cardputer.Display.setTextScroll(true);
M5Cardputer.Display.setCursor(0, 0);

void loop() {
    M5Cardputer.update();
    M5Cardputer.Keyboard.updateKeysState();
    for (char c : M5Cardputer.Keyboard.keysState().word) {
        M5Cardputer.Display.print(c);  // Auto-scrolls when reaching bottom
    }
}

Display — Text Rendering

setFont()

getFont()

setTextSize()

getTextSizeX() / getTextSizeY()

setTextColor()

setTextDatum()

setCursor()

drawString()

drawCenterString() / drawRightString()

drawNumber() / drawFloat()

drawChar()

printf()

print() / println()

fontHeight() / fontWidth() / textWidth()

setTextWrap()

setTextScroll()