# 更新日志

StellarX 项目所有显著的变化都将被记录在这个文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

[English document](CHANGELOG.en.md)

## [v2.3.1] - 2025 - 11 - 30

## 🙏 鸣谢

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

### ✨ 新增

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

### ⚙️ 变更

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

### ✅ 修复

- **容器嵌套时子控件坐标转化：**`Canvas`重写了基类的`setX/Y`方法，在容器全局坐标发生变化时同步修改子控件的全局坐标，防止在容器嵌套时，容器的相对坐标被子控件当成全局坐标处理
- **纯色背景窗口标题不生效：**在`Window`的`draw()`方法中强制设置窗口标题，以防止，创建窗口时传递的窗口标题不生效
- **选项卡控件页签打开时动态改变坐标背景残留：**在`TabControl`重写的`setX/Y`方法中，当选项卡的坐标发生变化时强制让所有页签以及页和子控件丢一次快照，防止，在修改坐标后因，快照恢复顺序引起的选项卡激活页残留
- **Table动态改变坐标页码标签和翻页按钮错乱：**在`Table`控件的`setX/Y`中重置`isNeedButtonAndPageNum`状态为真，在绘制时重新计算翻页按钮和页码标签的位置以保持在表格正下方居中位置显示

## [v2.3.0] - 2025 - 11 - 18

### ✨ 新增

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

### ⚙️ 变更

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

### ✅ 修复

- **模态对话框拉伸修复**：解决了模态对话框弹出时，窗口拉伸无法让底层控件按照锚点更新尺寸和位置的问题；同时避免对话框反复重绘导致残影。
- **绘制顺序错乱修复**：解决窗口拉伸时偶发的绘制顺序紊乱、控件残影和边框闪烁问题，确保控件按添加顺序依次绘制。
- **稳定性修复**：修正某些情况下窗口尺寸突变导致的异常帧；解决表格和对话框背景快照在边界条件下未及时更新的问题。

## [v2.2.2] - 2025 - 11- 08

### ⚙️ 变更

- Canvas容器坐标传递方式改变，子控件坐标由原来的传递全局坐标改为传递相对坐标（坐标原点为容器的左上角坐标可通过getX/Y接口获得）可以设置子控件坐标为负值
- examples\register-viewer下的案例已同步修改为最新，同步容器子控件为相对坐标

### ✅ 修复

- 修复窗口拉伸（左/上边）时的抖动/弹回与闪烁
  - `WM_SIZING` 仅做最小尺寸夹紧；`WM_GETMINMAXINFO` 设置窗口级最小轨迹
  - 拖拽期冻结重绘，松手统一收口；`WM_SIZE` 只记录尺寸不抢绘制
  - 禁用 `WM_ERASEBKGND` 擦背景并移除 `CS_HREDRAW/CS_VREDRAW`，减少闪烁
- 对话框的相关问题
  - 对话框关闭后概率出现功能按钮残留
  - 模态对话框触发时，窗口拉伸无法重绘或背景错乱
- 表格控件在窗口变化时其翻页按钮和页码标签背景快照更新不及时的问题

## [v2.2.1] - 2025 - 11 - 4

==此版本为v2.2.0的修复版本==

### ✅ 修复

- `TabControl`类重写了基类的`setDirty`方法保证页签+页列表同步更新

  状态

- `Canvas`容器和特殊容器`TabControl`以及对话框`Dialog`重写`requestRepaint`方法，控件向上冒泡时传递父指针，请求重绘时只向上到父一级，不再传递到根。并且不再重绘整个父容器，而是由父容器重绘标脏的子控件，避免了频繁真个容器重绘导致的频闪

- `Dialog`中重写了`saveBackground`和`restBackground`方法，保证对话框关闭后不会有边框残留

### ⚙️ 变更

- 彻底禁用`Control`的移动构造`Control(const Control&) = delete;`
  `Control& operator=(const Control&) = delete;`
  `Control(Control&&) = delete;`
  `Control& operator=(Control&&) = delete;`

## [v2.2.0] - 2025-11-02

**重点**：正式引入选项卡控件(TabControl)，增强控件显隐与布局响应能力，并完善文本样式机制；修复若干UI细节问题以提升稳定性。

### ✨ 新增

