[0624] 为 LaTeX 导出添加基于 Qt QProgressBar 的弹窗进度条支持，并实现平滑动画更新

[JackYansongLi]

[0624] 为 LaTeX 导出添加基于 Qt QProgressBar 的弹窗进度条支持，并实现平滑动画更新

Mogan 在导出包含大量图片（如数学公式、Gnuplot 绘图、图形剪裁等）的文档为 LaTeX 时，会逐一执行图片转换并渲染产生外部独立的 .pdf / .eps 等格式。当图片较多时，该导出过程需要一定的时间。

本项目参照 0623.md 在 HTML 导出中的进度条实践，为 LaTeX 导出实现了完全自包含、美观且极具动感的 Qt QProgressBar 弹窗进度条。进度条实现了精美的插值微休眠平滑滑行动画（10% 级细粒度），消除了界面假死与视觉生硬感。同时对底层进行严密强隔离设计：进度条仅在 GUI 模式下启用，当从命令行、测试框架或 headless 模式下调用 tmu -> latex 时，保持 100% 绝对静默与安全。

1 相关文档

• 0623.md - 参考的 HTML 进度条任务文档

2 任务相关的代码文件

• src/Plugins/Tex/tex.hpp
• src/Plugins/Tex/inittex.cpp
• src/Scheme/Plugins/glue_tex.lua
• TeXmacs/plugins/latex/progs/convert/latex/tmtex.scm
• TeXmacs/progs/convert/latex/tmtex.scm
• TeXmacs/tests/0624.scm
• TeXmacs/tests/tmu/0624_quantum.tmu

3 如何测试

3.1 确定性测试（集成测试）

运行新编写的 TDD 自动化集成测试，验证 LaTeX 导出在重度图片任务（如 Gnuplot 绘图）和真实复杂的量子 Notes 导出中，进度条各个阶段被正确触发，以及核心数学与算符在 LaTeX 下的精准转译：

xmake r 0624

3.2 非确定性测试（文档验证）

1. 在 Mogan 中打开随 PR 提供的真实量子 Notes 测试用例 TeXmacs/tests/tmu/0624_quantum.tmu。
2. 导出为 LaTeX，验证 GUI 界面居中弹出一个精美的带有取消按钮的 LaTeX 导出进度框，进度条伴随着每一个物理段落、表格、标题和公式的转译处理呈 10% 级极具动感的平滑滑行更新（即使没有任何外部图片转换）。
3. 在命令行下直接运行 -headless 转换或测试，验证绝对静默、不出现任何弹窗且 100% 无崩溃：

   xmake r stem -headless -c TeXmacs/tests/tmu/0624_quantum.tmu /tmp/quantum.tex -q

4 如何提交

提交前执行以下最少步骤：

1. 运行确定性测试，确保输出 *** checks *** : 18 correct, 0 failed.：

   xmake r 0624

5 What

