API指南

00 / BEFORE YOU START

使用接口前，先记住四件事

这些约定贯穿整个框架，理解它们比记住单个方法更重要。

01

只包含 StellarX.h

业务代码使用公共聚合头，不直接包含 src/internal 私有头文件。

02

容器拥有控件

Window、Canvas 接管 unique_ptr，外部长期保存 ControlHandle。

03

结构变更会延迟提交

回调中可以请求增删控件，但提交前 findControl() 还查不到新增对象。

04

以公开头文件为准

本页用于快速查询；完整重载、参数和源码级说明以公开文档为准。

01 / CORE TYPES

核心类型与稳定身份

基础枚举和结构体位于 StellarX 命名空间；主要控件类仍位于全局命名空间。

ENUMS

常用枚举

类型	常用取值
`ControlShape`	`RECTANGLE`、`ROUND_RECTANGLE`、`CIRCLE`、`ELLIPSE` 及无边框变体
`ButtonMode`	`NORMAL`、`TOGGLE`、`DISABLED`
`TextBoxmode`	`INPUT_MODE`、`READONLY_MODE`、`PASSWORD_MODE`
`TabPlacement`	`Top`、`Bottom`、`Left`、`Right`
`MessageBoxType`	`OK`、`OKCancel`、`YesNo`、`YesNoCancel` 等
`FillMode`	`Solid`、`Null`、`Hatched`、`Pattern`、`DibPattern`

TEXT STYLE

ControlText

Button、Label、TextBox、Table 等控件通过它描述字体高度、名称、颜色、字重和文本装饰。

nHeight / nWidth：字体尺寸
faceName：拥有型字体名称字符串
color / nWeight：颜色与字重
bItalic / bUnderline / bStrikeOut

Label 特别说明

直接修改 textStyle 后，调用 setDirty(true) 刷新内容驱动尺寸。

STABLE IDENTITY

ControlHandle

句柄代表控件在当前进程本次运行中的稳定身份，但不证明对象仍然存活。需要访问时，先通过容器临时查询。

value == 0 表示无效句柄
可用于 removeControl()、findControl() 和 getControlHandles()
控件移除后，旧句柄仍可安全比较，查询会返回 nullptr

control_handle.cpp

auto button = std::make_unique<Button>(
    40, 40, 160, 42, "确定");

const StellarX::ControlHandle handle =
    window.addControl(std::move(button));

if (Control* control = window.findControl(handle))
{
    control->setIsVisible(false);
}

window.removeControl(handle);

02 / WINDOW

窗口、事件循环与顶层控件

Window 创建原生窗口、托管顶层控件，并在安全点统一提交消息、结构变更和重绘。

COMMON API

常用公开接口

接口	用途与返回
`Window(width, height, mode, bkColor, headline)`	创建带背景色和标题的窗口；另有更短构造重载。
`draw()` / `draw(imagePath)`	执行一次全量绘制，使用纯色或背景图。
`runEventLoop()`	进入主事件循环并返回退出码。
`addControl(unique_ptr<Control>)`	接管所有权并返回稳定 `ControlHandle`。
`removeControl(handle)` / `clearControls()`	请求删除单个或全部普通顶层控件。
`findControl(handle)`	查询已提交对象；未命中时返回 `nullptr`。
`getControlHandles()`	返回当前已提交顶层控件的句柄快照。
`setBkImage(...)` / `setBkcolor(...)` / `setHeadline(...)`	修改窗口背景与标题。
`getHwnd()` / `getWidth()` / `getHeight()`	读取原生句柄与当前客户区尺寸。

CALLBACK BOUNDARY

回调中可以请求增删控件，但不要继续使用已请求删除的裸指针。

新增句柄可以立即保存；在最外层事务提交前，findControl() 不会返回待提交对象。

03 / CONTROL

所有控件共享的基础能力

Control 是抽象基类，提供身份、当前几何、设计基线、可见性、dirty 状态和布局入口。

GEOMETRY & STATE

几何与状态

getHandle()读取稳定身份句柄
getX/Y/Width/Height()读取当前运行态矩形
getLocalX/Y/Width/Height()读取父局部设计基线
setX/Y/Width/Height(...)修改当前运行态矩形
setIsVisible(bool) / IsVisible()设置或读取可见性
setDirty(bool) / isDirty()登记或读取重绘状态
draw() / handleEvent(...)由派生控件实现

LAYOUT ENTRY

布局入口

