Changelog

StellarX 更新日志

记录 StellarX 的版本发布、重要变更、缺陷修复、兼容性说明与升级要求。

本页面提供适合快速浏览的版本摘要。完整变更记录以仓库中的 CHANGELOG 与 GitHub Releases 为准。

GitHub Releases 完整 CHANGELOG GitHub 仓库

Current Version

v4.0.0

2026-09-30
版本重点 稳定控件句柄、受控所有权、延迟结构变更事务与核心稳定性修复。
推荐状态 当前稳定发布版本，建议新项目优先使用。
升级关注 包含破坏性 API 调整，从 v3.x 升级前需要完成接口迁移。
Latest

当前维护版本

v4.0.0 是当前维护版本，重点解决控件所有权、回调期间结构变更、重绘残影、文本安全和消息积压问题。

Format

记录格式

更新记录按新增、变更、修复、兼容性与验证分类，便于升级前快速判断影响范围。

Breaking

破坏性升级

v4.0.0 调整了 Window、Canvas、TabControl、ControlText 和 SxLog 的部分公开 API。

Validation

发布验证

当前版本已完成多配置自动化测试、x64 ASan 检查、KEY1 至 KEY6 人工 UI 回归和发布仓库编译链接验证。

Latest Release

v4.0.0 更新日志

发布时间：2026-09-30
下载 v4.0.0

新增

  • 新增 StellarX::ControlHandle，用于在当前进程本次运行期间稳定标识控件。
  • Window 与 Canvas 新增受控所有权接口： addControl()、removeControl()、 clearControls()、findControl()、 getControlHandles()。
  • 新增可嵌套的结构变更事务。事件、绘制、tick 和按钮回调期间的控件新增、删除与清空会先进入 pending 队列。
  • 新增控件 tick 链，Tooltip 等延时状态不再依赖额外的鼠标消息才能推进。
  • 新增 src/internal/SxEventLoopInternal.h 与 src/internal/SxTextInternal.h 两个实现专用私有头文件。

变更

  • ControlText::faceName 改为拥有型 std::string，避免保存外部字符串指针造成生命周期问题。
  • TabControl 改用 addTab(button, page) 和 tryAddToPage(index, control)，页签身份以索引为准，并允许重复标题。
  • TabControl::setActiveIndex() 改为返回 bool； 空容器可以预设首次激活索引，运行期非法索引返回 false。
  • SxLogger::setConfig() 改为返回 bool。 候选文件 sink 打开成功后才替换旧配置，失败时保留旧配置和旧 sink。
  • 事件循环单轮最多批处理 128 条消息。活动轮不再固定休眠，空闲轮使用短暂 Sleep(1)，每批末尾统一收口 resize 与重绘。
  • 源码分发结构调整为： include/StellarX 存放公共头， src 存放实现， src/internal 存放实现专用私有头。

修复

  • 修复回调中删除自身、兄弟控件或清空容器可能造成的 UAF 和迭代器失效。
  • 修复空 TabControl 绘制或激活越界，以及同名页签可能同时处于激活状态的问题。
  • 统一控件背景快照、几何 setter 和 coverage 矩形语义，修复移动、缩放、隐藏后的旧像素与局部重绘残影。
  • 修复 Dialog 关闭清理、overlay 清理时序和底层控件交互恢复问题。
  • 修复 Table 极窄宽度、列宽总和、MBCS 文本截断、coverage 边界及运行期重置后的分页首帧覆盖问题。
  • 修复 Tooltip 在鼠标静止时不能按时出现，以及禁用或移出后状态清理不一致的问题。
  • 修复密码掩码按字节而非逻辑字符生成，以及非法 MBCS 尾字节处理问题。
  • 修复日志同毫秒滚动重名、rename 失败后可能截断原日志，以及配置与文件 sink 状态不同步的问题。

兼容性与迁移

  • 移除 Window::getControls() 与 Canvas::getControls()； 外部代码应保存 ControlHandle，按需调用 findControl()。
  • 移除 Canvas::clearAllControls()，改用 clearControls()。
  • 将 ControlText::lpszFace 替换为 ControlText::faceName。
  • 将旧 TabControl::add(...) 调用迁移到 addTab() 和 tryAddToPage()。
  • 调用 setActiveIndex() 和 SxLogger::setConfig() 时，可以检查新的布尔返回值。
  • 回调中请求删除控件后，不得继续访问该控件；对象会在最外层结构变更事务结束时销毁。

