Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Marcussacapuces91/doc-TFT_eSPI/llms.txt

Use this file to discover all available pages before exploring further.

In TFT_eSPI, a datum is the anchor point that drawString() and related text functions use to position a string on screen. When you call tft.drawString("Hello", x, y), the coordinates x and y don’t refer to the top-left corner of the text by default — they refer to whatever datum is currently active. TL_DATUM (top-left) is the default, so in the default state x, y is the top-left corner of the first character. Switching to MC_DATUM (middle-centre) makes x, y the geometric centre of the rendered string, which is ideal for centring labels inside buttons or panel headings.

​
Datum constants

ConstantAliasValueAnchor position
TL_DATUM—0Top-left corner of the text bounding box (default)
TC_DATUM—1Top-centre
TR_DATUM—2Top-right corner
ML_DATUMCL_DATUM3Middle-left (vertically centred, left-aligned)
MC_DATUMCC_DATUM4Middle-centre (horizontally and vertically centred)
MR_DATUMCR_DATUM5Middle-right
BL_DATUM—6Bottom-left corner
BC_DATUM—7Bottom-centre
BR_DATUM—8Bottom-right corner
L_BASELINE—9Left edge of the character baseline
C_BASELINE—10Centre of the character baseline
R_BASELINE—11Right edge of the character baseline
ML_DATUM and CL_DATUM are identical integer values (3), as are the MC/CC and MR/CR pairs. They exist purely as readability aliases — choose whichever naming convention reads most naturally in your code.

​
Visual layout of datum positions

The grid below shows where (x, y) maps to on a text bounding box for each of the nine corner/edge datums: 
                  x (left)   x (centre)   x (right)
                     │             │            │
  y (top)    ────  TL_DATUM    TC_DATUM    TR_DATUM
                     │             │            │
  y (middle) ────  ML_DATUM    MC_DATUM    MR_DATUM
                     │             │            │
  y (bottom) ────  BL_DATUM    BC_DATUM    BR_DATUM
                     │             │            │
  y (baseline) ── L_BASELINE  C_BASELINE  R_BASELINE
The baseline is the invisible horizontal line that most characters sit on — the same line the capital letter A rests on. Descenders (the tails on g, p, y) extend below the baseline, so the bottom of the bounding box is lower than the baseline for fonts with descenders.

​
Using datum constants

​
setTextDatum() — apply a datum globally

void TFT_eSPI::setTextDatum(uint8_t datum);
Sets the active datum for all subsequent drawString(), drawNumber(), and drawFloat() calls until changed again. 
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);

  // Centre a heading at the top of the screen
  tft.setTextDatum(TC_DATUM);
  tft.drawString("Settings", tft.width() / 2, 8, 4);

  // Right-align a value against the right edge
  tft.setTextDatum(TR_DATUM);
  tft.drawString("v2.5.43", tft.width() - 4, 8, 2);

  // Centre a status message in the middle of the screen
  tft.setTextDatum(MC_DATUM);
  tft.drawString("No signal", tft.width() / 2, tft.height() / 2, 2);
}

void loop() {
  // Retrieve the current datum if needed
  uint8_t d = tft.getTextDatum(); // returns 0..11
}

​
Datum in TFT_eSPI_Button::setLabelDatum()

Button labels use MC_DATUM by default. Pass a different datum to setLabelDatum() if you need the label anchored elsewhere: 
// Shift label 4 px left and anchor it to the left-centre of the button
btn.setLabelDatum(-4, 0, ML_DATUM);
btn.drawButton();

​
Drawing at multiple positions with different datums

void setup() {
  tft.init();
  tft.fillScreen(TFT_NAVY);
  tft.setTextColor(TFT_YELLOW);

  int cx = tft.width()  / 2;
  int cy = tft.height() / 2;

  // Top-left datum — x,y is the top-left of the text
  tft.setTextDatum(TL_DATUM);
  tft.drawString("TL", 0, 0, 2);

  // Middle-centre datum — x,y is the exact centre of the text
  tft.setTextDatum(MC_DATUM);
  tft.drawString("MC", cx, cy, 2);

  // Bottom-right datum — x,y is the bottom-right corner
  tft.setTextDatum(BR_DATUM);
  tft.drawString("BR", tft.width(), tft.height(), 2);

  // Baseline-left datum — x,y is on the baseline, at the left of the text
  tft.setTextDatum(L_BASELINE);
  tft.drawString("Baseline", 10, cy + 40, 2);
}
Always call setTextDatum(TL_DATUM) after positioned drawing if the rest of your sketch expects the default top-left anchor. Leaving an unexpected datum active is a common source of misaligned text bugs.

Build docs developers (and LLMs) love

Get started for freeTalk to us