注意

此次更新变更了TextBox::setText语义之前如果再调用setText之后手动调用了draw方法现在应当删除，否则旧代码在新版本可能会造成TextBox闪烁（概率触发）【配置包含目录与库目录】

🙏 鸣谢

感谢用户Pengfei Zhu帮StellarX完善文档【配置包含目录与库目录】部分，以及反馈在窗口模式传递参数NULL时会弹出命令行窗口的问题Issues#9

⚙️ 变更

• TextBox::setText语义变化:由原来的仅标脏改为更健全的工作原理
  • 如果文本未发生变化则立即return不做任何操作
  • 如果文本变化则根据是否已经创建图形上下文/窗口决定是否立即重绘/向上请求，如果图形上下文/窗口还为创建则仅标记为脏
• TextBox-文本溢出截断：如果用户输入或者调用setText设置文本，文本不超过maxCharLen但是像素长度超过TextBox则按字符截断并添加…绘制，内部仍然保存完整的文本不影响get方法获取

✅ 修复

• Window::runEventLoop普通控件事件分发顺序：将controls(vector)的正序遍历for (auto& c : controls)改为逆序遍历for (auto it = controls.rbegin(); it != controls.rend(); ++it)

• TabControl::getActiveIndex() const当页签对列表不为空时，如果所有页签都未激活则会返回最后一个页签的索引：修复再调用getActiveIndex()概率获取错误的索引，如果页签对列表为空或者没有页签激活则返回-1，如果有页签激活则返回对应页签索引

• 对话框打开时持续持续触发全量重绘：Window新增变量dialogOpen，在对话框弹出时设置dialogOpen为true，只有dialogOpen为真时才判断needredraw，在重绘后立即设置dialogOpen为flase

• 对话框关闭合成WM_MOUSEMOVE下发更新 可见控件hover 状态，在对话框打开时也会触发：合成WM_MOUSEMOVE下发时判断是否有对话框关闭，只有dialogClose为真才合成并下发WM_MOUSEMOVE

✨ 新增

• 日志系统使用Demo 在：examples\SXLog-日志系统使用demo
• 轻量日志系统 SxLog（SxLogger / SxLogLine / SxLogScope / Sink / TagFilter / LanguageSwitch）：新增统一日志入口与宏封装，支持按级别与 Tag 筛选输出，支持控制台/文件落地与可选滚动（按大小阈值），并提供中英文双语文本选择能力（SX_T / SxT）。日志宏具备短路机制：未命中级别或 Tag 时不构造日志对象、不拼接字符串；输出侧以行级互斥保证多线程下不交错。该模块不依赖 WinAPI 调试输出通道、不引入第三方库。
  • 典型用法：SX_LOGD/SX_LOGI/SX_LOGW/SX_LOGE/SX_LOGF/SX_LOG_TRACE + 流式拼接；SX_TRACE_SCOPE 作用域耗时统计
  • 核心配置：setMinLevel(...)、setTagFilter(...)、enableConsole(true/false)、enableFile(path, append, rotateBytes)、setLanguage(ZhCN/EnUS)、setGBK()

⚙️ 变更

• TabControl 页签切换时序调整：修改页签按钮切换逻辑为“先关闭当前已打开页，再打开目标页”，避免“先打开再关闭”在复杂容器/快照链路下引入的时序不确定性；对外 API 不变（涉及 TabControl::add 内部切换逻辑）。
• 控件 Setter 语义收敛：明确控件 Setter 的职责为“更新状态并标脏”，绘制统一由窗口/容器的重绘收口机制触发，降低生命周期耦合与快照污染风险（见下方相关修复条目）。

✅ 修复

