Codex
75 lines
2.4 KiB
Markdown
75 lines
2.4 KiB
Markdown
# 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。滚动重命名失败时继续追加原文件，不再截断。
|