验证

  • Debug x64、Debug x64 ASan、Release x64、Debug Win32 四种配置的非 UI 自动化测试均为 15/15 通过。
  • x64 ASan 未报告内存错误，KEY1 至 KEY6 均完成编译链接。
  • KEY1 至 KEY6 已完成人工 UI 回归，暂未发现明显问题。
  • 发布仓库的 x64 Debug、Release 核心库及 9 个示例均通过编译链接验证。

Known Limits

当前已知限制

  • 尚未实现焦点系统。
  • 尚未实现键盘事件系统。
  • TextBox 仍基于 EasyX InputBox，尚未重写自绘输入体系。
  • Table 内部局部重绘体系尚未完成。
  • Table 当前不支持纵向 Stretch。
  • Table 结构尺寸刷新仍可能发生在 draw 流程中。
  • Canvas 对 Table 的历史兜底特判仍然保留。
  • TabControl 内部布局应用路径尚未完全收口。
  • Tooltip 尚未实现完整智能选位。
  • 暂未提供全局字体自动缩放系统。

Recent Releases

最近版本

官网保留当前版本之外最近四个版本的摘要。完整版本历史请查看仓库 CHANGELOG。
v3.1.0 2026-05-15 单轴布局与托管重绘收口

新增

  • 新增四边集合式锚点语义：水平轴支持 left/right，垂直轴支持 top/bottom。
  • 新增 AxisSizePolicy：Stretch 与 FixedSize。
  • 新增 AxisAlignPolicy：Start、End、Center、Proportional。
  • 新增 AxisLayoutSpec、LayoutSpec、LayoutCapability 和 ResolvedLayoutRect。
  • 新增托管重绘持久 coverage 与临时 coverage 区分。

变更

  • 明确 localx/localy/localWidth/localHeight 为设计态父局部矩形， x/y/width/height 为运行态绘制矩形。
  • Window 顶层控件与 Canvas 子控件统一使用单轴布局解算语义。
  • Dialog 在窗口尺寸变化时只重新居中，不参与拉伸。
  • TabControl 外层接入统一布局，内部页签栏和页面区仍由自身管理。
  • Table 的能力边界明确为 X 轴可拉伸、Y 轴固定。
  • 旧 setLayoutMode() 与 setAnchor() 继续作为兼容输入层保留。

修复

  • 修复 TabControl::indexOf() 未命中时返回值错误的问题。
  • 修复 Dialog 与 overlay 遮挡、关闭后底层 hover 和 Tooltip 状态不同步的问题。
  • 修复局部提交 coverage 扩张后，上层 Dialog 或 overlay 可能漏补画的问题。
  • 修复跨 root 回调修改状态后未在同一轮事件尾提交的问题。
  • 修复 Tooltip 被兄弟控件背景快照捕获后产生残留或擦除的问题。
  • 修复多层 Canvas、TabControl、Table、Dialog 混合遮挡下的若干重绘错层问题。
  • 修复 TextBox 在 GBK/MBCS 下可能截断半个中文字符的问题。

兼容性

  • 旧布局 API 保持可用，但不能反向表达新模型的所有组合。
  • 直接修改 Label::textStyle 后，如需立即刷新尺寸，应调用 setDirty(true)。
  • Table 当前不支持纵向 Stretch。
v3.0.2 2026-04-09 Dialog / Resize / Overlay 修复版本

变更

  • Dialog 在窗口 resize、最大化、还原时只重新计算位置并保持居中，不再跟随窗口拉伸。
  • Dialog 标题改为由自身直接绘制，不再依赖单独的 Label 子控件。
  • Window::getWidth() 和 getHeight() 返回当前已生效的客户区尺寸； 待处理尺寸改用 getPendingWidth() 和 getPendingHeight()。
  • 非模态对话框覆盖区域内的底层控件不再响应鼠标事件。