setHorizontalAnchors(...)设置水平起止锚点
setVerticalAnchors(...)设置垂直起止锚点
setHorizontal/VerticalSizePolicy(...)Stretch 或 FixedSize
setHorizontal/VerticalAlignPolicy(...)固定尺寸时的位置策略
setHorizontal/VerticalLayoutSpec(...)直接设置完整单轴规格
getLayoutCapability()查询允许拉伸的坐标轴
commitCurrentGeometryAsDesignRect()把当前矩形提交为新设计基线

DESIGN BASELINElocalX / localY / localWidth / localHeight

父局部坐标中的设计态基线

LAYOUT SOLVER窗口与容器布局解算

resize 时按单轴策略计算

RUNTIME RECTx / y / width / height

当前绘制和命中测试矩形

04 / CONTAINERS

Canvas 与 TabControl

Canvas 管理普通子控件；TabControl 组织页签按钮和页面 Canvas。两者都遵循延迟结构变更语义。

GENERAL CONTAINER

Canvas

子控件使用父局部坐标添加，由 Canvas 映射到窗口世界坐标。

addControl(unique_ptr<Control>)接管子控件并返回句柄
removeControl(handle) / clearControls()请求删除子控件
findControl(handle)只查询已提交的直接子控件
getControlHandles()获取直接子控件句柄快照
setShape(...) / setCanvasfillMode(...)设置形状与填充
setCanvasBkColor(...) / setBorderColor(...)设置背景与边框

TABBED CONTAINER

TabControl

外部不能直接使用继承自 Canvas 的 addControl()；必须通过页签专用接口管理页面。

addTab(button, page)添加页签并返回逻辑索引
tryAddToPage(index, control)成功返回空指针，失败返还所有权
tryAddToPage(text, control)重复标题只匹配第一个页签
setActiveIndex(index)有效或重复激活返回 true
setTabPlacement(...)设置页签栏位置
indexOf(text)未命中返回 -1

tab_control.cpp

auto tabs = std::make_unique<TabControl>(20, 20, 760, 500);
auto pageButton = std::make_unique<Button>(0, 0, 120, 36, "概览");
auto page = std::make_unique<Canvas>();

const size_t pageIndex =
    tabs->addTab(std::move(pageButton), std::move(page));

auto label = std::make_unique<Label>(24, 24, "第一页内容");

if (auto rejected = tabs->tryAddToPage(pageIndex, std::move(label)))
{
    // 添加失败时，rejected 仍持有控件所有权
}

window.addControl(std::move(tabs));

事务内连续添加

addTab() 返回包含 pending 页签的逻辑索引，因此可以在同一事务里立即传给 tryAddToPage()。

05 / WIDGETS

常用界面控件

这里列出最常查询的入口与当前行为边界；完整构造重载请查看全量 API 文档。

BUTTON

Button

点击、切换和禁用状态，支持 Tooltip。

setOnClickListener(...)
setOnToggleOnListener(...)
setOnToggleOffListener(...)
setbuttonMode(...)
setButtonText(...)
enableTooltip(...)
setTooltipText(...)

Tooltip 当前不会自动避让窗口边界、上层控件或 Dialog 遮挡。

LABEL

Label

显示静态文本，尺寸由内容与字体样式驱动。

setText(...)
setTextdisap(bool)
setTextBkColor(...)
hide()
textStyle 公开字段

setText() 会刷新尺寸；直接修改字体样式后调用 setDirty(true)。

TEXTBOX

TextBox

输入、只读和密码模式，当前仍使用 EasyX InputBox。

setMode(...)
setMaxCharLen(...)
setTextBoxshape(...)
setTextBoxBorder(...)
setText(...) / getText()

最大长度按底层多字节字符串的字节数计算，不等同于 Unicode 字符数。

TABLE

Table

表头、数据行、分页显示与基础表格样式。

setHeaders(...)
setData(...)
setRowsPerPage(...)
showPageButton(...)
clearData() / resetTable()
getCurrentPage() / getTotalPages()

setData() 是追加语义；替换数据前先调用 clearData() 或 resetTable()。

06 / DIALOGS

Dialog 与 MessageBox

标准提示和确认优先使用 MessageBox；需要自定义内容和生命周期时再直接使用 Dialog。

STATIC FACTORY

StellarX::MessageBox

showModal(...)阻塞直到关闭，返回 MessageBoxResult
showAsync(...)立即返回，通过回调传出结果

非模态去重

相同标题与正文的非模态消息框不会重复打开。

CUSTOM DIALOG

Dialog

Show() / Close()显示或关闭
SetTitle/Message/Type(...)更新标题、正文与按钮类型
SetModal(...) / model()设置或查询模态状态
SetResultCallback(...)注册结果回调
addControl(...) / clearControls()管理自定义内容
recenterInHostWindow()在宿主客户区重新居中

