📚 课程目录第3章 TouchGFX Designer快速上手

3. TouchGFX Designer快速上手

TouchGFX 是 ST 官方为 STM32 提供的图形框架，它把“界面设计”和“嵌入式渲染”拆成了两个可协作的部分：一边是运行在 PC 上的 TouchGFX Designer，负责画布、控件、资源与交互逻辑的可视化编辑；另一边是运行在 STM32 上的 TouchGFX Engine，负责把界面渲染到 LCD 并处理触摸事件。理解这套分工，是快速上手的第一步——Designer 不是仿真器，它最终要把设计“翻译”成 C++ 代码，再交给 STM32 工程去编译运行。

安装 TouchGFX 软件生态

TouchGFX 的安装不是单独装一个软件，而是把三件东西配齐：STM32CubeMX（负责芯片时钟、外设、LTDC/SPI 显示接口与 FreeRTOS 配置）、TouchGFX Designer（负责 UI 设计）、以及对应的 STM32Cube 固件包（提供 HAL 与 BSP 驱动）。推荐顺序是：先装 STM32CubeMX，再装 X-CUBE-TOUCHGFX 扩展包，最后通过 CubeMX 的“Additional Software”把 TouchGFX 勾选进工程。这样 Designer 与 CubeMX 之间才能通过 .ioc 文件和 TouchGFX 目录双向同步。

安装完成后，在 CubeMX 中新建工程并选择目标芯片（例如 STM32F429ZIT6，带 LTDC 与 SDRAM，适合 RGB 屏）。关键配置包括：RCC 时钟树、SDRAM 控制器（作为显存）、LTDC 图层参数（分辨率、像素格式 RGB565）、DMA2D（加速填充与混合）、以及 FreeRTOS（TouchGFX 默认以任务方式运行）。这些配置会直接影响 Designer 中画布的分辨率与颜色格式，必须与屏幕实物一致。

若使用官方开发板（如 STM32F429I-DISC1），可直接在 CubeMX 的 Board Selector 中选择对应板卡，LTDC、SDRAM、触摸引脚会被自动配置，能显著减少上手阻力。

创建第一个 STM32 工程

在 CubeMX 中完成外设配置后，进入 Project Manager，设置工程名与工具链（STM32CubeIDE 或 MDK-ARM），并在 Additional Software 中勾选 X-CUBE-TOUCHGFX。生成代码后，工程目录中会出现 TouchGFX/ 文件夹，其中 TouchGFX/Designer/ 存放 .touchgfx 设计文件，TouchGFX/generated/ 存放自动生成的 C++ 代码，TouchGFX/gui/ 存放用户可编辑的界面逻辑。这个目录结构是后续所有工作的基础。

双击 .touchgfx 文件即可启动 Designer。首次打开时，Designer 会读取 CubeMX 生成的配置，确定画布尺寸（如 240×320）与颜色深度。此时画布是空白的，左侧是控件库（Widgets），右侧是属性面板（Properties），中间是画布（Canvas），底部是资源管理器（Assets）与交互（Interactions）。

理解 Designer 的四大区域

画布（Canvas）是所见即所得的设计区，坐标原点在左上角，X 向右、Y 向下，单位是像素。画布尺寸由 CubeMX 中的 LTDC 分辨率决定，不能随意更改。所有控件都按绝对坐标摆放，Designer 会自动生成对应的 setPosition 调用。

控件库（Widgets）提供 Box、TextArea、Button、Image、Slider、ProgressBar、FlexButton、Container 等常用控件。拖拽到画布后，在右侧属性面板中设置名称、坐标、尺寸、颜色、文本等。命名建议使用有意义的英文（如 btnStart、txtStatus），因为该名称会直接成为 C++ 中的成员变量名。

资源管理器（Assets）管理图片、字体、文本和动画。图片会被转换为 TouchGFX 专用的位图格式（如 RGB565、ARGB8888），字体被转换为 4bpp 或 1bpp 位图字体。资源越多，Flash 与 RAM 占用越大，因此要控制图片尺寸与字体字符集。

交互（Interactions）把控件事件与动作绑定，例如“点击 btnStart → 切换屏幕”或“点击 btnStart → 调用虚拟函数”。Designer 会为每个交互生成回调代码框架，用户只需在 TouchGFX/gui/ 下的 Screen1View.cpp 中填充业务逻辑。

代码生成机制

点击 Designer 右上角的 Generate Code 后，会发生三件事：第一，Designer 把画布上的控件、资源、交互序列化为中间描述；第二，代码生成器根据模板生成 C++ 类，包括 Screen1ViewBase（控件成员与布局）、Screen1Presenter（MVP 中的 Presenter）以及资源索引；第三，生成的文件被写入 TouchGFX/generated/，而用户可编辑的 Screen1View.cpp 与 Screen1View.hpp 位于 TouchGFX/gui/，不会被覆盖。

这种“生成基类 + 用户继承”的机制，使得重新生成代码时用户逻辑不会丢失。典型的工作流是：在 Designer 中改界面 → Generate Code → 在 Screen1View.cpp 中实现 btnStartClicked() 等回调 → 在 STM32CubeIDE 中编译下载。若在 CubeMX 中修改了 LTDC 分辨率或颜色格式，需要重新生成 CubeMX 代码，再回到 Designer 中确认画布参数同步。

常见问题：Generate Code 报错“Cannot find TouchGFX folder”，通常是因为 .touchgfx 文件与 CubeMX 工程不在同一目录，或 CubeMX 中未勾选 X-CUBE-TOUCHGFX。解决方法是回到 CubeMX 重新勾选并生成，确保 TouchGFX/ 目录存在。

第一个可运行示例

以 240×320 屏幕为例，在 Screen1 上放置一个 TextArea（显示“Hello STM32”）、一个 Button（文本“Start”）、一个 ProgressBar（范围 0~100）。为 Button 添加交互：onButtonClicked → Call new virtual function，命名为 startClicked。Generate Code 后，在 Screen1View.cpp 中实现：

void Screen1View::startClicked()
{
    // 示例：每次点击进度条增加 10，超过 100 归零
    static uint8_t progress = 0;
    progress = (progress + 10) % 110;
    progressBar.setValue(progress);
    progressBar.invalidate();
}

编译下载后，屏幕上应显示文本、按钮与进度条；点击按钮，进度条按 10 的步进增长，到 100 后归零。若进度条不刷新，检查是否调用了 invalidate()；若按钮无响应，检查触摸驱动是否在 CubeMX 中正确配置，以及交互是否绑定到了正确的控件名称。