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.

When displaying a value that changes over time — a sensor reading, counter, or clock — the new text may be shorter than what was previously drawn. Without clearing the old text first, stale pixels remain visible. setTextPadding() solves this by forcing drawString() (and related functions) to blank a fixed-width area before drawing the new text, replacing the old value cleanly in a single pass with no flicker.
Text padding only takes effect when a background color is set via setTextColor(fg, bg). When called with a single color argument (setTextColor(fg)), no background fill is applied and padding is ignored.

​
How setTextPadding Works

setTextPadding(uint16_t x_width) sets a minimum pixel width for the text drawing area. When drawString() renders text:
  1. It calculates the actual pixel width of the string.
  2. If that width is less than x_width, the remaining area is filled with the background color.
  3. The text is drawn over the filled region.
This means a short string like "9" written after "100" will still erase the full width of "100".

​
Basic Example

#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

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

  // Set text padding to 10 pixels
  tft.setTextPadding(10);

  // Draw a string with padding
  tft.drawString("Hello", 10, 20);

  // Get the current text padding
  uint16_t padding = tft.getTextPadding();
  Serial.print("Text padding: ");
  Serial.println(padding);

  // Change the text padding to 20 pixels
  tft.setTextPadding(20);

  // Draw another string with the new padding
  tft.drawString("World", 10, 40);
}

void loop() {
  // Nothing to do here
}

​
Practical Use: Updating a Counter Without Flicker

Without padding, counting down from "100" to "9" leaves "00" residue on screen. With padding sized to the widest expected string, each update is clean: 
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();
int counter = 100;

void setup() {
  tft.begin();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  tft.setTextColor(TFT_GREEN, TFT_BLACK);

  // Measure the width of the widest possible value ("100")
  // and use that as the padding
  tft.setTextFont(4);  // Select font before measuring
  uint16_t maxWidth = tft.textWidth("100", 4);
  tft.setTextPadding(maxWidth);
}

void loop() {
  tft.setTextDatum(MC_DATUM);
  tft.drawNumber(counter, tft.width() / 2, tft.height() / 2, 4);

  counter--;
  if (counter < 0) counter = 100;

  delay(200);
}
Use tft.textWidth("widest_string", font) to compute the exact padding needed for any expected value. This avoids over-padding (wasted pixels) or under-padding (leftover residue).

​
Live Sensor Display

#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.begin();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  tft.setTextColor(TFT_CYAN, TFT_BLACK);
  tft.setTextDatum(TL_DATUM);

  tft.drawString("Temp:", 10, 10, 2);

  // Pad for widest expected float: "-99.9" = 5 chars at font 4
  tft.setTextPadding(tft.textWidth("-99.9", 4));
}

void loop() {
  float temp = analogRead(A0) * 0.1;  // Example conversion — adapt to your sensor
  tft.drawFloat(temp, 1, 70, 10, 4);
  delay(500);
}

​
API Reference

FunctionSignatureDescription
setTextPaddingvoid setTextPadding(uint16_t x_width)Set minimum draw width in pixels
getTextPaddinguint16_t getTextPadding()Read current padding value
The padding value is reset to 0 by calling setTextPadding(0). It does not reset automatically between calls.

Build docs developers (and LLMs) love

Get started for freeTalk to us