修复

  • 修复直接最大化窗口时可能出现的黑背景和控件残影。
  • 修复 Dialog 在 resize、重定位与关闭过程中的背景残留。
  • 修复对话框遮挡场景下的底层控件误交互。
  • 修复 Canvas 和 TabControl 在事件被消费后仍继续向下分发的问题。
  • 修复 Table 在空数据、空表头和列数不一致输入下的边界风险。
  • 修复 Label::setText() 后尺寸与绘制范围不同步的问题。

可能不兼容

  • Dialog::setInitialization(bool) 已移除。
  • 如果旧代码将 Window::getWidth() 或 getHeight() 当作待收口尺寸使用，需要迁移到对应的 pending 尺寸接口。
v3.0.1 2026-03-17 TextBox 与事件分发修复

注意

  • 此版本变更了 TextBox::setText() 的重绘语义。 旧代码如果在调用 setText() 后手动调用 draw()， 升级后应删除相关调用，避免概率触发闪烁。

变更

  • 文本未变化时 TextBox::setText() 直接返回； 文本变化时根据窗口和图形上下文状态决定请求重绘或仅标脏。
  • TextBox 文本溢出绘制时按像素宽度截断并显示省略号，内部仍保存完整文本。

修复

  • 修复 TabControl::getActiveIndex() 在无激活页签时可能返回错误索引的问题。
  • 修复对话框打开时持续触发全量重绘的问题。
  • 修复对话框关闭后合成 WM_MOUSEMOVE 的触发时机问题。
  • Window 普通控件事件分发顺序由正序改为逆序遍历。
v3.0.0 2026-01-09 SxLog 日志系统与 Setter 语义收敛

新增

  • 新增轻量日志系统 SxLog，支持级别与 Tag 过滤、控制台和文件输出、文件滚动与双语文本选择。
  • 新增 SX_LOGD、SX_LOGI、SX_LOGW、 SX_LOGE、SX_LOGF、SX_LOG_TRACE、 SX_TRACE_SCOPE 等宏。
  • 新增 SxLog 使用示例。

变更

  • TabControl 页签切换时序调整为先关闭当前页，再打开目标页。
  • 控件 setter 语义收敛为更新状态并标脏，绘制由窗口或容器的重绘链路提交。

修复

  • 修复 TextBox::setText() 在进入事件循环前调用可能触发中断的问题。
  • 修复 TabControl 切换或关闭后 Table 新旧内容重叠的问题。

可能不兼容

  • 删除 Button 尺寸别名 API：getButtonWidth() 和 getButtonHeight()，统一使用 getWidth() 和 getHeight()。
  • setIsVisible(true) 与 setText() 等 setter 不再保证立即执行绘制。

Milestones

重要里程碑

这里保留对框架阶段影响较大的版本，便于了解 StellarX 的演进节点。
v4.0.0 引入稳定控件句柄、受控所有权和延迟结构变更事务，并完成一轮覆盖核心控件、重绘、文本与日志系统的稳定性修复。
v2.0.0 引入 Dialog 与 MessageBox，对事件分发、API 语义和内部资源管理进行重要调整。
v1.0.0 首个稳定版本，提供基础控件库、CMake 构建系统、文档示例和预编译静态库。
v0.1.0 初始项目结构与核心架构版本，包含 Control 基类、基本事件处理系统、基础示例和文档设置。
完整历史： 官网只保留当前版本、最近几个版本和关键里程碑。 更早或更细的历史记录请查看 GitHub 仓库中的 CHANGELOG。
查看完整 CHANGELOG 查看 GitHub Releases

Versioning

版本命名与兼容性说明

StellarX 按语义化版本组织发布。涉及 API 和核心行为不兼容调整时，会提升主版本号并提供迁移说明。
主版本号 用于标记明显不兼容变更，例如事件模型、控件所有权、资源管理或生命周期语义调整。
次版本号 通常用于新增控件、布局能力、示例体系、文档体系或较大范围的兼容行为改进。
修订版本号 通常用于修复缺陷、收口边界行为、提高稳定性和补充文档说明。
升级建议： 从旧版本升级前，请先阅读目标版本的“兼容性与迁移”部分， 并优先在独立分支或示例工程中完成编译、自动化测试和关键界面回归。

Next Step

继续查看

获取发布包、查看完整版本历史、阅读 API 指南或提交问题。