3、第一个TouchGFX项目：使用Designer创建空白项目、屏幕与画布概念、模拟器运行、生成代码并导入IDE
好，咱们正式开始动手了。
这一章的目标很简单——让你亲手跑起来第一个TouchGFX界面。哪怕你之前没接触过任何GUI框架，跟着走一遍，也能看到屏幕上出现你自己的第一个画面。
我个人习惯，学一个新工具时，先别管那么多理论，先让东西跑起来再说。有了感性认识，后面再讲概念你才记得住。
3.1 用Designer创建空白项目
打开TouchGFX Designer，你会看到一个启动界面。别被它吓到，其实核心操作就几步。
- 点击 “Create New Project”。
- 弹出一个对话框，让你选模板。我们选 “Empty UI”——空白项目，干干净净。
- 给项目起个名字，比如
MyFirstGUI。路径建议用默认的，或者放到一个你记得住的目录。 - 点击 “Create”，等几秒钟。
嗯，这里要注意：项目名不要带中文和空格。我之前有个同事用了中文名，结果编译时报了一堆莫名其妙的路径错误，排查了半天才发现是编码问题。
创建完成后，你会看到Designer的主界面。左边是组件面板，中间是画布，右边是属性面板。先别急着点，我们看看这个界面到底在说什么。
核心理解：TouchGFX Designer本质上是一个代码生成器。你在界面上拖拖拽拽，它背后帮你生成C++代码。所以，你看到的每一个控件、每一个屏幕，最终都会变成实实在在的代码文件。
3.2 屏幕与画布概念
很多初学者会把“屏幕”和“画布”搞混。我刚开始学的时候也迷糊过，这里给你讲清楚。
| 概念 | 含义 | 类比 |
|---|---|---|
| 屏幕（Screen） | 一个完整的界面状态，包含多个控件和逻辑 | 就像手机上的一个页面 |
| 画布（Canvas） | 屏幕内部的绘制区域，用于放置控件 | 就像画板上的白纸 |
说白了，一个屏幕可以包含多个画布，但一个画布只能属于一个屏幕。你想想看，手机上一个页面里可能有不同的区域——标题区、内容区、底部按钮区——每个区域都可以是一个画布。
在Designer里，默认创建的空项目已经有一个屏幕了，叫 Screen1。你可以在左侧的“Screens”面板里看到它。双击它可以重命名，但我建议先保持默认，等后面熟悉了再改。
我的经验：项目初期，尽量保持屏幕命名规范。比如用 MainScreen、SettingScreen 这样的名字，别用 Screen1、Screen2。等项目做到几十个屏幕时，你就知道命名规范有多重要了。
3.3 模拟器运行——第一次看到你的界面
好，现在我们来点最激动人心的操作——运行模拟器。
- 在Designer的右下角，找到 “Run Simulator” 按钮（一个绿色的播放图标）。
- 点击它，Designer会先编译你的项目（第一次会慢一点，别急）。
- 编译完成后，会自动弹出一个模拟器窗口。
你会看到一个空白的屏幕，背景是默认的深灰色。嗯，确实很“空”。但别失望，这证明你的开发环境已经全部打通了。
模拟器窗口有几个功能值得注意：
- 鼠标拖拽：可以模拟触摸操作
- 键盘快捷键：比如按
F1可以查看帧率 - 窗口缩放：可以调整模拟器大小，看看不同分辨率下的效果
我曾经在调试一个动画性能问题时，全靠模拟器的帧率显示来定位问题。所以这个 F1 快捷键，你最好记一下。
注意：模拟器跑的是你PC上的x86程序，不是ARM交叉编译。所以模拟器上的性能表现，只能作为参考。真正上硬件后，帧率可能会有明显差异。尤其是动画和图片解码，硬件上往往比模拟器慢不少。
3.4 生成代码并导入IDE
模拟器跑通了，接下来我们要把Designer生成的代码导入到真正的IDE里，这样才能编译成嵌入式固件。
3.4.1 生成代码
在Designer里，点击菜单栏的 “File” → “Generate Code”，或者直接按快捷键 Ctrl+G。
Designer会在你的项目目录下生成一堆文件。核心目录结构是这样的：
MyFirstGUI/
├── assets/ # 资源文件（图片、字体等）
├── generated/ # Designer自动生成的代码
│ ├── gui/ # 界面相关代码
│ └── touchgfx/ # TouchGFX框架核心
├── src/ # 用户自定义代码
├── target/ # 硬件平台相关配置
└── MyFirstGUI.touchgfx # 项目配置文件这里我要强调一下：千万不要手动修改 generated/ 目录下的文件。因为每次你在Designer里修改界面并重新生成代码，这个目录都会被覆盖。我之前有个项目，同事直接在 generated/ 里改了布局代码，结果Designer一重新生成，他的修改全没了，白干半天。
3.4.2 导入到IDE
TouchGFX官方推荐使用 STM32CubeIDE 或者 Keil MDK。我这里以STM32CubeIDE为例，因为它是免费的，而且和TouchGFX集成得最好。
- 打开STM32CubeIDE，选择 “File” → “Import”。
- 选择 “General” → “Existing Projects into Workspace”。
- 浏览到你刚才生成的项目目录，选中
MyFirstGUI文件夹。 - 点击 “Finish”，项目就会被导入。
导入后，你会看到项目结构里多了一些IDE相关的配置文件。别慌，这些都是自动生成的。
小技巧：如果你用的是Keil，导入方式类似。但要注意，Keil项目文件（.uvprojx）可能不在根目录，而是在 target/ 目录下。我第一次用Keil时找了半天项目文件，后来才发现它在 target/Keil/ 里。
3.4.3 编译与下载
在IDE里，直接点击编译按钮。如果一切顺利，你会看到控制台输出 Build Finished，没有错误。
然后连接你的开发板（比如STM32F429 Discovery Kit），点击下载按钮。等几秒钟，开发板上的屏幕就会亮起来，显示你在Designer里看到的那个空白界面。
嗯，虽然还是空白的，但这是你自己亲手跑起来的第一个嵌入式GUI程序。成就感应该还是有的。
关键流程总结：
Designer设计界面 → 生成代码 → IDE编译 → 下载到硬件 → 屏幕显示
这个流程，后面每一章都会重复。所以现在把它刻在脑子里。
3.5 本章知识体系
为了让你更直观地理解这一章的内容结构，我画了一张流程图。
这张图把我们从创建项目到硬件运行的完整路径串起来了。你跟着箭头走一遍，就是整个开发流程。后面每一章的内容，都会在这个流程的某个环节上深入展开。
3.6 避坑指南
最后，分享几个我实际踩过的坑，你遇到了可以少走弯路。
- 路径问题：项目路径不要有中文、空格、特殊字符。我见过最离谱的是路径里带了个“&”符号，编译直接报语法错误，排查了两小时。
- 版本匹配：TouchGFX Designer、STM32CubeIDE、硬件固件包，这三者的版本要匹配。官方有版本兼容性表格，生成项目前最好看一眼。
- 模拟器闪退：如果模拟器启动后立刻闪退，八成是显卡驱动问题。更新一下显卡驱动，或者把模拟器的渲染模式从OpenGL切换到Software。
- 代码生成失败：如果点击Generate Code后报错，先检查项目里有没有未保存的修改。Designer有时候会因为你没保存而拒绝生成。
好了，这一章的内容就到这里。你现在应该已经成功跑起来了第一个TouchGFX项目，并且理解了屏幕、画布、模拟器、代码生成这几个核心概念。这些东西是后面所有章节的基础，务必亲手操作一遍，光看是记不住的。