Overwrite text using tft.print()?

[Xylopyrographer]

Sending text to a display using the tft.print() and println() methods. At some point I reset the cursor using setCursor() and then I want to erase the text there for the next 'x' lines by tft.print( " ") a number of times, reset the cursor position and then use print() and println() for the new text.

Soon discovered this doesn't work, with methods of blanking out existing text using sprites, filled rectangles, overwriting first in the background colour, etc. recommended.

All good but why isn't there a "special character" that when print()'ed fills to the background colour at the cursor position?

Yes, this would only work reliably for monospaced fonts, but would make things easier with text of random length not set to appear in a fixed region of the screen.

Or in other terms, why doesn't print()'ing a character (even when using a method that sets the text foreground and background colours) erase whatever was there before (it only overlays the new charter on top of the existing one)? Is this behaviour unique to print() and println()?

Realizing this question comes often, though mostly in the context of using drawString().

FWIW, using a 240 x 320 display - ILI9341 driver in landscape orientation, with FreeFont FM9, monospaced 9pt.

Relative new user of the library.

[Bodmer]

Set a background colour to overwrite. See example here on how to do this:
https://github.com/Bodmer/TFT_eSPI/blob/master/examples/320%20x%20240/TFT_Print_Test/TFT_Print_Test.ino

[Xylopyrographer]

Thanks for the reply.

Tried many variations of that, none with success. With the following sketch, when using setTextColor( fgColor, bgColor ) (where fgColor and bgColor are valid TFT_color type macros) setting the foreground colour works, but setting the background colour does not work.

//
// Sketch to figure out how to clear a line or more of text
// of text of the display using the TFT_eSPI library.
// Target:  Sunton ESP32-2432S024C dev board
//          (though not really specific to that board, just need a display)
// Display: 240 by 320, native in portrait mode
// Driver:  ILI9341V

#include "TFT_eSPI.h"       // graphics and font library
#include "Free_Fonts.h"     // need FM9 from here

int16_t cursorBaseX = 0;
int16_t cursorBaseY = 0;

TFT_eSPI tft = TFT_eSPI();      // Invoke library

void setup() {

    Serial.begin( 115200 );
    delay( 250 );
    Serial.println();

    tft.init();
    tft.setRotation( 3 );         // 3 = display in landscape, USB connector on the left
    tft.fillScreen( TFT_BLACK );

    tft.setFreeFont( FM9 );

    tft.setCursor( 0, 0 );
    tft.setTextColor( TFT_GREEN, TFT_BLACK );    // BUG? setting the background colour has no effect

    tft.println();
    tft.println( "1. This is text, line 1" );
    tft.println( "2. This is text, line 2" );
    tft.println( "3. More text on line 3" );
    tft.println( "4. Line the 4th be with you." );
    tft.println( "5. Leaving setup()" );

    tft.setTextColor( TFT_RED, TFT_BLACK );     // BUG? setting the background colour has no effect

    cursorBaseX = tft.getCursorX();
    cursorBaseY = tft.getCursorY();

    Serial.printf( "End of setup(): cursorBaseX = %i, cursorBaseY = %i\n\n", cursorBaseX, cursorBaseY  );

}

void loop() {

    tft.println( "6. a line to be erased 1" );
    tft.println( "7. a line to be erased 2" );
    delay( 1000 );                                  // pause before trying to overwrite text

    Serial.printf( "In loop(): lines 6 & 7 printed: getCursorX() = %i, getCursorY() = %i\n", tft.getCursorX(), tft.getCursorY() );

    tft.setTextColor( TFT_BLACK, TFT_BLACK );      // BUG? setting the background colour has no effect

    // put the cursor back where it was after leaving setup()
    tft.setCursor( cursorBaseX, cursorBaseY );

    // intent now is to erase lines 6. and 7.
    //  note: monospaced font FreeFont FM9 = 29 char/line in 320 pixels
    //  2 lines = 58 characters
    for ( uint8_t i = 0; i < 29 * 2; i++ ) {
        // BUG? whatever char is used below, it overlays, it does not
        // overwrite even when the BG colour is set using setTextColor()
        tft.print( "@" );   // not using a space (" ") so the bug can be seen on the screen
    }

    Serial.printf( "In loop(): 'blanking' characters just printed.\n" );
    Serial.printf( "In loop(): cursorBaseX = %i, cursorBaseY = %i\n", cursorBaseX, cursorBaseY  );

    tft.setCursor( cursorBaseX, cursorBaseY );  // reset the cursor position

    Serial.printf( "In loop(): Cursor reset to Base: getCursorX = %i, getCursorY = %i\n\n", tft.getCursorX(), tft.getCursorY() );

    tft.setTextColor( TFT_RED, TFT_BLACK );     // BUG? setting the background colour has no effect

    delay( 3000 );      // so we can see what happened
    // and let's do it again...
}

