3. TouchGFX Designer入门：安装与配置、创建第一个空白项目、熟悉界面布局与基本操作

TouchGFX Designer（以下简称TGD）是STMicroelectronics为STM32系列MCU提供的可视化GUI开发环境，它允许开发者通过拖拽控件、配置交互逻辑、管理图片与字体资源的方式，快速生成基于C++的嵌入式图形界面工程。与传统的纯代码编写GUI不同，TGD将界面设计与业务逻辑分离，设计阶段产出的UI文件（.touchgfx）最终会通过代码生成器转换为可编译的C++源码，与TouchGFX核心库及STM32硬件驱动层无缝衔接。本章将围绕TGD的安装配置、首个空白项目的创建流程以及界面布局的核心操作展开，帮助读者建立从工具链搭建到项目结构认知的完整闭环。

上图展示了从安装配置到界面布局的完整工程链路。TGD并非孤立工具，它依赖STM32CubeMX生成底层硬件初始化代码，同时需要交叉编译器将生成的C++代码编译为可在目标MCU上运行的固件。理解这一链路有助于后续排查环境问题，例如“模拟器正常但板子黑屏”时，往往需要回溯到CubeMX中的显示接口配置是否正确。

3.1 安装与配置TouchGFX Designer

3.1.1 核心原理：工具链的依赖关系

TouchGFX Designer本身是一个基于Java的桌面应用程序，它并不直接编译代码，而是负责UI设计、资源管理和代码生成。其运行依赖以下组件：

• Java运行时环境（JRE）：TGD 4.21及以上版本要求Java 11或更高版本，安装时需确保JAVA_HOME环境变量正确指向JDK目录。
• STM32CubeMX：用于配置MCU引脚、时钟、外设（如LTDC、DMA2D、FMC），并生成初始化C代码。TGD通过CubeMX的.ioc文件识别硬件平台。
• 交叉编译器：根据开发环境选择GCC（STM32CubeIDE自带）、IAR EWARM或Keil MDK。TGD生成的代码需要这些编译器进行编译链接。
• 调试器驱动：ST-Link或J-Link驱动用于固件烧录和在线调试，与TGD本身无直接交互，但影响后续验证环节。

版本匹配是常见陷阱。例如，TGD 4.21生成的代码可能依赖TouchGFX框架4.21版本的API，如果CubeMX固件包中集成的TouchGFX组件版本过低，编译时会报出大量未定义符号错误。建议在CubeMX中通过“Help → Manage Embedded Software Packages”安装与TGD主版本一致的TouchGFX组件。

3.1.2 操作流程：从零完成安装

1. 获取安装包：访问ST官网下载TouchGFX Designer安装程序（约500MB），同时下载对应STM32系列的CubeMX固件包（如STM32F746G-DISCO的固件包）。
2. 安装Java：若系统未安装JDK 11+，先安装并配置环境变量。验证方法：在命令行执行 java -version，确认输出中包含“11.0.x”或更高版本。
3. 安装TGD：双击安装程序，选择安装路径（建议默认路径），勾选“Add to PATH”选项。安装完成后首次启动会提示选择工作区目录，建议使用英文路径避免编码问题。
4. 配置CubeMX路径：在TGD中通过“File → Settings → STM32CubeMX Path”指定CubeMX可执行文件路径。此配置用于TGD调用CubeMX生成底层驱动。
5. 验证安装：打开TGD，点击“File → New Project”，若能正常弹出项目配置对话框，说明基础环境就绪。

3.1.3 案例拆解：解决“模拟器无法启动”问题

背景与约束：某学员在Win10 64位系统上安装TGD 4.21后，点击“Run Simulator”时模拟器窗口闪退，无任何错误提示。其开发板为STM32F746G-DISCO，CubeMX版本为6.8.0。

分析过程：首先检查TGD日志（位于%APPDATA%\TouchGFX\4.21.0\log），发现关键错误：java.lang.UnsatisfiedLinkError: Can't load library: swt-win32-4626.dll。该错误表明SWT图形库未能正确加载，通常由系统缺少Visual C++运行库或Java路径包含空格导致。

解决步骤：

1. 安装“Microsoft Visual C++ 2015-2022 Redistributable (x64)”，重启TGD。
2. 若问题依旧，检查JAVA_HOME路径是否包含空格（如C:\Program Files\Java\jdk-11），在TGD启动脚本中改用短路径名（C:\PROGRA~1\Java\jdk-11）。
3. 最终通过将JDK安装到D:\Java\jdk-11（无空格路径）彻底解决。

结果与复盘：模拟器正常启动，项目可预览。此案例说明TGD对运行环境较为敏感，遇到闪退时优先检查日志文件，而非盲目重装。

3.1.4 常见误区与总结

3.2 创建第一个空白项目

3.2.1 核心原理：项目文件结构

一个TouchGFX项目由TGD生成后，会包含以下关键目录：

• assets/：存放图片、字体、文本等资源文件，TGD会将这些资源转换为C数组嵌入固件。
• generated/：TGD自动生成的C++代码，包括界面布局、控件初始化、资源描述等，此目录内容不应手动修改。
• gui/：用户自定义逻辑代码，如屏幕跳转、业务处理函数，开发者在此添加业务逻辑。
• target/：与硬件相关的驱动代码，由CubeMX生成，包含LTDC、DMA2D等初始化。

理解这一结构对后续开发至关重要。例如，当需要添加自定义字体时，应将字体文件放入assets/fonts，并在TGD中重新生成代码，而不是直接修改C++文件。

