StellarX-kaifa/开发记录/MIGRATION.md

StellarX API 迁移说明

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

Window 与 Canvas 所有权

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

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。

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

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

TabControl

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

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：

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

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