The User_Setup.h file that goes with this is:

//                            USER DEFINED SETTINGS
//
// THIS FILE SETUP IS FOR THE BUILT-IN DISPLAY OF THE SUNTON ESP32-2432S024C Dev Board
// Created: 2023-11-05
// Note: The displays native setting is portrait mode,
//       meaning 240 px is the width, 320 px is the height

#define USER_SETUP_INFO "User_Setup"

// Define to disable all #warnings in library (can be put in User_Setup_Select.h)
// #define DISABLE_ALL_LIBRARY_WARNINGS

// ######## Section 1. Call up the right driver file and any options for it

#define ILI9341_DRIVER       // Generic driver for common displays

// ######## Section 2. Define the pins that are used to interface with the display here

#define TFT_BL 27               // LED back-light control pin
#define TFT_BACKLIGHT_ON HIGH   // Level to turn ON back-light (HIGH or LOW)

// Settings for the Sunton ESP32-2432S024 Dev Board
//  - the display is on the ESP32 HSPI bus
// #define TFT_MISO 12         // commented out in favour of the USE_HSPI_PORT define below
// #define TFT_MOSI 13         // commented out in favour of the USE_HSPI_PORT define below
// #define TFT_SCLK 14         // commented out in favour of the USE_HSPI_PORT define below
#define TFT_CS   15         // Chip select control pin
#define TFT_DC    2         // Data/Command control pin
#define TFT_RST  -1         // Set to -1 if the display RESET pin is either not connected or is connected to the ESP32 EN pin

// ######## Section 3. Define the fonts that are to be used here

#define LOAD_GLCD   // Font 1. Original Adafruit 8 pixel font needs ~1820 bytes in FLASH
#define LOAD_FONT2  // Font 2. Small 16 pixel high font, needs ~3534 bytes in FLASH, 96 characters
#define LOAD_GFXFF  // FreeFonts. Include access to the 48 Adafruit_GFX free fonts FF1 to FF48 and custom fonts

// ######## Section 4. Other options

#define SPI_FREQUENCY  40000000
#define SPI_READ_FREQUENCY  20000000    // may be able to use the SPI_FREQUENCY above.

#define USE_HSPI_PORT

#define SUPPORT_TRANSACTIONS

//  - EOF -

Using:
TFT_eSPI version 2.5.31
Arduino IDE v2.2.1
Arduino-esp32 core v2.0.14

Also tried using a "built-in" font (not a font from the FreeFonts.h file), same problem observed.

Be glad to try out any suggested variation of this that would get it to work.

Many thanks.

[Bodmer]

The background is not drawn for Freefonts, this is compatible with the original Adafruit approach, see here and note the "gotcha".

Also see Free_Font_Demo example and notes here.

The library will blank the background when the drawString() function is used with free fonts, but this can lead to flicker. The other option to avoid flicker is to use sprites.

[Xylopyrographer]

Thank-you very much for the reply. Makes sense. I should have caught that.

I revised the sketch to use a built-in font and in the process I think I may have found a bug with tft.print().

When using built-in fonts, tft.print() won't print the background colour unless the background colour has a value different since the last time tft.print() was called.

Eg: in the revised sketch below, (see lines 85 & 105) the line below works when using built-in fonts (causes the text to be overwritten)
tft.setTextColor( TFT_BLACK, 0x0001 );
but the line below fails as the BG colour is unchanged since set at the bottom of loop()
tft.setTextColor( TFT_BLACK, TFT_BLACK );
likewise, the line below also fails
tft.setTextColor( TFT_BLACK );

Or did I miss something else??

//
// Sketch to figure out how to clear a line or more of text
// of text of the display using the TFT_eSPI library.
// Target:  Sunton ESP32-2432S024C dev board
//          (though not really specific to that board, just need a display)
// Display: 240 by 320, native in portrait mode
// Driver:  ILI9341V

#define USE_FREEFONTS 0     // define as 1 to use FreeFont FM9, 0 to use built-in font 1
// Note: setting the font background colour has no effect when using FreeFonts