- **选项卡容器控件 TabControl**：新增 `TabControl` 类，实现多页面选项卡界面。支持页签栏在 **上/下/左/右** 四种位置排列，可通过 `TabControl::setTabPlacement(...)` 设置。提供 `TabControl::add(std::pair<std::unique_ptr<Button>, std::unique_ptr<Canvas>>&&)` 接口，一次性添加“页签按钮+页面内容”对，并自动管理切换显示。各页内容区域由 `Canvas` 承载，点击不同页签(Button，TOGGLE模式)将切换显示对应页面**【见 API】**。TabControl 在窗口大小变化时可自动调整页签布局，并使用背景快照避免透明主题下的叠影问题。
- **控件显隐控制**：所有控件现支持运行时**显示/隐藏**切换。基类新增方法 `Control::setIsVisible(bool)` 控制自身可见性，隐藏后控件不参与绘制和事件。容器控件(`Canvas`)重写该方法，实现**级联隐藏**：隐藏容器将自动隐藏其中所有子控件，再次显示时子控件也随之恢复。这使一组界面元素的显隐切换更加方便。
- **窗口尺寸变化响应**：引入 `Control::onWindowResize()` 虚函数，当父窗口尺寸改变时调用。各控件可通过实现此函数响应窗口大小调整，例如重置背景缓存、调整布局等。`Canvas` 已实现该函数，会在窗口变化时**递归通知子控件**调用 `onWindowResize()`，确保嵌套布局能正确更新。此改进解决了之前窗口拉伸后子控件可能位置错位或背景异常的问题。
- **Label 文本样式结构**：`Label` 控件现在使用统一的 `ControlText` 样式结构管理字体和颜色。可通过访问公有成员 `Label::textStyle` 设置字体名称、大小、颜色、下划线等属性，实现**完整文本样式定制**（替代原先的 setTextColor 接口）。这使 Label 在展示文本时支持更丰富的格式。
- **Dialog 防重复机制**：`Window` 新增内部检查函数，**防止重复弹出相同内容的对话框**。在使用 `MessageBox::showAsync` 非模态弹窗时，框架会判断是否已有相同标题和消息的对话框未关闭，若是则避免再次创建。此机制杜绝了短时间内弹出多个相同提示的情况。

### ⚙️ 变更

- **文本颜色接口调整**：`Label` 移除了过时的 `setTextColor` 方法，改为通过公有的 `textStyle.color` 设置文字颜色。如需改变 Label 文本颜色，请直接修改 `label.textStyle.color` 并重绘。此改动提升了文本属性管理的一致性，但可能对旧版代码不兼容，需要做相应替换。
- **Tooltip 样式与切换**：`Button` 的悬停提示 (Tooltip) 接口调整为支持更多自定义。`Button::setTooltipStyle` 现在可灵活设置提示文字颜色、背景色及透明模式；新增 `setTooltipTextsForToggle(onText, offText)` 用于切换按钮在 **ON/OFF** 两种状态下显示不同的提示文字。原有 Tooltip 文案设置接口仍兼容，但内部实现优化，修正了先前切换按钮提示文字不更新的问题。
- **控件坐标系与布局**：控件现在同时维护**全局坐标**和**局部坐标**。`Control` 新增成员（如 `getLocalX()/getLocalY()` 等）用于获取控件相对父容器的位置，以及 `parent` 指针指向父容器。这一改进使得嵌套容器布局计算更加便捷和准确。在绝对布局场景下，控件的全局坐标会在添加进容器时自动转换为本地坐标保存。开发者需要注意，新版中移动控件或调整尺寸应优先使用控件自带的 setter，以确保内部坐标同步更新。
- **默认窗口调整**：窗口拉伸功能从实验转为默认支持。框架始终为主窗口启用了可调整大小的样式（`WS_THICKFRAME|WS_MAXIMIZEBOX|...`），不再需要调用独立的方法启用。这一变更简化了使用，同时意味着创建的窗口默认可以被用户拖拽拉伸。对于不希望窗口缩放的场景，可在创建窗口时通过传递特定模式标志来禁止。

### ✅ 修复

