# 功能变更 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` 交叉核对。