• TextBox::setText 在进入事件循环前调用触发中断：修复在窗口尚未初始化（未 initgraph()、图形上下文未就绪）前调用 TextBox::setText() 导致访问冲突崩溃的问题。旧实现将“状态更新”和“立即绘制”耦合，setText() 内部直接触发 draw()，进而在无图形上下文时进入 saveBackground()/getimage() 路径崩溃；现已移除 Setter 内直接绘制，仅保留赋值与置脏，绘制交由统一重绘流程完成。
• TabControl 切换/关闭后 Table 新旧内容重叠（重影）：修复页签切换与表格重置数据后出现的稳定残影问题。根因是“快照未就绪阶段发生局部重绘”导致快照污染；本次回退 setIsVisible(true) 的“立即向上 requestRepaint”行为，改为仅置脏，并为 Canvas::requestRepaint 与 TabControl::requestRepaint 增加护栏：当容器 dirty 或 hasSnap=0 或快照缓存无效时，禁止 partial fast-path，自动降级为全量重绘以保证快照链路正确性；同时修正 Table::setData(...) 列补齐边界问题，降低异常噪声。

⚠️ 可能不兼容

• 删除 Button 尺寸别名 API（Breaking）：移除 Button::getButtonWidth() / Button::getButtonHeight()，统一使用基类 Control::getWidth() / Control::getHeight() 获取控件尺寸。该改动会导致旧代码在升级到 v3.0.0 后编译失败，但行为语义保持一致（仍读取同一 width/height）。
• 可见性/文本设置的“即时刷新”副作用移除：setIsVisible(true) 与 setText() 等 Setter 不再保证立刻触发绘制；如业务代码此前依赖“调用后立即可见”，需要确保后续存在一次重绘收口（窗口主循环/容器重绘/显式刷新）以完成视觉更新。

📌 升级指引

在程序入口完成基础配置（控制台输出/最低级别/语言），并使用统一 Tag（如 Dirty/Resize/Table/Canvas/TabControl）建立可回放的事件链路；高频路径建议通过级别与 Tag 控制噪声与 I/O 成本。

Button 宽高接口迁移：

• getButtonWidth() → getWidth()
• getButtonHeight() → getHeight()

Setter 不再“立即绘制”的适配：

• 初始化阶段可先设置属性（如 TextBox::setText("default")），由首次 Window::draw() / 主事件循环的统一绘制完成可视刷新；
• 若在非事件驱动场景下程序化更新后需要立刻刷新，请确保触发一次统一重绘路径（避免在 Setter 内手动调用 draw() 造成生命周期耦合）。

SxLog 接入建议：

• 在程序入口完成基础配置（控制台输出/最低级别/语言），并使用统一 Tag（如 Dirty/Resize/Table/Canvas/TabControl）建立可回放的事件链路；高频路径建议通过级别与 Tag 控制噪声与 I/O 成本。

✨ 新增

• Table 支持运行期重置表头与数据：新增 Table::clearHeaders()、Table::clearData()、Table::resetTable()，允许同一 Table 在运行过程中动态切换表头与数据，并触发必要的单元格尺寸/分页信息重算与重绘。
• TextBox 新增密码模式：TextBoxmode 新增 PASSWORD_MODE；输入内容内部保存，绘制层面使用掩码字符（如 *）替代显示，真实文本可通过 TextBox::getText() 获取。

⚙️ 变更

• TabControl 默认激活页语义明确化：
  • 首次绘制前调用 TabControl::setActiveIndex()：仅记录默认激活索引，不再立即触发页签按钮点击回调；
  • 首次绘制完成后：若设置了默认激活索引则应用激活状态并绘制激活页（索引越界时默认激活最后一个页）；
  • 程序运行过程中调用 TabControl::setActiveIndex()：索引合法则立即切换激活页并绘制；索引越界则不做处理。

✅ 修复

TabControl 由不可见设置为可见时绘制错乱：修复 setIsVisible(false) -> setIsVisible(true) 后非激活页被错误绘制导致的多页重叠/残影；现在 TabControl 可见时仅激活页可见/可绘制，无激活页则不绘制任何页。

TabControl::setActiveIndex 绘制前调用导致程序中断：修复绘制前设置默认激活索引时触发空指针访问的问题；现在默认激活逻辑延后到首次绘制完成后再生效，避免崩溃并保证首次绘制即可绘制激活页。