- **切换按钮 Tooltip 更新**：修正了切换模式按钮在状态改变时悬停提示未及时更新的问题。现在使用 `setTooltipTextsForToggle` 设置不同提示后，按钮在 **ON/OFF** 状态切换时悬停提示文字会正确显示对应内容。
- **控件背景残影与坐标同步**：解决了某些情况下窗口或容器尺寸变化后控件背景未及时刷新、位置计算偏差的缺陷。利用 `onWindowResize` 统一丢弃并更新背景快照，避免了拉伸窗口时可能出现的控件背景残影和错位现象，界面稳定性提升。
- **`Control`类背景快照内存泄漏**：在析构函数里调用了`discardBackground`释放并恢复背景快照，避免了上一版本未释放`*saveBkImage`造成的内存泄漏
- **重复对话框弹出**：修复了快速重复调用非模态消息框可能出现多个相同对话框的问题。新增的去重判断保证相同内容的非模态对话框同一时间只会存在一个，避免用户界面受到干扰。
- **其他**：优化了控件绘制刷新策略，减少某些场景下的不必要重绘，提升运行效率；修正少量内存管理细节以消除潜在泄漏。上述改进进一步提高了框架的性能与可靠性。

## [v2.1.0] - 2025-10-27

**重点**：窗口可拉伸/最大化补强（EasyX + Win32）、布局管理器（HBox/VBox 第一阶段）、选项卡控件雏形；系统性修复黑边、最大化残影、频闪与“控件需交互才出现”等历史问题。并统一了**背景快照/恢复**、**按钮单行截断**、**Tooltip** 的机制。

### ✨ 新增

- **中英文双语 API文档**
  - 文档详细介绍了每个类，以及API描述、功能和需要注意的地方，详细介绍了每个控件

- **窗口拉伸 / 最大化补强（在 EasyX 基础上用 Win32 加固）**
  - 新增 `Window::enableResize(bool enable, int minW, int minH)`；运行时开关可拉伸并设置最小跟踪尺寸。
  - 子类化窗口过程：处理 `WM_GETMINMAXINFO / WM_SIZE / WM_EXITSIZEMOVE / WM_ERASEBKGND / WM_PAINT`，并启用 `WS_THICKFRAME | WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_CLIPCHILDREN | WS_CLIPSIBLINGS`，解决 EasyX 窗口原生不可拉伸问题。
  - **整窗背景绘制**：在 `WM_PAINT` 用 GDI 直写客户区（纯色/图片均支持），彻底消除黑边与最大化残影。
  - **一次性重绘**：合并连续 `WM_SIZE`，使用 `pendingW/H + needResizeDirty` 在主循环尾部统一置脏重绘，避免死循环与抖动。
- **布局管理器（第一阶段）**
  - 在 `Canvas` 引入布局元数据：`LayoutKind::{Absolute, HBox, VBox, Grid(预留), Flow(预留), Stack(预留)}` 与 `LayoutParams`（`margin{L,R,T,B}`、`fixedW/fixedH(-1=沿用)`、`weight`、`Align{Start,Center,End,Stretch}`）。
  - 实装 **HBox/VBox** 自动布局（容器内部自动排布；容器本身仍绝对定位，可嵌套）。
- **选项卡（Tabs）控件雏形**
  - 页签条与页面容器解耦；多页签切换；为透明主题提供**背景快照**避免叠影。
- **按钮文本单行截断（MBCS：中/英分治）**
  - 基于像素宽度阈值的 `...` 截断，避免半字节/半汉字。
- **悬停提示（Tooltip）**
  - 以 `Label` 为载体，支持延时出现、自动隐藏、自定义文案（默认回退到按钮文本）；使用控件级**背景快照/恢复**。

### 🔧 变更

- **Window 渲染路径**
  - 弱化“离屏 frame→整屏贴图”的依赖；在 `WM_PAINT` 走 **GDI 整窗背景 + EasyX 批量绘制**（`BeginBatchDraw/EndBatchDraw + FlushBatchDraw`）以抑制频闪。
  - 尺寸变化仅重建 `zoomBackground`（图片背景的缩放副本），显示延后到下一帧。
- **Control 基类**
  - 标准化 **captureBackground/restoreBackground**；统一透明/叠放控件行为。
  - 统一 `dirty` 语义：容器自身脏才重画背景，但**子控件每帧评估并按需绘制**，不再出现“容器不脏→子控件不画”的空窗。
