feat(HDMI-Tool): CustomTkinter 双栏仪表盘界面重构(feature/ctk-ui)
This commit is contained in:
+36
-20
@@ -34,10 +34,15 @@ HDMI-Tool/
|
||||
|
||||
| 文件 | 角色 |
|
||||
|---|---|
|
||||
| `src/hdmi_gui.py` | 单文件主程序：GUI(tkinter) + 命令行 + 光机控制区, 纯标准库 + 可选依赖 |
|
||||
| `src/hdmi_gui.py` | 入口: argparse 命令行分发(--dump/--edid-fields/--test-pattern/--dlpc-cmd/--seconds), GUI 委托 app_gui |
|
||||
| `src/app_gui.py` | CustomTkinter 主界面: 双栏仪表盘(左 HDMI 源端五卡/右 光机四卡), 光强/定时快捷滑条 |
|
||||
| `src/display_win.py` | Win32 显示器枚举/分辨率切换/智能拓扑(纯 ctypes) |
|
||||
| `src/edid_parse.py` | EDID 1.4/CEA-861 解析(纯标准库, 上游 lt8619c_edid.c 以此为参考解码器) |
|
||||
| `src/patterns.py` | 测试图案全屏投屏窗口(tkinter, ESC 退出, 测试卡区域 1:1 居中) |
|
||||
| `src/config.py` | 运行目录定位(BASE_DIR)与 pattern_slots.json 读写(slots/area/serial 三键) |
|
||||
| `src/dlpc_rs485.py` | 光机 RS485 协议模块: 帧构造/增量解析/译码表/预设命令/串口线程(DLPC485) |
|
||||
| `src/selftest_rs485.py` | 光机协议自检(对照上游实测帧向量, 无硬件回归, 改协议代码后必跑) |
|
||||
| `src/build_exe.py` | PyInstaller 打包 → `release/HDMI-Tool.exe`（onefile/noconsole，内嵌图标+pyserial） |
|
||||
| `src/build_exe.py` | PyInstaller 打包 → `release/HDMI-Tool.exe`（onefile/noconsole, 内嵌图标+pyserial+customtkinter） |
|
||||
| `src/package_release.py` | 复制图案到 release/(平铺) → `release/HDMI-Tool-v<ver>-win64.zip`（校验栏位引用完整性; release/ 与 zip 内容一致） |
|
||||
| `src/publish_gitea.py` | 建/复用 Gitea Release 并上传 zip（tag 默认取 zip 文件名） |
|
||||
| `src/hdmi_source.ps1/.bat` | 独立 PowerShell 命令行工具（自包含，与 GUI 无代码共享） |
|
||||
@@ -46,17 +51,21 @@ HDMI-Tool/
|
||||
| `src/la_wave_analyzer*.py` | 逻辑分析仪 CSV 波形判读（2/3 通道，40MHz 像素时钟假设） |
|
||||
| `src/logos/make_ico.py` | svg/png → ico（写在其自身目录） |
|
||||
| `release/pattern_slots.json` | 预置栏位：西门子星/波带片/综合测试卡，area=640x360；`serial` 键记忆光机串口 |
|
||||
| `UI参考布局.svg/.png` | 界面布局设计稿（app_gui.py 双栏布局的规格来源, 随分支入库） |
|
||||
|
||||
## 3. 代码不变量（改 hdmi_gui.py 必须维持）
|
||||
|
||||
1. **纯标准库 + 可选依赖**：hdmi_gui.py 核心只准用标准库（ctypes/winreg/tkinter/…）。
|
||||
可选依赖一律走"try-import + HAS_* 标志 + 缺失降级"模式：Pillow（自定义图片 JPG/BMP/WebP）、
|
||||
pyserial（光机控制）。缺失时对应功能禁用/提示安装，其余功能必须照常工作。
|
||||
2. **pyserial 只准在 dlpc_rs485.py 里 import**：hdmi_gui.py 通过 `dlpc_rs485.HAS_SERIAL`
|
||||
与 `DLPC485` 类间接使用，不得直接 import serial（协议与串口细节收敛在单一模块）。
|
||||
3. **BASE_DIR 语义**：frozen（PyInstaller onefile）时 `BASE_DIR=exe 所在目录`（`sys.executable`），
|
||||
源码运行时 `=hdmi_gui.py 所在目录`（`__file__`）。所有用户数据（pattern_slots.json、
|
||||
自定义图片）都写/读自 BASE_DIR **平铺**存放，不建子目录。
|
||||
1. **依赖分层**：CLI/显示/EDID/协议/配置模块（display_win/edid_parse/patterns/config/
|
||||
dlpc_rs485）纯标准库；customtkinter 是 GUI（app_gui）的**硬依赖**（装了才能开界面，
|
||||
CLI 不受影响）。可选依赖仍走"try-import + HAS_* 标志 + 缺失降级"模式：Pillow、
|
||||
pyserial——缺失时对应功能禁用/提示安装，其余功能必须照常工作。
|
||||
2. **模块边界**：hdmi_gui.py 只是入口, 不放实现; GUI 不直接碰 ctypes/winreg
|
||||
（显示器走 display_win, EDID 走 edid_parse）; pyserial 只准在 dlpc_rs485.py 里 import
|
||||
（hdmi_gui/app_gui 经 `dlpc_rs485.HAS_SERIAL` 与 `DLPC485` 类间接使用）。
|
||||
3. **BASE_DIR 语义**（定义在 config.py）：frozen（PyInstaller onefile）时
|
||||
`BASE_DIR=exe 所在目录`（`sys.executable`），源码运行时 `=config.py 所在目录`
|
||||
（即 src/）。所有用户数据（pattern_slots.json、自定义图片）都写/读自 BASE_DIR
|
||||
**平铺**存放，不建子目录。
|
||||
4. **自定义栏位 `file` 字段是裸文件名**：加载时 `os.path.join(BASE_DIR, file)` 解析，
|
||||
因此 pattern_slots.json 引用的图片必须与 exe 同目录 —— package_release.py 正是按此平铺打包。
|
||||
5. **exe 自包含**：图标经 `--add-data` 内嵌（运行时从 `_MEIPASS` 读）；内置五种图案
|
||||
@@ -76,6 +85,10 @@ HDMI-Tool/
|
||||
`App.destroy()`，在那里 `dlpc.close()` 收线程。
|
||||
11. **pattern_slots.json 格式**：`{'area', 'slots', 'serial'}` 三键共存；load 兼容旧版
|
||||
纯数组（无 area）与无 serial 键两种历史格式，save 永远写全三键。
|
||||
12. **GUI = app_gui.py 双栏仪表盘**（规格：`HDMI-Tool/UI参考布局.svg`）：左列 HDMI 源端
|
||||
五卡（显示器/模式/EDID 信息/测试图案/hex），右列光机四卡（串口/数据/命令/滑条），
|
||||
顶栏 Dark/Light/System 切换（ttk.Treeview 颜色随动）。打包必须 `--collect-all
|
||||
customtkinter`（build_exe.py 已内置，勿删）——CTk 主题/字体数据缺失会让 exe 启动即崩。
|
||||
|
||||
## 4. 领域语义（测试值都有含义，勿"顺手改"）
|
||||
|
||||
@@ -117,21 +130,24 @@ python publish_gitea.py HDMI-Tool-v<版本>-win64.zip --replace --insecure #
|
||||
|
||||
## 6. 已知坑（历史踩过，勿重蹈）
|
||||
|
||||
- onefile 运行时 `__file__` 指向临时解压目录 `_MEIPASS`，定位 exe 必须用 `sys.executable`（§3.2）；
|
||||
- onefile 运行时 `__file__` 指向临时解压目录 `_MEIPASS`，定位 exe 必须用 `sys.executable`（§3.3）；
|
||||
- 重新打包前旧 exe 可能被残留进程占用 → build_exe.py 会 taskkill 同名进程，手改打包脚本时保留；
|
||||
- 打包后本机图标缓存不刷新：`ie4uinit -show`，不是产物问题；
|
||||
- 改图标流程：改 svg → `make_ico.py` 生成 ico → 重新打包（ico 同时是文件图标与运行时窗口图标）；
|
||||
- GUI 与 hdmi_source.ps1 各自独立实现显示器枚举，行为可能微差（GUI 与 `-List` 序号一致，
|
||||
但与"设置"面板序号无保证）；多屏操作前先确认序号；
|
||||
- `pattern_slots.json` 兼容两种格式：新 `{area, slots[]}`，旧纯数组（无 area）——load_slots 已兼容，
|
||||
但写出只应写新格式。
|
||||
- `pattern_slots.json` 兼容两种历史格式，写出只写新格式（详见 §3.11）；
|
||||
- CustomTkinter 6.x：`CTkComboBox` 不支持 `textvariable`（用 `.set()/.get()`）；`CTkTextbox`
|
||||
的 `tag_config` 在部分版本不可用，app_gui 已 try/except 兜底为单色；同一容器内
|
||||
grid/pack 不可混用（卡片用 grid 挂进列，卡片内部一律 pack——`_card` 返回 (卡片, 内容)）；
|
||||
|
||||
## 7. 验证清单（改完代码后）
|
||||
|
||||
1. `python selftest_rs485.py` —— 光机协议回归（改 dlpc_rs485.py 后必跑，向量来自上游 protocols.md）；
|
||||
2. `python hdmi_gui.py --seconds 5` —— GUI 冒烟（自动开关）；
|
||||
3. `python hdmi_gui.py --test-pattern Checker --area 800x600 --seconds 3` —— 投图链路；
|
||||
4. `python hdmi_gui.py --dump` —— EDID 解算不抛异常；
|
||||
5. `python hdmi_gui.py --dlpc-cmd M999`（不带 --port）—— 应明确报错而非崩溃（无硬件时的优雅降级）；
|
||||
6. `python build_exe.py` → 双击 release/HDMI-Tool.exe 确认图标/启动/投图/光机区渲染；
|
||||
7. `python package_release.py <版本>` —— 不报"引用图片缺失"即栏位完整性 OK。
|
||||
1. `python -m py_compile src/*.py` —— 全模块可编译；
|
||||
2. `python selftest_rs485.py` —— 光机协议回归（改 dlpc_rs485.py 后必跑，向量来自上游 protocols.md）；
|
||||
3. `python hdmi_gui.py --seconds 5` —— GUI 冒烟（自动开关）；
|
||||
4. `python hdmi_gui.py --test-pattern Checker --area 800x600 --seconds 3` —— 投图链路；
|
||||
5. `python hdmi_gui.py --dump` —— EDID 解算不抛异常；
|
||||
6. `python hdmi_gui.py --dlpc-cmd M999`（不带 --port）—— 应明确报错而非崩溃（无硬件时的优雅降级）；
|
||||
7. `python build_exe.py` → 双击 release/HDMI-Tool.exe 确认图标/双栏布局/投图/光机区渲染；
|
||||
8. `python package_release.py <版本>` —— 不报"引用图片缺失"即栏位完整性 OK。
|
||||
|
||||
Reference in New Issue
Block a user