显示屏 — 文字渲染

M5GFX 源码： lgfx/v1/LGFXBase.hpp
返回： 显示屏概览

所有文字均在光标位置或指定的 (x, y) 绘制，使用当前设置的字体、大小、颜色和对齐基准点。

`setFont()`

void setFont(const IFont* font);

设置活动字体。M5GFX 包含内置位图字体，支持从 SD 卡加载 VLW 字体。

参数	类型	说明
`font`	`const IFont*`	字体对象指针

// 内置字体
M5Cardputer.Display.setFont(&fonts::Font0);      // 极小（Adafruit 5x7）
M5Cardputer.Display.setFont(&fonts::Font2);      // 中等（16px）
M5Cardputer.Display.setFont(&fonts::Font4);      // 大号（26px）
M5Cardputer.Display.setFont(&fonts::Font6);      // 超大（52px）
M5Cardputer.Display.setFont(&fonts::Font7);      // 数码管（7 段）

// 中文字体
M5Cardputer.Display.setFont(&fonts::efontCN_16);
M5Cardputer.Display.drawString("你好世界", 10, 10);

// 从 SD 卡加载自定义 VLW 字体
M5Cardputer.Display.loadFont("/myfont.vlw");

`getFont()`

const IFont* getFont() const;

返回当前活动字体。

`setTextSize()`

void setTextSize(float size);           // 统一缩放
void setTextSize(float sx, float sy);   // X/Y 分别缩放

缩放文字渲染。1 为字体原生大小。

参数	类型	说明
`size`	`float`	统一缩放因子
`sx`	`float`	X 方向缩放因子
`sy`	`float`	Y 方向缩放因子

M5Cardputer.Display.setFont(&fonts::Font2);
M5Cardputer.Display.setTextSize(2);    // 原生大小的 2 倍
M5Cardputer.Display.drawString("大字", 10, 10);

M5Cardputer.Display.setTextSize(1, 2); // 垂直拉伸
M5Cardputer.Display.drawString("瘦高", 10, 50);

`getTextSizeX()` / `getTextSizeY()`

float getTextSizeX() const;
float getTextSizeY() const;

返回当前文字的缩放因子。

`setTextColor()`

void setTextColor(uint16_t color);                     // 仅前景色
void setTextColor(uint16_t fg, uint16_t bg);           // 前景 + 背景

设置文字渲染颜色。

参数	类型	说明
`color`	`uint16_t`	文字颜色
`fg`	`uint16_t`	前景色（文字）
`bg`	`uint16_t`	背景色

M5Cardputer.Display.fillScreen(TFT_BLACK);
M5Cardputer.Display.setTextColor(TFT_WHITE);               // 白色文字
M5Cardputer.Display.drawString("普通", 10, 10);

M5Cardputer.Display.setTextColor(TFT_YELLOW, TFT_BLUE);    // 黄底蓝字
M5Cardputer.Display.drawString("高亮", 10, 30);

`setTextDatum()`

void setTextDatum(uint8_t datum);

设置文字对齐锚点。所有 drawString() 调用均相对此基准点定位。

基准点	简写	锚点
`top_left`	`TL_DATUM`	左上角
`top_center`	`TC_DATUM`	顶部居中
`top_right`	`TR_DATUM`	右上角
`middle_left`	`ML_DATUM`	左中
`middle_center`	`MC_DATUM`	绝对居中
`middle_right`	`MR_DATUM`	右中
`bottom_left`	`BL_DATUM`	左下角
`bottom_center`	`BC_DATUM`	底部居中
`bottom_right`	`BR_DATUM`	右下角

M5Cardputer.Display.fillScreen(TFT_BLACK);
M5Cardputer.Display.setTextColor(TFT_WHITE);

M5Cardputer.Display.setTextDatum(TC_DATUM);
M5Cardputer.Display.drawString("顶部居中", 160, 0);

M5Cardputer.Display.setTextDatum(MC_DATUM);
M5Cardputer.Display.drawString("绝对居中", 160, 120);

M5Cardputer.Display.setTextDatum(BR_DATUM);
M5Cardputer.Display.drawString("右下角", 320, 240);

`setCursor()` / `getCursorX()` / `getCursorY()`

void setCursor(int32_t x, int32_t y);
int32_t getCursorX() const;
int32_t getCursorY() const;

print() / println() / printf() 的输出位置。每次写入后光标自动前进。

M5Cardputer.Display.setCursor(10, 10);
M5Cardputer.Display.print("行1");
M5Cardputer.Display.println(" 续");   // 光标移到下一行
M5Cardputer.Display.printf("光标位置 (%d, %d)\n",
    M5Cardputer.Display.getCursorX(),
    M5Cardputer.Display.getCursorY());

`drawString()`