- **Table**
  - 透明模式下，分页按钮与页码标签跟随表格的文本/填充风格，避免风格漂移。
  - **分页度量与整体居中**重做：可用宽度含表头；“上一页/下一页+页码”作为**一个块**水平居中。
  - 修复**背景快照区域**未计入表头导致恢复失败的问题。
- **事件循环**
  - 合并 `WM_SIZE` 到循环尾统一处理，降低输入延迟与重绘风暴。

### ✅ 修复

- **黑边 / 最大化残影 / 频闪**：`WM_ERASEBKGND` 返回 1 禁止系统擦背景；`WM_PAINT` 全面覆盖；清空裁剪区防止旧帧残留。
- **容器不画、控件需交互后才出现**：首帧与输入后触发**全树置脏**；子控件在容器未脏时也能正常绘制。
- **Table 翻页重叠与透明叠影**：修正快照区域、重算坐标并即时恢复+重绘。

### ⚠️ 可能不兼容

- 若外部代码直接访问 `Window` 私有成员（如 `dialogs`），请改用 `getControls()` / `getdialogs()`。
- `Table` 的分页与表头度量变化可能影响外部硬编码偏移；需要对齐新公式。
- 自定义控件若未遵循绘制前 `SetWorkingImage(nullptr)` 的约定，请自查。

### 📌 升级指引

1. **窗口背景**：将手工 `cleardevice()+putimage` 迁移到 `WM_PAINT` 的**整窗覆盖**流程。
2. **透明控件**：首绘前 `captureBackground()`，隐藏/覆盖时 `restoreBackground()`。
3. **布局**：容器设 `layout.kind = HBox/VBox`；子项用 `LayoutParams`（`margin/fixed/weight/align`）。
4. **按钮截断**：保持单次截断，避免重复 `...`。
5. **表格**：移除自绘分页，使用内置导航。

## [v2.0.1] - 2025 - 10 - 03

### 新增

- 新增示例：基于 StellarX 实现的 32 位寄存器查看工具（支持位取反、左移、右移，十六进制/十进制带符号/无符号切换，分组二进制显示）。
  - 示例路径：`examples/register-viewer/`
- `TextBox`新增`setText`API，可在外部设置文本框内容
- `TextBox::setText`API修改：在设置文本后立即调用`draw`方法重绘
- `Button`新增`setButtonClick`API,允许通过外部函数修改按钮的点击状态，并执行相应的回调函数
- ==所有文档更新对应英文版本==

## [v2.0.0] - 2025-09-21

### 概述
v2.0.0 为一次重大升级（major release）。本次发布新增对话框与消息框工厂（Dialog / MessageBox），并对事件分发、API语义与内部资源管理做了若干重要修复和改进。

部分 API/行为发生不向后兼容的变化（breaking changes）。

### 新增
- **对话框系统**:
  - 新增 `Dialog` 类，继承自 `Canvas`，用于构建模态与非模态对话框
  - 新增 `MessageBox` 工厂类，提供 `ShowModal`（同步阻塞）与 `ShowAsync`（异步回调）两种便捷API
  - 支持六种标准消息框类型：`OK`, `OKCancel`, `YesNo`, `YesNoCancel`, `RetryCancel`, `AbortRetryIgnore`
  - 自动处理对话框布局、背景保存与恢复、事件传播和生命周期管理

- **事件系统增强**:
  - 所有控件的 `handleEvent` 方法现在返回 `bool` 类型，表示是否消费了事件
  - 引入事件消费机制，支持更精细的事件传播控制
  - Window 类的事件循环现在优先处理对话框事件

- **控件状态管理**:
  - Control 基类新增 `dirty` 标志和 `setDirty()` 方法，统一管理重绘状态
  - 所有控件现在都实现了 `IsVisible()` 和 `model()` 方法

- **API 增强**:
  - Button 类新增 `setButtonFalseColor()` 方法
  - TextBox 类的 `setMaxCharLen()` 现在接受 `size_t` 类型参数
  - Window 类新增对话框管理方法和去重检测机制

### 重大变更（Breaking Changes）
- **API 签名变更**:
  - 所有控件的 `handleEvent(const ExMessage& msg)` 方法从返回 `void` 改为返回 `bool`
  - Control 基类新增纯虚函数 `IsVisible() const` 和 `model() const`，所有派生类必须实现