3.2.2 操作流程：创建空白项目

1. 启动TGD，点击“Create New Project”。
2. 选择目标平台：在“Target”下拉框中选择“STM32F746G-DISCO”或自定义型号。若选择自定义，需手动指定分辨率、色彩深度（RGB565或RGB888）和帧缓冲格式。
3. 配置显示参数：设置屏幕分辨率（如480x272）、色彩深度（建议RGB565以节省内存）、旋转方向（横屏/竖屏）。
4. 选择生成器版本：保持默认的“TouchGFX Generator”版本，与安装的TGD版本一致。
5. 指定项目名称与路径：例如D:\Projects\MyFirstGUI，注意路径不能包含中文。
6. 点击“Create”，TGD会生成基础工程骨架，并自动打开主编辑界面。

3.2.3 案例拆解：为STM32F746G-DISCO创建项目

背景：使用官方评估板STM32F746G-DISCO，板载4英寸480x272电容触摸屏，外部SDRAM容量为8MB。

操作步骤：

1. 在TGD中选择“STM32F746G-DISCO”模板，TGD自动识别板载屏幕参数。
2. 色彩深度选择RGB565，帧缓冲放置于外部SDRAM（地址0xC0000000）。
3. 项目创建后，打开CubeMX（TGD自动调用），确认LTDC引脚已正确映射（如PF10-PF15等），时钟树中LTDC时钟频率设置为约25MHz。
4. 在TGD中点击“Run Simulator”，验证空白屏幕显示为纯色背景。

结果：模拟器显示一个空白画布，背景色默认为黑色。此时项目已具备编译条件，但尚未添加任何控件。

风险与代价：若SDRAM初始化时序不正确，模拟器正常但板子显示花屏。此时需检查CubeMX中FMC配置的时序参数（如读/写恢复周期），并对比SDRAM芯片数据手册。

3.2.4 常见误区与总结

3.3 熟悉界面布局与基本操作

3.3.1 核心原理：TGD工作区组成

TGD主界面分为五个核心区域：

• 画布（Canvas）：中央区域，用于所见即所得地摆放控件，支持缩放、平移、网格对齐。
• 控件面板（Widgets）：左侧列表，包含按钮、文本框、滑块、图片、容器等基础控件，拖拽即可添加到画布。
• 属性编辑器（Properties）：右侧面板，显示选中控件的坐标、尺寸、颜色、字体、文本等属性，支持直接输入数值或拖拽调整。
• 交互面板（Interactions）：底部区域，用于配置控件的事件响应，如点击、滑动、定时器触发等。
• 资源管理器（Assets）：右上角，管理图片、字体、文本资源，支持导入PNG/JPG图片和TTF字体。

理解这些区域的协作关系是高效使用TGD的基础。例如，添加一个按钮需要：从控件面板拖拽按钮到画布，在属性编辑器中修改文本和颜色，在交互面板中添加点击事件，最后在模拟器中验证效果。

3.3.2 操作流程：添加并配置一个按钮

1. 在左侧控件面板中找到“Button”控件，拖拽至画布中央。
2. 选中按钮，右侧属性编辑器显示其属性。修改“Text”为“Start”，设置“Text Color”为白色，背景色为蓝色（#2196F3）。
3. 调整按钮位置：在“Position”栏输入X=200，Y=120，或直接在画布上拖拽。
4. 在底部交互面板点击“+ Add Interaction”，选择Trigger为“Click”，Action为“Toggle Screen”或“Call Custom Function”。
5. 点击“Run Simulator”，点击按钮验证交互效果。

3.3.3 案例拆解：制作一个带背景图的登录界面

背景：需要制作一个480x272分辨率的登录界面，包含背景图片、用户名输入框、密码输入框和登录按钮。

操作步骤：

1. 导入背景图片：在资源管理器中点击“Import Images”，选择一张480x272的PNG图片（建议小于200KB以节省Flash）。
2. 从控件面板拖拽“Image”控件到画布，在属性编辑器中将其关联到刚导入的图片，并设置坐标(0,0)。
3. 添加两个“Text Area”控件作为标签，分别设置文本为“User:”和“Pass:”，字体选择系统默认字体，颜色为白色。
4. 添加两个“Text Area”控件作为输入框，设置“Keyboard”属性为“Numeric”或“Alpha”，并设置背景色为半透明黑色（Alpha=128）。
5. 添加“Button”控件，设置文本为“Login”，背景色为绿色（#4CAF50）。
6. 在交互面板中为登录按钮添加“Click”事件，Action选择“Call Custom Function”，并生成函数骨架。
7. 在生成的LoginView.cpp中实现登录逻辑，例如检查用户名和密码是否匹配。

结果：模拟器显示完整登录界面，点击按钮后触发自定义函数，可在控制台输出调试信息。

复盘：此案例展示了TGD的核心工作流：资源导入→控件布局→属性配置→交互绑定→代码生成。实际开发中，建议先完成静态布局，再逐步添加交互逻辑，避免频繁切换设计器和代码编辑器。

3.3.4 常见误区与总结

通过本章的学习，读者应能独立完成TGD的安装配置、创建空白项目，并掌握基本的界面布局操作。下一阶段将深入探讨控件库的详细用法与样式定制，但在此之前，务必通过实际操作熟悉TGD的界面逻辑，因为后续所有高级功能都建立在这一基础之上。