🙏 鸣谢

• 感谢用户 @To-KongBai 提供稳定复现步骤与关键现象对比（容器嵌套孙控件坐标转换问题），帮助我们快速确认多容器嵌套时的控件坐标转换问题并修复。（Issues#6）
• 在即将上线的官网中（ICP备案中）我们计划加入一个贡献者鸣谢墙，欢迎各位用户反馈BUG或者分享自己用星垣做的界面，我们将认真阅读并收录鸣谢
• 真诚的感谢每一位反馈BUG的用户，你们的反馈将使星垣更加稳定和健壮

✨ 新增

新增一个登录界面Demo在主仓库examples/目录下

⚙️ 变更

• Dialog背景快照机制：Dialog不在自己抓取和销毁快照，删除重载的抓取和恢复快照的方法，完全交由基类Canvas处理，Dialog的draw方法中不在处理快照
• 窗口变化重绘时控件和窗口重绘的时机调整：主事件循环中窗口大小发生变化时先处理控件尺寸，并回贴和释放旧快照，然后再重绘新尺寸窗口，最后绘制控件

✅ 修复

Table动态改变坐标页码标签和翻页按钮错乱：在Table控件的setX/Y中重置isNeedButtonAndPageNum状态为真，在绘制时重新计算翻页按钮和页码标签的位置以保持在表格正下方居中位置显示

容器嵌套时子控件坐标转化：Canvas重写了基类的setX/Y方法，在容器全局坐标发生变化时同步修改子控件的全局坐标，防止在容器嵌套时，容器的相对坐标被子控件当成全局坐标处理

纯色背景窗口标题不生效：在Window的draw()方法中强制设置窗口标题，以防止，创建窗口时传递的窗口标题不生效

选项卡控件页签打开时动态改变坐标背景残留：在TabControl重写的setX/Y方法中，当选项卡的坐标发生变化时强制让所有页签以及页和子控件丢一次快照，防止，在修改坐标后因，快照恢复顺序引起的选项卡激活页残留

✨ 新增

• 新增LayoutMode自适应布局模式和Anchor锚点，控件中可以调用 setLayoutMode
  设置布局模式以及steAnchor设置锚点，达到窗口拉伸时控件自适应窗口变化。对话框控件在窗口变化时只会重新计算位置，来保证居中显示
• Window新增adaptiveLayout()这个API由主事件循环调用，在窗口拉伸时根据锚点重新计算控件位置和尺寸，使左右/上下双锚定控件随窗口变化自动伸缩。

⚙️ 变更

• 优化窗口尺寸调整机制：重构 WndProcThunk、runEventLoop 和 pumpResizeIfNeeded，统一记录窗口尺寸变化并在事件循环尾部一次性重绘，避免拉伸过程中重复绘制引发抖动与顺序错乱。
• 新增对话框尺寸调度接口：引入 Window::scheduleResizeFromModal()，配合 pumpResizeIfNeeded() 使用。模态对话框显示期间，父窗口可实时更新客户区尺寸并在统一收口时重新布局子控件，对话框自身尺寸保持不变。
• 重绘顺序优化：在窗口尺寸变化后的收口阶段使用 ValidateRect 代替 InvalidateRect，避免系统再次发送 WM_PAINT 导致重入绘制。
• 其他改进：修复表格翻页按钮与页码标签等元素背景快照更新不及时的问题；改进对话框背景捕捉逻辑。

✅ 修复

稳定性修复：修正某些情况下窗口尺寸突变导致的异常帧；解决表格和对话框背景快照在边界条件下未及时更新的问题。

模态对话框拉伸修复：解决了模态对话框弹出时，窗口拉伸无法让底层控件按照锚点更新尺寸和位置的问题；同时避免对话框反复重绘导致残影。

绘制顺序错乱修复：解决窗口拉伸时偶发的绘制顺序紊乱、控件残影和边框闪烁问题，确保控件按添加顺序依次绘制。