Text Drawing

• Text Display
  • drawCenterString
  • drawChar
  • drawFloat
  • drawNumber
  • drawString
  • print
  • printf
  • println
• Text Attributes
  • setFont
  • getFont
  • showFont
  • fontHeight
  • fontWidth
  • loadFont
  • unloadFont
  • setTextColor
  • setTextSize
  • getTextSizeX
  • getTextSizeY
  • setTextStyle
  • getTextStyle
  • textLength
  • textWidth
• Text Alignment and Padding
  • setTextDatum
  • getTextDatum
  • setTextPadding
  • getTextPadding
• Automatic Line Wrapping
  • setTextWrap

Text Display

drawCenterString

Function Prototype 1:

void drawCenterString(const char *string, int32_t x, int32_t y, const IFont* font)

Function Prototype 2:

void drawCenterString(const char *string, int32_t x, int32_t y)

Description:

• Draw text at the center position

Parameters:

• string: text string
• x: x coordinate of the drawing start point
• y: y coordinate of the drawing start point

Return:

• null

drawChar

Function Prototype 1:

size_t drawChar(int32_t x, int32_t y, uint16_t uniCode, T color, T bg, float size_x, float size_y)

Function Prototype 2:

size_t drawChar(int32_t x, int32_t y, uint16_t uniCode, T color, T bg, float size)

Function Prototype 3:

size_t drawChar(uint16_t uniCode, int32_t x, int32_t y, uint8_t font)

Function Prototype 4:

size_t drawChar(uint16_t uniCode, int32_t x, int32_t y)

Description:

• Draw a single character

Parameters:

• x: x coordinate of the drawing start point
• y: y coordinate of the drawing start point
• uniCode: character UniCode encoding
• color: character color
• bg: character background color
• size(_N): text scaling ratio
• font: text font format

Return:

• size_t:
  • Total pixel width occupied by the character in the x direction

drawFloat

Function Prototype 1:

size_t drawFloat(float floatNumber, uint8_t dp, int32_t poX, int32_t poY)

Function Prototype 2:

size_t drawFloat(float floatNumber, uint8_t dp, int32_t poX, int32_t poY, uint8_t font)

Description:

• Draw a floating-point number

Parameters:

• floatNumber: floating-point number
• dp: number of decimal places
• poX: x coordinate of the start point
• poY: y coordinate of the start point
• font: text font format

Return:

• size_t: total horizontal pixel width of the drawn string

drawNumber

Function Prototype 1:

size_t drawNumber(long long_num, int32_t poX, int32_t poY)

Function Prototype 2:

size_t drawNumber(long long_num, int32_t poX, int32_t poY, uint8_t font)

Description:

• Draw a long integer number

Parameters:

• long_num: long integer number
• poX: x coordinate
• poY: y coordinate
• font: text font format

Return:

• size_t: total horizontal pixel width of the drawn string

drawString

Function Prototype 1:

size_t drawString( const char *string, int32_t x, int32_t y)

Function Prototype 2:

size_t drawString( const char *string, int32_t x, int32_t y, const IFont* font)

Description:

• Draw a string

Parameters:

• string: string to draw
• x: x coordinate of the drawing start point
• y: y coordinate of the drawing start point
• font: text font format

Return:

• size_t: total horizontal pixel width of the drawn string

print

Function Prototype 1:

size_t print(char c)
size_t print(const char str[])

Function Prototype 2:

size_t print(int  n, int base = 10)
size_t print(long n, int base = 10)
size_t print(unsigned char n, int base = 10)
size_t print(unsigned int  n, int base = 10)
size_t print(unsigned long n, int base = 10)
size_t print(double        n, int digits= 2)

Description:

• Output text to the cursor position, compatible with Arduino header file Print.h.

Parameters:

• c: character
• str: string
• n: integer or floating-point number
• base: base (default is 10)
• digits: number of decimal places to keep (default is 2)

Return:

• size_t: number of characters output

printf

Function Prototype:

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

Description:

• Output text to the cursor position, compatible with Arduino header file LibPrint.h.

Parameters:

• format: format string
• ...: variable arguments

Return:

• size_t: number of characters output

println

Function Prototype:

size_t println(void)
size_t println(char c)
size_t println(const char c[])

Function Prototype:

size_t println(int  n, int base = 10) 
size_t println(long n, int base = 10)
size_t println(unsigned char n, int base = 10)
size_t println(unsigned int  n, int base = 10)
size_t println(unsigned long n, int base = 10)
size_t println(double        n, int digits= 2)

Description:

• Output text to the cursor position, compatible with Arduino header file Print.h.

Parameters:

• c: character/string
• n: integer or floating-point number
• base: base (default is 10)
• digits: number of decimal places to keep (default is 2)

Return:

• size_t: number of characters output

Text Attributes

setFont

Function Prototype:

void setFont(const IFont* font)

Description:

• Set the text font

Parameters:

• font: text font format

Return:

• null

getFont

Function Prototype:

const IFont* getFont (void)

Description:

• Get the currently used font set by setFont

Parameters:

• null

Return:

• const IFont*: pointer to the currently used font object (about Font)

showFont

Function Prototype:

void showFont(uint32_t td = 2000)

Description:

• Display text for the specified time

Parameters:

• td: display time in milliseconds

Return:

• null

fontHeight

Function Prototype:

int32_t fontHeight(const IFont* font)

Description:

• Get the height of the specified font

Parameters:

• font: text font format

Return:

• int32_t: font height

fontWidth

Function Prototype:

int32_t fontWidth(const IFont* font)

Description:

• Get the width of the specified font

Parameters:

• font: text font format

Return:

• int32_t: font width

loadFont

Function Prototype 1:

bool loadFont(const uint8_t* array)

Function Prototype 2:

bool loadFont(T &fs, const char *path)

Function Prototype 3:

bool loadFont(const char *path)

Function Prototype 4:

bool loadFont(DataWrapper* data)

Description:

• Load font data

*For usage, refer to here

Parameters:

• array: pointer to font data
• fs: font data object
  • SPIFFS
  • SD etc
• path: font file path
• data: pointer to font data object

Return:

• bool: whether loading was successful
  • true: success
  • false: failure

unloadFont

Function Prototype:

void unloadFont(void)

Description:

• Restore the font set by setFont to the default font &fonts::Font0.

Parameters:

• null

Return:

• null

setTextColor

Function Prototype 1:

void setTextColor(T color)

Function Prototype 2:

void setTextColor(T1 fgcolor, T2 bgcolor)

Description:

• Set text color

Parameters:

• color: text color
• fgcolor: text foreground color
• bgcolor: text background color

Return:

• null

setTextSize

Function Prototype 1:

void setTextSize(float size)

Function Prototype 2:

void setTextSize(float sx, float sy)

Description:

• Set text size

Parameters:

• size: text scaling ratio
• sx: text x-axis scaling ratio
• sy: text y-axis scaling ratio

Return:

• null

getTextSizeX

Function Prototype:

float getTextSizeX(void)

Description:

• Get the text width set by setTextSize

Parameters:

• null

Return:

• float: text width

getTextSizeY

Function Prototype:

float getTextSizeY(void)

Description:

• Get the text height set by setTextSize

Parameters:

• null

Return:

• float: text height

setTextStyle

Function Prototype:

void setTextStyle(const TextStyle& text_style)

Description:

• Set text style

Parameters:

• text_style: text style object (about TextStyle)

Return:

• null

getTextStyle

Function Prototype:

TextStyle& getTextStyle(void)

Description:

• Get the text style information set by setTextStyle

Parameters:

• null

Return:

• TextStyle&: reference to text style information

textLength

Function Prototype:

int32_t textLength(const char *string, int32_t width)

Description:

• Get the number of characters that can be displayed within the specified range

Parameters:

• string: pointer to the string to display
• width: pixel width of the specified range

Return:

• int32_t: number of bytes that can be displayed

textWidth

Function Prototype:

int32_t textWidth(const char *string, const IFont* font)

Description:

• Returns the width of the string displayed on the screen. If the font is not specified, the default font or the font set by setFont will be used for calculation.

Parameters:

• string: pointer to the string displayed on the screen
• font: text font format

Return:

• int32_t: pixel width of the displayed string

Text Alignment and Padding

setTextDatum

Function Prototype:

void setTextDatum(textdatum_t datum)

Description:

• Set the text datum information

Parameters:

• datum: text alignment

Return:

• null

getTextDatum

Function Prototype:

textdatum_t getTextDatum(void)

Description:

• Get the text datum information set by setTextDatum

Parameters:

• null

Return:

• textdatum_t: text alignment

setTextPadding

Function Prototype:

void setTextPadding(uint32_t padding_x)

Description:

• Set text padding value

Parameters:

• padding_x: text padding value, in pixels

Return:

• null

getTextPadding

Function Prototype:

uint32_t getTextPadding(void)

Description:

• Get the text padding value set by setTextPadding

Parameters:

• null

Return:

• uint32_t: text padding value

Automatic Line Wrapping

setTextWrap

Function Prototype:

void setTextWrap( bool wrapX, bool wrapY = false)

Description:

• Set text automatic line wrapping

Parameters:

• wrapX: flag for automatic line wrapping in the x direction
• wrapY: flag for automatic line wrapping in the y direction (default is no wrapping)

Return:

• null

Example Program:

#include <Arduino.h>
#include <M5GFX.h>

M5GFX display;

void setup() {
    display.begin();

    display.setRotation(3);
    if(display.isEPD())
    {
        display.setColorDepth(8);//The ink screen product supports a maximum bit depth of 8 bits.
        display.setEpdMode(epd_fastest);
    }
    else
    {
        display.setColorDepth(16);
    }
    
    display.clear(TFT_WHITE);
    display.setFont(&fonts::FreeMonoBoldOblique24pt7b);
    display.setTextColor(TFT_BLACK);
    display.setTextWrap(true);
    display.setCursor(0, 0);
    display.setTextSize(1,2);
    uint16_t x = display.getTextSizeX();
    uint16_t y = display.getTextSizeY();
    display.printf("Text SizeX:%d SizeY:%d", x, y);
    display.setTextSize(1,1);
    display.setTextDatum(top_left);//This alignment method refers to the position of the specified coordinate points relative to the text content.
    x = display.fontWidth(&fonts::Font0);
    y = display.fontHeight(&fonts::Font0);
    display.printf(" Font0 W:%d H:%d", x, y);
    display.setTextPadding(10);
    x = display.width() / 2;
    y = display.height() / 2;

    display.drawCenterString("This is CenterString", x, y);
    display.drawChar(0x004D, 0, y/4*7-24);//M
    display.drawChar(0x0035, 30, y/4*7-24);//5
    display.drawChar(0x0053, 30*2, y/4*7-24);//S
    display.drawChar(0x0074, 30*3, y/4*7-24);//t
    display.drawChar(0x0061, 30*4, y/4*7-24);//a
    display.drawChar(0x0063, 30*5, y/4*7-24);//c
    display.drawChar(0x006B, 30*6, y/4*7-24);//k
    display.drawFloat(127.45678, 5, 0, y/4*7);
    display.drawNumber(1234567890, 0, y*2-40);
    display.drawString("This is drawString", x/2, y/4*7);
}

void loop() {
}