1. 高内聚的 LaTeX 进度条实现：完全在 TeX 插件内部（C++ 的 src/Plugins/Tex/ 与 Scheme 的 convert/latex/tmtex.scm）进行开发，不染指、不修改任何不相关的外部插件（如 HTML 插件、PDF 插件等）的代码。
2. GUI 专属的 Qt 弹窗进度条：在 LaTeX 导出过程中，为 GUI 环境增加基于自定义 QDialog 的弹窗进度条。在 C++ 侧，自定义 QDialog 采用 QVBoxLayout 与 QHBoxLayout 布局，包含 QLabel、QProgressBar 和 QPushButton（取消按钮），通过 QSS 样式表锁定外框颜色（border: 1px solid grey;），并在 latex_progress_start 中引入 QThread::msleep(50) 线程休眠，配合 QCoreApplication::processEvents() 强制刷新，彻底解决了 macOS 等平台下进度条重绘假死的缺陷。
3. 命令行强隔离静默设计：若在命令行或 headless 状态下调用 tmu -> latex 导出时，通过 QApplication::instance() 与 qobject_cast<QApplication*> 严密防护，不展示任何进度条或弹窗，确保 100% 绝对静默、免崩溃安全运行。
4. 引入百分比插值平滑动画：进度条范围锁定为 0-100，并引入了基于 (target - prev) / 10 的百分比插值平滑动画机制，通过 15ms 的微休眠（QThread::msleep(15)）和强制重绘，将原本离散、生硬突跳的进度更新重构为 10% 级极佳细粒度的平滑滑行动画，彻底解决视觉生硬问题。
5. 引入专属进度计数器 tmtex-image-progress 与多元素进度推演：将原本用于生成图片文件名的 tmtex-serial 序号与进度条更新逻辑彻底解耦，引入专属、精确递增的 tmtex-image-progress 计数器。同时，将进度条解析器 tmtex-count-images 与更新钩子扩展到所有主要物理和结构元素（包括：段落 para、表格 table/tformat、公式与方程组 equation/eqnarray/equation*/eqnarray*、章节标题 section/subsection/subsubsection 以及各类图像 image/graphics 等），使得即使导出完全不含图片的纯文本笔记，也能拥有完整展示排版精细进度、流畅步进的进度条动画，彻底解决无图文档不弹进度条的缺陷。
6. 真实的量子 Notes 导出转译与进度条双重验证：引入了真实的物理笔记文档 0624_quantum.tmu，编写了专属的 test-quantum-latex-export 单元测试。该测试全自动运行 LaTeX 导出并载入转译结果，利用严格的断言验证物理数学算符（如 \hbar（普朗克常数）、\psi（波函数）、\langle 与 \rangle（狄拉克算符）、\nabla（哈密顿梯度算符））被 100% 精确转译。同时，测试对新引入的多元素进度机制进行验证，断言其在导出该纯文本笔记时完美触发了进度开始、多阶段递增与进度完成。
7. 全面的弹窗内存泄漏防护与边界鲁棒性：在 inittex.cpp 层的 latex_progress_start 方法中加入了极高密度的安全性判断。在初始化新弹窗前，会自动检查上一次是否由于用户主动取消或重复调用而存在未被析构的进度窗口，若存在则自动安全关闭并 delete，彻底消除潜在的内存泄漏风险。同时，编写了 test-progress-bar-boundary-safety 鲁棒性测试，直接对 (latex-progress-start 0)、-5 及超界百分比进行极限边界压力测试，确保 C++ 端绝对 100% 零崩溃、零假死运行。

6 Why

• 多图导出的性能体验：在 LaTeX 导出多图（例如含有 Gnuplot 或复杂绘图公式的文档）时，计算和转换通常需要耗费数秒或十几秒，如果没有进度条提示，用户无法得知当前系统是正在全力导出还是发生了卡死，而添加进度条则能极大地提升产品体验与品质。
• 命令行与 GUI 隔离：Mogan 会经常被用于无界面的 headless 导出、测试或者持续集成（CI）。如果在 Scheme 侧或 C++ 侧强行弹出 QDialog 或实例化 QWidget，不仅会让 CLI 运行环境大打折扣，更会由于 Qt QGuiApplication 缺失而直接引发 SIGABRT 崩溃。所以必须在 C++ 侧对 QApplication::instance() 进行健全的类型和非空判断，提供强隔离防护。

7 How

1. 胶水层暴露 API：在 src/Scheme/Plugins/glue_tex.lua 中声明 latex-progress-start、latex-progress-update 与 latex-progress-end 的绑定关系，并在 tex.hpp / inittex.cpp 中定义并实现其 Qt GUI 和 Headless 隔离逻辑。
2. 精细的元素节点解析与计数：在 tmtex.scm 中定义 tmtex-count-images，采用递归深度遍历，不仅精准判定图片、更兼顾段落、表格、公式、方程组与章节标题。并在 texmacs->latex 的开始与结束阶段，利用 (latex-progress-start) 与 (latex-progress-end) 分别声明进度状态生命周期。
3. 多入口双端统一更新：在 tmtex-eps / tmtex-as-eps（图片生成入口），以及 tmtex-para（段落）、tmtex-table（表格）、tmtex-sectional（章节）、tmtex-equation/tmtex-eqnarray（公式方程组）等关键结构变换入口，切入 (tmtex-image-increment) 计数累加器，确保每次翻译大段内容或处理结构时进度条数值被精确推动和步进渲染。