- **资源管理变更**:
  - Control 基类的样式保存从栈对象改为堆对象，使用指针管理
  - 增强了资源释放的安全性，所有资源都在析构函数中正确释放

- **事件处理逻辑**:
  - Window 的 `runEventLoop()` 方法完全重写，现在优先处理对话框事件
  - 引入了事件消费机制，事件被消费后不会继续传播

### 修复（Fixed）
- **内存管理**:
  - 修复 `Button::setFillIma()` 的内存泄漏问题
  - 修复 Control 基类析构函数中的资源释放问题
  - 修复 Dialog 类背景图像资源管理问题

- **布局与渲染**:
  - 修复 `Table` 组件的分页计算、列宽和行高越界问题
  - 修复 `Table` 中 `pX` 坐标累加错误导致的布局错乱
  - 修复 `Canvas::draw()` 中导致子控件不被绘制的 dirty 判定问题
  - 修复 `TextBox::draw()` 和 `restoreStyle()` 的不对称调用问题

- **事件处理**:
  - 修复窗口事件分发逻辑，确保对话框/顶层控件优先处理事件
  - 修复鼠标移出按钮区域时状态更新不及时的问题
  - 修复非模态对话框事件处理中的竞争条件

- **其他问题**:
  - 修复文本测量和渲染中的潜在错误
  - 修复对话框关闭后背景恢复不完全的问题
  - 修复多对话框场景下的 z-order 管理问题

### 改进（Changed）
- **代码质量**:
  - 重构了大量内部 API，增强异常安全性与可维护性
  - 使用智能指针和现代 C++ 特性替代裸 new/delete
  - 统一了代码风格和命名约定

- **性能优化**:
  - 优化了事件处理流程，减少不必要的重绘
  - 改进了对话框背景保存和恢复机制
  - 减少了内存分配和拷贝操作

- **文档与示例**:
  - 为所有新增功能添加了详细的使用示例
  - 完善了代码注释和 API 文档
  - 更新了 README 和 CHANGELOG 反映最新变化

## [1.1.0] - 2025-09-08

### 新增
- **Window 类 API 增强**:
  - 添加了完整的获取器(getter)方法集，提高类的封装性和可用性
  - `getHwnd()` - 获取窗口句柄，便于与原生 Windows API 集成
  - `getWidth()` - 获取窗口宽度
  - `getHeight()` - 获取窗口高度
  - `getHeadline()` - 获取窗口标题
  - `getBkcolor()` - 获取窗口背景颜色
  - `getBkImage()` - 获取窗口背景图片指针
  - `getControls()` - 获取控件管理容器的引用，允许迭代和操作已添加的控件

### 改进
- **API 一致性**: 为所有重要属性提供了对称的设置器(setter)和获取器(getter)方法
- **代码文档**: 进一步完善了类注释，使其更加清晰和专业

## [1.0.0] - 2025-09-08

### 发布摘要
首个稳定版本 (Stable Release)

### 新增

- StellarX 框架的第一个稳定版本
- 完整的控件库：按钮、标签、文本框、画布、表格和窗口
- 基于 CMake 的构建系统
- 详细的文档和示例代码
- **明确声明：本框架专为 Windows 平台设计**

### Released
-   **首次发布预编译的二进制库文件**，方便用户快速集成，无需从源码编译。
-   提供的发布包包括：
    -   `StellarX-v1.0.0-x64-Windows-msvc-x64.zip`
        -   **编译环境**: Visual Studio 2022 (MSVC v143)
        -   **架构**: x64 (64位)
        -   **运行时库**: `/MD` 
        -   **构建模式**: `Release | Debug`
        -   **内容**: 包含所有必要的头文件(`include/`)和静态库文件(``lib/StellarX-Debug.lib StellarX-Release.lib`)

### 核心特性
- 模块化设计，遵循 SOLID 原则
- 统一的控件接口（draw() 和 handleEvent()）
- 支持多种控件形状和样式
- 自定义事件处理回调
- 轻量级设计，无外部依赖

## [0.1.0] - 2025-08-15
### 新增
- 初始项目结构和核心架构
- Control 基类和基本事件处理系统
- 基础示例和文档设置