#include "TFT_eSPI.h"       // graphics and font library

#if USE_FREEFONTS
    #include "Free_Fonts.h"     // need FM9 from here
    char blankingChar = 'W';
    uint8_t spaceMult = 2;
#else
    char blankingChar = ' ';
    uint8_t spaceMult = 3;
#endif

int16_t cursorBaseX = 0;
int16_t cursorBaseY = 0;

TFT_eSPI tft = TFT_eSPI();      // invoke library

void setup() {

    Serial.begin( 115200 );
    delay( 250 );
    Serial.println();

    tft.init();
    tft.setRotation( 3 );         // 3 = display in landscape, USB connector on the left
    tft.fillScreen( TFT_BLACK );

    #if USE_FREEFONTS
        tft.setFreeFont( FM9 );
        tft.setCursor( 0, 0 );
        tft.println();           // only needed if FreeFonts are used as their baseline is bottom of the char
    #else
        tft.setTextFont( 1 );    // there is no font 3
    #endif

    tft.setTextColor( TFT_GREEN, TFT_BLACK );

    tft.println( "1. This is text, line 1" );
    tft.println( "2. This is text, line 2" );
    tft.println( "3. More text on line 3" );
    tft.println( "4. Line the 4th be with you." );
    tft.println( "5. Leaving setup()" );

    tft.setTextColor( TFT_RED, TFT_BLACK );

    cursorBaseX = tft.getCursorX();
    cursorBaseY = tft.getCursorY();

    Serial.printf( "End of setup(): cursorBaseX = %i, cursorBaseY = %i\n\n", cursorBaseX, cursorBaseY  );

}

void loop() {

    Serial.printf( "In loop(): About to print lines 6. & 7.: getCursorX() = %i, getCursorY() = %i\n", tft.getCursorX(), tft.getCursorY() );

    tft.println( "6. a line to be erased 1" );
    tft.println( "7. a line to be erased 2" );

    Serial.printf( "In loop(): lines 6 & 7 printed: getCursorX() = %i, getCursorY() = %i\n", tft.getCursorX(), tft.getCursorY() );

    tft.setCursor( cursorBaseX, cursorBaseY );  // put the cursor back where it was after leaving setup()

    Serial.printf( "In loop(): lines 6 & 7 printed, cursor reset: getCursorX() = %i, getCursorY() = %i\n", tft.getCursorX(), tft.getCursorY() );
    
    // BUG? when using built-in fonts, tft.print() won't print the background colour unless
    //      the BG colour has a different value since the last time tft.print() was called.
    //      eg: the next line works when using built-in fonts (causes the text to be overwritten)
    //          tft.setTextColor( TFT_BLACK, 0x0001 );
    //      this next line fails as the BG colour is unchanged since set at the bottom of loop()
    //          tft.setTextColor( TFT_BLACK, TFT_BLACK );
    //      likewise, this next statement fails
    //          tft.setTextColor( TFT_BLACK );

    tft.setTextColor( TFT_BLACK, 0x0001 );      // works
    // tft.setTextColor( TFT_BLACK, TFT_BLACK );   // fails
    // tft.setTextColor( TFT_BLACK );              // fails

    delay( 1000 );          // pause before trying to overwrite text

    // intent now is to erase lines 6. and 7.
    //  note: monospaced font FreeFont FM9 = 29 char/line in 320 pixels
    //        2 lines = 58 characters
    //  if using built-in fonts, print a gob of spaces
    for ( uint8_t i = 0; i < 29 * spaceMult; i++ ) {
        tft.print( blankingChar );
    }

    Serial.printf( "In loop(): 'blanking' characters just printed. getCursorX = %i, getCursorY = %i\n", tft.getCursorX(), tft.getCursorY() );

    tft.setCursor( cursorBaseX, cursorBaseY );  // reset the cursor position

    Serial.printf( "In loop(): Cursor reset to Base: getCursorX = %i, getCursorY = %i\n\n", tft.getCursorX(), tft.getCursorY() );

    tft.setTextColor( TFT_RED, TFT_BLACK );     // ** read the note above before the 'tft.setTextColor( TFT_BLACK, 0x0001 );' statement

    delay( 1000 );      // so we can see what happened
    // and let's do it again...
}

[Bodmer]

That behaviour is intentional and is compatible with the Adafruit_GFX library.

Use setTextPadding to overwrite old text.

[Xylopyrographer]

OK. Thanks again for the reply and most certainly for this library! Have a great one.