CURRENT SEMANTICS

Dialog 在宿主窗口 resize、最大化和还原时只重新居中，不参与拉伸。

非模态 Dialog 会阻止遮挡区域内的底层控件误响应 hover、click 和 Tooltip。

07 / LAYOUT & REPAINT

单轴布局与托管重绘

v4.0.0 推荐分别配置水平轴和垂直轴；旧版 LayoutMode 与 Anchor 继续保留用于兼容。

SIZE POLICY

Stretch / FixedSize

只决定该坐标轴上的尺寸是否随父容器变化。

ALIGN POLICY

Start / End / Center / Proportional

只在固定尺寸时决定位置；Proportional 是位移策略，不是缩放策略。

CAPABILITY

LayoutCapability

描述控件是否允许在 X/Y 轴拉伸，不等同于默认布局策略。

layout.cpp

auto panel = std::make_unique<Canvas>(20, 20, 760, 500);
panel->setHorizontalAnchors(true, true);
panel->setVerticalAnchors(true, true);
panel->setHorizontalSizePolicy(StellarX::AxisSizePolicy::Stretch);
panel->setVerticalSizePolicy(StellarX::AxisSizePolicy::Stretch);

auto button = std::make_unique<Button>(620, 30, 120, 36, "Right");
button->setHorizontalAnchors(false, true);
button->setHorizontalSizePolicy(StellarX::AxisSizePolicy::FixedSize);
button->setHorizontalAlignPolicy(StellarX::AxisAlignPolicy::End);

设计基线

local* 保存父局部矩形。普通 resize 不会自动回写。

dirty 与重绘

状态变化后使用公开 setter 或 setDirty(true)，由 Window 统一提交。

能力边界

Canvas、TabControl 支持双轴 Stretch；Table 当前只支持水平 Stretch。

08 / SXLOG

日志、过滤与文件输出

SxLog 支持控制台和文件 sink、级别与 Tag 过滤、双语文本选择、文件滚动和作用域耗时记录。

LOGGER API

常用入口

接口	用途与边界
`SxLogger::Get()`	获取全局日志器单例。
`setMinLevel(...)`	设置最低输出级别。
`enableConsole(bool)`	启用或关闭控制台 sink。
`enableFile(path, append, rotateBytes)`	启用文件输出，返回文件是否成功打开。
`setTagFilter(...)` / `clearTagFilter()`	配置或清空 Tag 白名单、黑名单。
`setLanguage(...)` / `SX_T(zh, en)`	选择文本语言，不执行字符编码转换。
`getConfigCopy()` / `setConfig(...)`	读取或整体应用配置；新文件 sink 失败时保留旧配置。
`SX_LOGD/I/W/E/F` / `SX_TRACE_SCOPE`	按级别输出日志或统计作用域耗时。

sxlog.cpp

auto& log = StellarX::SxLogger::Get();
log.enableConsole(true);
log.setMinLevel(StellarX::SxLogLevel::Debug);
log.setLanguage(StellarX::SxLogLanguage::ZhCN);

if (!log.enableFile("stellarx.log", true, 1024 * 1024))
{
    SX_LOGE("Init") << "日志文件打开失败";
}

SX_LOGI("Demo") << SX_T("程序启动", "program started");

MACRO SAFETY

SxLog 宏采用 if/else 短路形式。

不要将日志宏裸放在没有大括号的单行 if/else 分支中，以免出现 dangling-else 绑定歧义。

09 / BOUNDARIES & MIGRATION

当前限制与迁移提示

这些内容决定了哪些能力可以依赖，以及从 v3.1.0 升级时必须修改哪些调用。

NOT IN v4.0.0

当前限制

尚未提供完整焦点系统和键盘事件系统。
TextBox 自绘输入体系尚未重写。
Table 仍以整表正确性优先，没有内部局部重绘和纵向 Stretch。
TabControl 内部布局应用路径尚未完全收口。
Tooltip 不会自动避让边界、上层控件或 Dialog。
尚未提供全局字体自动缩放。

FROM v3.1.0

迁移检查

getControls() → 句柄式 add/remove/clear/find/handles 接口。
clearAllControls() → clearControls()。
ControlText::lpszFace → 拥有型字符串 faceName。
TabControl::add(pair) → addTab() 与 tryAddToPage()。
setActiveIndex() 与 SxLogger::setConfig() 现在返回 bool。
回调中请求删除后，不要继续使用原始控件指针。