跳转至

显示屏 — 工具

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

屏幕控制、二维码生成、进度条、状态保存/恢复和绘图会话。

屏幕控制

fillScreen() — 填充屏幕

void fillScreen();                        // 填充背景色
void fillScreen(uint16_t color);          // 填充指定颜色

用纯色填满整个屏幕。

M5Cardputer.Display.fillScreen(TFT_BLACK);

// 填充默认背景色
M5Cardputer.Display.setBaseColor(TFT_NAVY);
M5Cardputer.Display.fillScreen();

setBrightness() / getBrightness() — 背光

void setBrightness(uint8_t brightness);   // 0–255（0=关闭, 255=最大）
uint8_t getBrightness() const;

控制 LCD 背光亮度。

void setup() {
    M5Cardputer.begin();
    M5Cardputer.Display.setBrightness(128);  // 50%
}

void onDimTimer() {
    // 空闲时降至 20%
    M5Cardputer.Display.setBrightness(51);
}

setRotation() / getRotation() — 旋转

void setRotation(uint8_t rotation);   // 0–3
uint8_t getRotation() const;

旋转屏幕坐标系统。

值 方向 分辨率
0 竖屏 240 × 320
1 横屏 320 × 240
2 竖屏（倒置） 240 × 320
3 横屏（倒置） 320 × 240 
M5Cardputer.Display.setRotation(1);  // 默认横屏
M5Cardputer.Display.printf("宽=%d 高=%d\n",
    M5Cardputer.Display.width(),
    M5Cardputer.Display.height());   // 320 x 240

width() / height() — 尺寸

int32_t width() const;
int32_t height() const;

返回当前显示尺寸（旋转后）。

int32_t cx = M5Cardputer.Display.width() / 2;
int32_t cy = M5Cardputer.Display.height() / 2;
M5Cardputer.Display.drawCircle(cx, cy, 30, TFT_RED);

sleep() / wakeup() — 休眠

void sleep();    // 关闭显示屏
void wakeup();   // 唤醒显示屏

LCD 电源管理。

// 空闲后熄屏
if (millis() - lastActivity > 30000) {
    M5Cardputer.Display.sleep();
}

// 按键唤醒
if (M5Cardputer.BtnA.wasPressed()) {
    M5Cardputer.Display.wakeup();
    lastActivity = millis();
}

invertDisplay() — 反色

void invertDisplay(bool invert);
bool getInvert() const;

反转屏幕上所有像素（适用于某些面板配置）。

M5Cardputer.Display.invertDisplay(true);
delay(500);
M5Cardputer.Display.invertDisplay(false);

二维码

qrcode()

void qrcode(const char* string, int32_t x = -1, int32_t y = -1,
            int32_t width = -1, uint8_t version = 1);

直接在显示屏上绘制二维码。

参数 类型 默认 说明
string const char* — 要编码的数据
x, y int32_t -1 位置（-1 = 居中）
width int32_t -1 尺寸（-1 = 最大适配）
version uint8_t 1 QR 版本（1–40，决定数据容量） 
// 自动居中
M5Cardputer.Display.qrcode("https://m5stack.com", -1, -1, -1);

// 自定义位置和尺寸
M5Cardputer.Display.qrcode("hello123", 10, 10, 100);

进度条

progressBar()

void progressBar(int x, int y, int w, int h, uint8_t val);

M5GFX 特有的便捷控件。绘制简单进度条。

参数 类型 说明
x, y int 左上角
w, h int 宽高
val uint8_t 进度值 0–100 
void loadingScreen() {
    M5Cardputer.Display.fillScreen(TFT_BLACK);
    M5Cardputer.Display.setTextColor(TFT_WHITE);
    M5Cardputer.Display.drawString("加载中...", 10, 10);

    for (int i = 0; i <= 100; i += 10) {
        M5Cardputer.Display.progressBar(40, 80, 240, 20, i);
        delay(200);
    }
}

状态保存 / 恢复

pushState() / popState()

void pushState();   // 保存字体、文字样式、光标、颜色
void popState();    // 恢复保存的状态

LIFO 栈式图形状态管理。在函数中临时更改字体/大小/颜色时使用。

void drawHeader(const char* title) {
    M5Cardputer.Display.pushState();
    M5Cardputer.Display.setTextSize(2);
    M5Cardputer.Display.setTextColor(TFT_WHITE, TFT_NAVY);
    M5Cardputer.Display.drawCenterString(title, 160, 15);
    M5Cardputer.Display.popState();   // 恢复原始设置
}

void drawBodyLine(const char* text) {
    M5Cardputer.Display.println(text);  // 使用原始设置
}

绘图会话

startWrite() / endWrite()

void startWrite();   // 开始绘图会话
void endWrite();     // 结束并刷新

将多个绘图操作包裹在单次 SPI 事务中以提升性能。

M5Cardputer.Display.startWrite();
for (int i = 0; i < 100; i++) {
    int x = random(320);
    int y = random(240);
    M5Cardputer.Display.drawPixel(x, y, TFT_WHITE);
}
M5Cardputer.Display.endWrite();