# StellarX API 迁移说明

本次变更包含不兼容的所有权与文本样式 API 调整。GUI 仍限定在主线程，字符集仍为 MBCS。

## Window 与 Canvas 所有权

不再公开可变的 `std::vector<std::unique_ptr<Control>>`。调用方必须保存稳定句柄，而不是保存容器迭代器或假设控件地址永久有效。

```cpp
auto button = std::make_unique<Button>(10, 10, 100, 32, "run");
const StellarX::ControlHandle handle = window.addControl(std::move(button));

Control* control = window.findControl(handle);
const bool removed = window.removeControl(handle);
```

新接口：

- `ControlHandle addControl(std::unique_ptr<Control>)`
- `bool removeControl(ControlHandle)`
- `void clearControls()`
- `Control* findControl(ControlHandle)`
- `std::vector<ControlHandle> getControlHandles() const`

已删除：

- `Window::getControls()`
- `Canvas::getControls()`
- `Canvas::clearAllControls()`

事件、绘制、tick 和按钮回调遍历期间的新增、删除与清空会延迟到最外层事务结束后提交。回调结束后不要继续使用已请求删除的裸指针。

## 字体名称

`ControlText::lpszFace` 已替换为拥有型字符串 `ControlText::faceName`。

```cpp
StellarX::ControlText style;
style.faceName = "微软雅黑";
```

不再传入临时 `c_str()` 指针。字体样式比较按字符串内容进行，复制赋值使用默认值语义。

## TabControl

页签身份改为索引，重复标题合法。

```cpp
const size_t index = tabs.addTab(std::move(button), std::move(page));
auto rejected = tabs.tryAddToPage(index, std::move(control));
if (rejected) {
    // 添加失败，调用方仍拥有控件。
}
```

替换关系：

- `add(pair<Button, Canvas>)` 改为 `addTab(button, page)`，返回页签索引。
- `add(tabText, control)` 改为 `tryAddToPage(index, control)`；文本重载只匹配第一个同名页签。
- `setActiveIndex(int)` 现在返回 `bool`，运行期非法索引返回 `false`。

空 TabControl 可预设首次激活索引；首次绘制不会访问空容器。索引超过首批页签范围时首次激活最后一个可用页签。

## 日志配置

`SxLogger::setConfig` 现在返回 `bool`：

```cpp
if (!StellarX::SxLogger::Get().setConfig(config)) {
    // 候选文件 sink 打开失败，旧配置和旧 sink 保持有效。
}
```

文件输出禁用、路径、追加模式或滚动阈值变化会同步更新 sink。滚动重命名失败时继续追加原文件，不再截断。