size_t drawString(const char* str, int32_t x, int32_t y);
size_t drawString(const String& str, int32_t x, int32_t y);

在 (x, y) 绘制文字，按当前 setTextDatum() 对齐。

参数	类型	说明
`str`	`const char*` / `String`	要绘制的文字
`x, y`	`int32_t`	位置（相对基准点）

返回值	说明
`size_t`	绘制的宽度（像素）

M5Cardputer.Display.setTextDatum(TL_DATUM);
M5Cardputer.Display.drawString("左对齐", 10, 10);

M5Cardputer.Display.setTextDatum(TC_DATUM);
M5Cardputer.Display.drawString("居中标题", 160, 20);

`drawCenterString()` / `drawRightString()`

size_t drawCenterString(const char* str, int32_t x, int32_t y);
size_t drawRightString(const char* str, int32_t x, int32_t y);

在 (x, y) 强制居中或右对齐，忽略当前 datum 设置。

// 无论 datum 设置如何，始终在屏幕中心居中
M5Cardputer.Display.drawCenterString("你好", 160, 120);

// 右对齐时间戳
M5Cardputer.Display.drawRightString("14:30:00", 310, 10);

`drawNumber()` / `drawFloat()`

size_t drawNumber(long num, int32_t x, int32_t y);
size_t drawFloat(float num, uint8_t decimalPlaces, int32_t x, int32_t y);

参数	类型	说明
`num`	`long` / `float`	要渲染的数值
`decimalPlaces`	`uint8_t`	浮点数小数位数
`x, y`	`int32_t`	位置

// 分数显示
int score = 1420;
M5Cardputer.Display.drawNumber(score, 10, 10);

// 温度显示
float temp = 23.7f;
M5Cardputer.Display.drawFloat(temp, 1, 10, 40);  // "23.7"

`drawChar()`

size_t drawChar(uint16_t unicode, int32_t x, int32_t y);

绘制单个 Unicode 字符。

M5Cardputer.Display.drawChar('A', 10, 10);
M5Cardputer.Display.drawChar(0x2603, 30, 10);  // 雪人 ☃（需支持字体的中文字库）

`printf()`

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

在当前光标位置格式化输出。使用标准 printf 格式化。

M5Cardputer.Display.setCursor(10, 10);
M5Cardputer.Display.printf("电池: %d%%\n", 85);
M5Cardputer.Display.printf("IP: %d.%d.%d.%d\n", 192, 168, 1, 100);

`print()` / `println()`

size_t print(const char str[]);
size_t print(int n, int base = DEC);
size_t print(float n, int decimals = 2);
size_t println();                         // 仅换行
size_t println(const char str[]);         // 文字 + 换行

标准 Arduino Print 接口。使用当前光标位置。

M5Cardputer.Display.setCursor(0, 0);
M5Cardputer.Display.print("你好 ");
M5Cardputer.Display.print(42);
M5Cardputer.Display.println();            // 换行
M5Cardputer.Display.println("世界");

`fontHeight()` / `fontWidth()` / `textWidth()`

int32_t fontHeight() const;                      // 当前字体高度
int32_t textWidth(const char* str);              // 字符串像素宽度

int32_t h = M5Cardputer.Display.fontHeight();
int32_t w = M5Cardputer.Display.textWidth("你好");
M5Cardputer.Display.printf("字体: %d x %d\n", w, h);

`setTextWrap()`

void setTextWrap(bool wrapX, bool wrapY = false);

启用自动换行，当文字超过显示区域宽度时自动折行。

// 在 200px 宽的列中自动换行
M5Cardputer.Display.setClipRect(10, 10, 200, 220);
M5Cardputer.Display.setTextWrap(true);
M5Cardputer.Display.setCursor(10, 10);
M5Cardputer.Display.print("这段很长的文字将会自动折行到下一行继续显示。");
M5Cardputer.Display.clearClipRect();

`setTextScroll()`

void setTextScroll(bool scroll);

当输出到达底部时自动向上滚动屏幕，实现终端风格显示。

M5Cardputer.Display.setTextScroll(true);
M5Cardputer.Display.setCursor(0, 0);

void loop() {
    M5Cardputer.update();
    M5Cardputer.Keyboard.updateKeysState();
    for (char c : M5Cardputer.Keyboard.keysState().word) {
        M5Cardputer.Display.print(c);  // 触底时自动滚动
    }
}

显示屏 — 文字渲染

setFont()

getFont()

setTextSize()

getTextSizeX() / getTextSizeY()

setTextColor()

setTextDatum()

setCursor() / getCursorX() / getCursorY()

drawString()

drawCenterString() / drawRightString()

drawNumber() / drawFloat()

drawChar()

printf()

print() / println()

fontHeight() / fontWidth() / textWidth()

setTextWrap()

setTextScroll()