Codex
78 lines
4.2 KiB
Markdown
78 lines
4.2 KiB
Markdown
# 功能变更 ID: Feature-20260317-0002
|
||
|
||
> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
|
||
> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
|
||
|
||
## 基本信息
|
||
|
||
- ID: Feature-20260317-0002
|
||
- 标题: TextBox::setText 运行期刷新语义调整
|
||
- 状态：已完成（历史记录；本次仅归档，未重新验证）
|
||
- 类型：修改
|
||
- 级别：L2 中等
|
||
- 模块: TextBox / Repaint
|
||
- 版本 / 分支: v3.0.1 / master
|
||
- 环境: Windows 11 / Visual Studio 2022 / Debug、Release / EasyX
|
||
- 负责人: Ysm-04（历史实现）
|
||
|
||
## 变更背景
|
||
|
||
- 背景:
|
||
- 早期 `setText()` 直接调用 `draw()`，在图形上下文尚未初始化时可能崩溃。
|
||
- v3.0.0 将 Setter 收敛为更新状态并标脏，解决初始化阶段的生命周期问题，但运行期程序化设置文本可能要等后续事件或重绘周期才能显示。
|
||
- 目标: 在不破坏初始化阶段安全性的前提下，让已经绘制过的 TextBox 在运行期更新文本后请求或执行刷新。
|
||
- 不做什么：[可选]
|
||
- 不改变 `setText(std::string)` 的函数签名。
|
||
- 不在没有有效背景快照时强制进入绘制链路。
|
||
|
||
## 变更内容
|
||
|
||
- 变更摘要: `setText()` 根据文本是否变化、最大长度、父控件和有效快照状态决定仅标脏、向父控件请求重绘或直接绘制。
|
||
- 新增项：[可选]
|
||
- 文本未变化时立即返回，避免无效更新。
|
||
- 修改项：[可选]
|
||
- 文本变化后始终更新内部值并标记为脏。
|
||
- 有父控件且 `hasSnap` 为真时，调用 `requestRepaint(parent)`。
|
||
- 无父控件且 `hasSnap` 为真时，直接调用 `draw()`。
|
||
- `hasSnap` 为假时只保留脏标记，等待首次绘制或统一重绘流程。
|
||
- 删除 / 废弃项：[可选]
|
||
- 无。
|
||
- 受影响的文件 / 类 / 函数:
|
||
- 历史路径：`src/textBox.cpp`
|
||
- `TextBox::setText(std::string)`
|
||
- 对外 API / 属性变化：[可选]
|
||
- 函数签名不变；运行期可见刷新时机发生变化。
|
||
|
||
## 行为对照
|
||
|
||
- 变更前（v3.0.0）: `setText()` 更新内部文本并标脏，不保证调用后立即触发可见重绘。
|
||
- 变更后（v3.0.1）:
|
||
- 初始化/首次绘制前没有有效快照，仅更新文本并标脏，不触发依赖图形上下文的绘制。
|
||
- 已绘制且存在有效快照时，通过父容器请求重绘；没有父控件时直接绘制。
|
||
- 文本未变化时不执行重复重绘。
|
||
- 兼容性说明：部分兼容
|
||
- 迁移说明：[可选]
|
||
- 若旧代码在 `setText()` 后手动调用 `draw()`，升级到 v3.0.1 后应移除重复绘制，避免闪烁或重复刷新。
|
||
- 初始化阶段仍可先设置默认文本，由首次统一绘制完成显示。
|
||
|
||
## 验证与落地
|
||
|
||
- 验证方式:
|
||
- 创建 TextBox，在窗口和图形上下文建立前调用 `setText()`，确认不会进入绘制链路或中断。
|
||
- 窗口运行后，在按钮回调中调用 `setText()`，确认无需额外鼠标事件即可刷新。
|
||
- 重复设置相同文本，确认不会产生无效刷新。
|
||
- 验证结果:
|
||
- PDF 历史记录将“初始化前设置默认文本”和“按钮回调中运行期更新”记为正常。
|
||
- 本次归档通过历史提交确认了 `hasSnap` 分支逻辑，但未构建 v3.0.1，也未重新运行 GUI 用例。
|
||
- `hasSnap` 是历史实现用于判断是否已具备绘制条件的代理状态；本记录不把它扩展解释为所有图形上下文状态的通用保证。
|
||
- 关联 BUG / Fix：[可选]
|
||
- 前序问题：[`BUG-20260109-0001-TextBox-setText进入事件循环前调用崩溃.md`](../BUG/BUG-20260109-0001-TextBox-setText进入事件循环前调用崩溃.md)
|
||
- v3.0.0 修复：[`Fix-BUG-20260109-0001-TextBox-setText进入事件循环前调用崩溃.md`](../Fix/Fix-BUG-20260109-0001-TextBox-setText进入事件循环前调用崩溃.md)
|
||
- Commit:
|
||
- 实现提交：`c66cad3423a46ec4ef902965baa4c1816d10148a`
|
||
- 发布记录提交：`b765e54eff28ebcd0bd99a81dec80b3ac0769337`
|
||
- PR：[可选]
|
||
- 发布版本：[可选] v3.0.1
|
||
- 备注：[可选]
|
||
- 资料来源：`StellarX功能_模块变更.pdf` 第 10-12 页，并以对应提交和历史 `CHANGELOG.md` 交叉核对。
|