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.
The text datum in TFT_eSPI defines the anchor point used when positioning text with drawString(), drawCentreString(), drawRightString(), drawNumber(), and drawFloat(). By default, text is anchored at its top-left corner (datum 0 = TL_DATUM), but changing the datum lets you center text on screen, right-align values, or align to a typographic baseline without manually calculating offsets.
Datum Constants
There are 12 datum values, addressing corners, edges, centre, and baselines:
| Constant | Value | Aliases | Description |
|---|
TL_DATUM | 0 | — | Top-left (default) |
TC_DATUM | 1 | — | Top-centre |
TR_DATUM | 2 | — | Top-right |
ML_DATUM | 3 | CL_DATUM | Middle-left / Centre-left |
MC_DATUM | 4 | CC_DATUM | Middle-centre / Centre-centre |
MR_DATUM | 5 | CR_DATUM | Middle-right / Centre-right |
BL_DATUM | 6 | — | Bottom-left |
BC_DATUM | 7 | — | Bottom-centre |
BR_DATUM | 8 | — | Bottom-right |
L_BASELINE | 9 | — | Left — on the character baseline |
C_BASELINE | 10 | — | Centre — on the character baseline |
R_BASELINE | 11 | — | Right — on the character baseline |
Basic Usage
#include <TFT_eSPI.h>
TFT_eSPI tft = TFT_eSPI();
void setup() {
tft.begin();
tft.setRotation(3); // Landscape
// Center text on screen using MC_DATUM
tft.setTextDatum(MC_DATUM);
tft.drawString("Hello, World!", tft.width() / 2, tft.height() / 2);
}
MC_DATUM, the coordinate passed to drawString() becomes the centre of the text bounding box — ideal for centering on screen without manual calculation.
Changing and Reading the Datum
// Set datum
tft.setTextDatum(TR_DATUM); // Top-right anchor
// Read current datum
uint8_t d = tft.getTextDatum();
Serial.print("Current datum: ");
Serial.println(d); // prints 2
// Draw right-aligned text at the screen's right edge
tft.drawString("Score: 99", tft.width(), 10, 2);
// Change to top-left for normal text
tft.setTextDatum(TL_DATUM);
tft.drawString("Top left corner!", 0, 0, 2);
Datum Positions Illustrated
(0,0) ──────────── TC ──────────── (w,0)
│ │
TL TR
│ │
ML ──────────── MC ──────────── MR
│ │
BL BR
│ │
(0,h) ──────────── BC ──────────── (w,h)
Centering Text on Screen
void setup() {
tft.begin();
tft.setRotation(1);
tft.fillScreen(TFT_BLACK);
tft.setTextColor(TFT_WHITE, TFT_BLACK);
int cx = tft.width() / 2;
int cy = tft.height() / 2;
// Perfectly centred — no offset arithmetic needed
tft.setTextDatum(MC_DATUM);
tft.drawString("Centred Text", cx, cy, 4);
// Right-aligned at screen edge
tft.setTextDatum(TR_DATUM);
tft.drawString("Right edge", tft.width(), 10, 2);
// Bottom-left corner
tft.setTextDatum(BL_DATUM);
tft.drawString("Bottom left", 0, tft.height(), 2);
}
MC_DATUM combined with tft.width()/2, tft.height()/2 is the most common way to perfectly center a label on screen regardless of display size or rotation.
Datum with Numbers and Floats
The datum also applies to drawNumber() and drawFloat():
// Right-align a changing sensor value at x=230
tft.setTextDatum(MR_DATUM);
tft.setTextColor(TFT_GREEN, TFT_BLACK);
tft.setTextPadding(60); // Clear previous value
float temperature = 23.4;
tft.drawFloat(temperature, 1, 230, 60, 2); // "23.4"
API Reference
| Function | Description |
|---|
setTextDatum(uint8_t d) | Set the datum anchor point |
getTextDatum() → uint8_t | Read the current datum value |
drawString(str, x, y, font) | Draw string at x,y using current datum |
drawCentreString(str, x, y, font) | Draw centred (forces TC_DATUM) |
drawRightString(str, x, y, font) | Draw right-aligned (forces TR_DATUM) |
