# Qt Widgets 前期教学项目

三个独立的 C++ 桌面项目，对应单位换算、课堂计时、随机抽签与分组。全部使用 Qt Widgets，界面文件为 Qt Designer 的 `.ui`，没有 QML、Qt Quick 或网页界面。

## 项目入口

| 项目 | Qt Creator 入口 | 教学说明 |
|---|---|---|
| 单位换算器 | `01_UnitConverter/UnitConverter.pro` | `01_UnitConverter/README.md` |
| 课堂计时器 | `02_ClassroomTimer/ClassroomTimer.pro` | `02_ClassroomTimer/README.md` |
| 随机抽签与分组 | `03_RaffleGroups/RaffleGroups.pro` | `03_RaffleGroups/README.md` |

每个项目也有独立的 `CMakeLists.txt`。根目录的 `QtTeachingProjects.pro` 和 `CMakeLists.txt` 可以一次打开三个项目。目录使用英文，便于旧版 Windows 构建工具处理路径；界面、注释和教学说明使用中文。

## 先运行，再阅读源码

`Run_Qt5.14.2` 中的三个 EXE 是 Windows 64 位演示程序，附带运行库，可直接双击。转交其他电脑时请复制整个目录。

- `UnitConverter.exe`：单位换算器。
- `ClassroomTimer.exe`：课堂计时器。
- `RaffleGroups.exe`：随机抽签与分组。

## 用 Qt Creator 打开

1. 选择“文件 → 打开文件或项目”，打开上述任意一个 `.pro`。
2. 选择桌面 Kit。本机已经配置的 `Desktop Qt 6.8.3 MinGW 64-bit` 可以使用。
3. 构建并运行。构建目录建议使用英文路径，并与源码目录分开。
4. 双击 `mainwindow.ui` 可进入 Designer，修改布局和组件属性。
5. 换用 Qt 5.14.2 时，选择对应的 Qt 5.14.2 桌面 Kit，并使用新的构建目录。Qt 库与编译器必须属于匹配的 Kit，不能混用 MinGW 与 MSVC。

源码以 Qt 5.14.2 为最低版本。Qt 5 构建使用 C++14；Qt 6 构建自动使用 C++17。没有使用 Qt 6 专有的控件接口，也没有要求 Qt 5.15 的无版本 CMake 目标。

## 怎样阅读

每个项目都按下面的顺序阅读：

1. `mainwindow.ui`：先认清组件名称与布局。
2. `main.cpp`：创建应用、应用外观、显示主窗口、进入事件循环。
3. `mainwindow.cpp`：找出信号连接，再追踪一次按钮操作。
4. `conversion.cpp` / `countdown.cpp` / `roster.cpp`：阅读不依赖具体控件的计算规则。
5. `tests`：查看正常输入和边界情况应得到什么结果。

`appearance.h` 只负责字体与样式，可以在学生掌握功能后再讲。业务逻辑没有依赖这些样式。当前交付的是可运行的完整参考工程，学生练习见各项目 README。

## CMake 构建

以 Qt 5.14.2 的 MinGW Kit 为例，先将匹配的编译器、Qt 的 bin 和 Ninja 加入当前终端 PATH，再运行：

```powershell
cmake -S . -B build-qt5 -G Ninja -DCMAKE_PREFIX_PATH="D:/Qt/5.14.2/mingw73_64" -DCMAKE_BUILD_TYPE=Release
cmake --build build-qt5
```

示例中的 Qt 路径需要替换成实际安装位置。本机 Qt 6 的前缀为 `D:/Qt/6.8.3/mingw_64`，编译器位于 `D:/Qt/Tools/mingw1310_64/bin`。旧版本 Qt Creator 可直接使用 qmake 工程，不必额外配置 CMake。

## 自动化验证

测试需要同一套 Qt 中的 Qt Test 模块。普通构建默认不编译测试：

```powershell
cmake -S . -B build-test -G Ninja -DCMAKE_PREFIX_PATH="你的Qt目录" -DBUILD_TEACHING_TESTS=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build-test
ctest --test-dir build-test --output-on-failure
```

也可打开各项目 `tests` 中的 `.pro` 独立运行测试。测试在后台使用 offscreen 平台，不打开浏览器。Windows 上如需保存包含中文的后台截图，可设置：

```powershell
$env:QT_QPA_FONTDIR = "C:/Windows/Fonts"
$env:QT_TEACHING_SCREENSHOTS = "D:/QtTeachingScreenshots"
```

测试覆盖换算公式、非法输入、暂停与继续、延迟刷新、不重复抽签、分组完整性，以及主要按钮操作。具体版本、编译器和结果见 `verification/验证说明.md`。