API Guide

StellarX API 指南

按模块查询 StellarX 的常用公开接口：窗口、容器、控件、表格、页签、对话框、日志系统与布局接口。

本页按 StellarX v4.0.0 的常用公开接口整理，不替代完整 API 文档。 完整参数、行为边界和实现细节以当前公开头文件与 GitHub API 文档为准。

快速索引 快速开始 GitHub 仓库

Public API Map

主要模块

Core Types句柄、枚举、文本样式、布局结构 Window窗口、事件循环、顶层控件管理 Control控件基类、状态与布局入口 ContainersCanvas / TabControl WidgetsButton / Label / TextBox / Table DialogDialog / MessageBox Layout单轴策略、设计基线、托管重绘 SxLog日志、Tag、文件输出、双语文本

Full Reference

完整 API 文档

当前页面用于快速查询常用公开接口、最小示例和重要使用边界。 如需查看完整类定义、方法参数和源码级说明，请前往 GitHub 中的 API 文档。
查看完整 API 文档
01

业务代码只包含 StellarX.h

普通用户代码建议统一使用 #include "StellarX.h"。 不要直接包含 src/internal 中的框架私有头文件。

02

容器拥有控件生命周期

Window 和 Canvas 通过 std::unique_ptr 接管控件， 外部使用 ControlHandle 查询或请求删除，不要长期保存控件裸指针。

03

注意命名空间边界

Window、Button、Canvas 等主要控件类位于全局命名空间； 核心枚举、结构体、MessageBox 和 SxLog 位于 StellarX 命名空间。

04

部分接口保留历史命名

例如 setbuttonMode、setCanvasfillMode、 setTextBoxshape、setTextdisap，调用时应保持源码中的大小写。

Index

API 快速索引

先按模块定位，再查看常用方法、所有权规则和最小示例。
Core 核心类型 ControlHandle、枚举、文本样式、布局结构 Window 窗口 创建窗口、事件循环、句柄式控件管理 Control 控件基类 位置尺寸、可见性、dirty、布局入口 Container 容器控件 Canvas、TabControl、延迟结构变更 Widgets 常用控件 Button、Label、TextBox、Table Dialog 对话框 Dialog、MessageBox、模态与非模态 Layout 布局与重绘 锚点、单轴策略、dirty、托管重绘 Log SxLog 日志 级别、Tag、文件输出、SX_T

Core Types

核心类型与枚举

核心类型集中定义在 StellarX 命名空间中，普通用户包含 StellarX.h 即可使用。

常用枚举

类型 常用取值
StellarX::ControlShape RECTANGLE、B_RECTANGLE、ROUND_RECTANGLE、B_ROUND_RECTANGLE、CIRCLE、B_CIRCLE、ELLIPSE、B_ELLIPSE
StellarX::ButtonMode NORMAL、TOGGLE、DISABLED
StellarX::TextBoxmode INPUT_MODE、READONLY_MODE、PASSWORD_MODE
StellarX::FillMode Solid、Null、Hatched、Pattern、DibPattern
StellarX::FillStyle Horizontal、Vertical、FDiagonal、BDiagonal、Cross、DiagCross
StellarX::LineStyle Solid、Dash、Dot、DashDot、DashDotDot、Null
StellarX::TabPlacement Top、Bottom、Left、Right
StellarX::MessageBoxType OK、OKCancel、YesNo、YesNoCancel、RetryCancel、AbortRetryIgnore
StellarX::MessageBoxResult OK、Cancel、Yes、No、Abort、Retry、Ignore

稳定身份：ControlHandle

ControlHandle 表示控件在当前进程本次运行中的稳定身份， 用于后续查询和删除控件，不暴露容器内部的 unique_ptr。

handle.value 句柄原始值；值为 0 时表示无效句柄。
if (handle) 检查句柄值是否有效。
operator== / operator!= 比较两个句柄是否表示同一控件身份。
ControlHandle 
auto button = std::make_unique<Button>(40, 40, 160, 42, "确定");

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

if (auto* control = win.findControl(handle))
{
    control->setDirty(true);
}
边界： 句柄只表示身份，不保证对象仍然存活。控件被删除后， findControl() 会返回 nullptr。

文本样式：ControlText

多个控件公开了 textStyle 字段，可设置字体高度、字体名称、颜色、字重、斜体、下划线和删除线。 v4.0.0 使用拥有型字符串 faceName 保存字体名称。

ControlText 
auto label = std::make_unique<Label>(40, 40, "标题");

label->textStyle.nHeight = 28;
label->textStyle.faceName = "微软雅黑";
label->textStyle.color = RGB(37, 99, 235);
label->textStyle.nWeight = 700;

label->setDirty(true);
注意： Label 的尺寸由文本和字体样式驱动。直接修改 textStyle 后， 建议调用 setDirty(true) 重新计算并刷新内容。

Window

Window：窗口与事件循环

Window 是顶层窗口容器，负责创建窗口、绘制背景、托管顶层控件、分发事件和统一提交重绘。

构造、绘制与事件循环

接口 说明
Window(int width, int height, int mode) 创建基础窗口。
Window(int width, int height, int mode, COLORREF bkcloc) 创建指定背景色的窗口。
Window(int width, int height, int mode, COLORREF bkcloc, std::string headline) 创建带标题和背景色的窗口。
draw() / draw(std::string pImgFile) 执行一次全量绘制，可使用纯色背景或背景图。
runEventLoop() 进入主事件循环，处理消息、事件分发、tick、结构变更和统一重绘。
setBkImage(...) / setBkcolor(...) / setHeadline(...) 设置背景图、背景色或窗口标题。

顶层控件管理

接口 说明
addControl(std::unique_ptr<Control>) 接管控件所有权并返回稳定 ControlHandle。
removeControl(ControlHandle) 按句柄请求删除控件；命中时返回 true。
clearControls() 请求清空所有普通顶层控件。
findControl(ControlHandle) 查询当前已经提交的控件，未命中时返回 nullptr。
getControlHandles() 返回当前已提交顶层控件的句柄快照。

最小窗口示例

main.cpp 
#include "StellarX.h"

int main()
{
    Window win(1300, 800, NULL, RGB(255, 255, 0), "欢迎使用 StellarX 星垣-GUI");

    win.draw();

    return win.runEventLoop();
}

回调中的结构变更

v4.0.0 允许在事件、绘制、tick 和按钮回调期间请求添加、删除或清空控件。 这些操作会进入待提交队列，在最外层结构变更事务结束后的安全点统一提交。

注意： 回调中请求删除控件后，不要继续访问该控件。回调中新增控件时可以立即保存返回句柄， 但在事务提交前，findControl() 还不能查到该对象。
常用访问器 getHwnd()、getWidth()、getHeight()、 getHeadline()、getBkcolor()、getBkImage()
对话框协作 addDialog(...) 和 hasNonModalDialogWithCaption(...) 主要供 Dialog 与 MessageBox 工厂使用。
框架级接口 requestManagedRepaint(...)、flushManagedRepaint()、 beginMutationScope()、endMutationScope() 和 requestFullSceneRedraw() 主要服务框架内部协作。

Control

Control：所有控件的基础接口

Control 是抽象基类，不能直接实例化。它提供身份、位置、尺寸、可见性、dirty 标记和布局相关入口。

通用几何与状态接口

接口 说明
getHandle() 获取当前控件的稳定身份句柄。
getX() / getY() / getWidth() / getHeight() 获取当前运行态位置与尺寸。
getRight() / getBottom() 获取当前运行态右边界和下边界。
getLocalX() / getLocalY() / getLocalWidth() / getLocalHeight() 获取设计基线中的父局部位置与尺寸。
setX(...) / setY(...) / setWidth(...) / setHeight(...) 修改控件当前运行态矩形。
setIsVisible(bool) / IsVisible() 设置或查询控件可见性。
setDirty(bool) / isDirty() 设置或查询控件是否需要重绘。
getId() 获取控件内部 id。
draw() / handleEvent(...) 由具体控件实现的绘制和事件处理接口。

布局相关入口

接口 说明
setLayoutMode(StellarX::LayoutMode) 设置旧版兼容布局模式。
setAnchor(StellarX::Anchor, StellarX::Anchor) 旧版双锚点入口，会映射到单轴布局规格。
setHorizontalAnchors(bool left, bool right) 设置水平轴的起边和终边锚点。
setVerticalAnchors(bool top, bool bottom) 设置垂直轴的起边和终边锚点。
setHorizontalSizePolicy(...) / setVerticalSizePolicy(...) 设置单轴尺寸策略：Stretch 或 FixedSize。
setHorizontalAlignPolicy(...) / setVerticalAlignPolicy(...) 设置固定尺寸时的单轴位置策略。
setHorizontalLayoutSpec(...) / setVerticalLayoutSpec(...) 直接设置完整单轴布局规格。
getLayoutCapability() 查询控件允许在哪些轴上使用 Stretch。
commitCurrentGeometryAsDesignRect() 把当前运行态矩形提交为新的设计基线。

Containers

Canvas 与 TabControl

Canvas 管理普通子控件；TabControl 管理页签按钮和页面 Canvas。两者都会参与 v4.0.0 的延迟结构变更事务。

Canvas

Canvas 是通用容器控件，支持背景、边框、形状、填充模式、父局部坐标映射和子控件托管。

Canvas() / Canvas(int x, int y, int width, int height) 创建空容器。
addControl(std::unique_ptr<Control>) 添加子控件并返回稳定句柄，Canvas 接管生命周期。
removeControl(ControlHandle) 按句柄请求删除子控件。
clearControls() 请求清空全部子控件。
findControl(ControlHandle) 查找当前已经提交的直接子控件。
getControlHandles() 获取当前已提交直接子控件的句柄快照。
setShape(...) / setCanvasfillMode(...) 设置容器形状和填充模式。
setCanvasBkColor(...) / setBorderColor(...) 设置背景色和边框颜色。
setCanvasLineStyle(...) / setLinewidth(...) 设置边框线型和线宽。

TabControl

TabControl 继承 Canvas，但外部不能直接使用 Canvas 的 addControl()。 应通过 addTab() 和 tryAddToPage() 管理页签与页面内容。

TabControl() / TabControl(int x, int y, int width, int height) 创建空页签控件。
addTab(std::unique_ptr<Button>, std::unique_ptr<Canvas>) 添加页签按钮和页面组合，返回页签索引；参数为空时返回 size_t(-1)。
tryAddToPage(size_t, std::unique_ptr<Control>) 按索引添加页面控件；成功返回空指针，失败时返还控件所有权。
tryAddToPage(std::string, std::unique_ptr<Control>) 按页签标题添加控件；重复标题只匹配第一个页签。
setTabPlacement(...) 设置页签位置：Top、Bottom、Left 或 Right。
setTabBarHeight(...) 设置页签栏高度；左右排列时作为页签栏宽度。
getActiveIndex() 获取当前激活索引；没有激活页时返回 -1。
setActiveIndex(int) 设置激活页签并返回是否成功。
count() / indexOf(...) 获取页签数量或按标题查找第一个匹配索引。
事务边界： Canvas 和 TabControl 在事件、绘制或 tick 期间收到的结构修改会延迟提交。 addTab() 返回的逻辑索引可以立即传给 tryAddToPage()， 即使该页签此时仍在待提交队列中。
Canvas example 
#include "StellarX.h"
#include <memory>
#include <utility>

int main()
{
    Window win(900, 600, NULL, RGB(246, 248, 251), "Canvas Demo");

    auto panel = std::make_unique<Canvas>(40, 40, 360, 220);
    panel->setCanvasBkColor(RGB(255, 255, 255));
    panel->setBorderColor(RGB(37, 99, 235));

    auto title = std::make_unique<Label>(24, 24, "Canvas 子控件");
    title->textStyle.nHeight = 24;
    title->textStyle.color = RGB(37, 99, 235);
    title->setDirty(true);

    panel->addControl(std::move(title));
    win.addControl(std::move(panel));

    win.draw();

    return win.runEventLoop();
}
TabControl example 
auto tabs = std::make_unique<TabControl>(40, 40, 600, 360);

auto tabButton = std::make_unique<Button>(0, 0, 120, 36, "常规");
auto page = std::make_unique<Canvas>();

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

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

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

tabs->setActiveIndex(static_cast<int>(pageIndex));
win.addControl(std::move(tabs));

Widgets

常用控件 API

这里列出 Button、Label、TextBox、Table 的常用公开接口和使用注意事项。

Button：按钮控件

用于点击、切换状态、禁用状态、Tooltip 和视觉样式设置。
类别 接口
构造 Button(x, y, width, height, text, mode, shape)，也支持自定义默认色、点击色和悬停色的重载。
事件 setOnClickListener(...)、setOnToggleOnListener(...)、setOnToggleOffListener(...)
状态 setbuttonMode(...)、setButtonClick(...)、isClicked()
文本 setButtonText(...)、getButtonText()、getButtonText_c()、getButtonTextStyle()、公开字段 textStyle
形状与填充 setButtonShape(...)、setROUND_RECTANGLEwidth(...)、setROUND_RECTANGLEheight(...)、setFillMode(...)、setFillIma(...)
颜色 setButtonBorder(...)、setButtonFalseColor(...)、getButtonBorder()、getButtonTextColor()
Tooltip enableTooltip(...)、setTooltipDelay(...)、setTooltipFollowCursor(...)、setTooltipOffset(...)、setTooltipStyle(...)、setTooltipText(...)、setTooltipTextsForToggle(...)
button_demo.cpp 
#include "StellarX.h"
#include <memory>
#include <utility>

int main()
{
    Window win(900, 600, NULL, RGB(246, 248, 251), "Button Demo");

    auto button = std::make_unique<Button>(60, 60, 180, 44, "点击测试");

    button->setOnClickListener([&win]()
    {
        StellarX::MessageBox::showAsync(win, "按钮事件已经触发。", "StellarX");
    });

    button->enableTooltip(true);
    button->setTooltipText("点击按钮触发回调");

    win.addControl(std::move(button));

    win.draw();

    return win.runEventLoop();
}

Label：文本标签

用于显示静态文本，支持透明背景、背景色和文本样式。

常用接口

  • Label()
  • Label(int x, int y, std::string text, COLORREF textcolor, COLORREF bkColor)
  • setText(...)
  • setTextdisap(bool)
  • setTextBkColor(...)
  • hide()
  • 公开字段：textStyle

使用提示

Label 是内容驱动尺寸控件。调用 setText(...) 会刷新内容尺寸； 直接修改 textStyle 后建议调用 setDirty(true)。

TextBox：文本框

用于输入、只读显示和密码输入。当前版本内部仍使用 EasyX InputBox。
TextBox(int x, int y, int width, int height, std::string text, StellarX::TextBoxmode mode, StellarX::ControlShape shape) 创建文本框。
setMode(...) 设置输入、只读或密码模式。
setMaxCharLen(size_t) 设置最大长度；当前按多字节 std::string 的字节长度限制。
setTextBoxshape(...) 设置形状；当前主要支持矩形与圆角矩形。
setTextBoxBorder(...) / setTextBoxBk(...) 设置边框色和背景色。
setText(...) / getText() 设置或读取文本。
textStyle 公开文本样式字段。

Table：表格控件

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

常用写入接口

  • Table(int x, int y)
  • setHeaders(std::initializer_list<std::string>)
  • setData(std::vector<std::string>)
  • setData(std::initializer_list<std::vector<std::string>>)
  • setRowsPerPage(int)
  • showPageButton(bool)
  • setTableBorder(...)、setTableBk(...)
  • setTableFillMode(...)、setTableLineStyle(...)、setTableBorderWidth(...)
  • clearHeaders()、clearData()、resetTable()

常用读取接口

  • getCurrentPage()、getTotalPages()
  • getRowsPerPage()、getShowPageButton()
  • getTableBorder()、getTableBk()
  • getTableFillMode()、getTableLineStyle()
  • getHeaders()、getData()
  • getTableBorderWidth()
  • getTableWidth()、getTableHeight()
注意： setData(...) 是追加语义，不会自动覆盖已有数据。 如需替换旧数据，请先调用 clearData()；如需同时清空表头和分页状态，请调用 resetTable()。
table_demo.cpp 
auto table = std::make_unique<Table>(40, 80);

table->setHeaders({ "寄存器", "值", "说明" });

table->setData({
    { "EAX", "0x00000000", "累加器" },
    { "EBX", "0x00000000", "基址寄存器" },
    { "ECX", "0x00000000", "计数寄存器" }
});

table->setRowsPerPage(5);
table->showPageButton(true);

win.addControl(std::move(table));

Dialog

Dialog 与 MessageBox

标准提示、确认和选择场景建议优先使用 StellarX::MessageBox； 需要自定义内容时再直接使用 Dialog。

MessageBox 工厂接口

StellarX::MessageBox::showModal(...) 显示模态消息框，运行 Dialog 自己的事件循环，关闭后返回 MessageBoxResult。
StellarX::MessageBox::showAsync(...) 显示非模态消息框并立即返回，可通过回调异步获取结果。
messagebox.cpp 
auto result = StellarX::MessageBox::showModal(
    win,
    "是否继续执行？",
    "确认",
    StellarX::MessageBoxType::YesNo
);

if (result == StellarX::MessageBoxResult::Yes)
{
    // 用户选择“是”
}

Dialog 公开接口

  • Dialog(Window& wnd, std::string titleText, std::string message, StellarX::MessageBoxType type, bool modal)
  • Show() / Close()
  • SetTitle(...) / SetMessage(...) / SetType(...)
  • SetModal(...) / model()
  • SetResult(...) / GetResult()
  • SetResultCallback(...)
  • GetCaption() / GetText()
  • addControl(...) / clearControls()
  • recenterInHostWindow()
  • 公开字段：textStyle
建议： 非模态 Dialog 由 Window 托管生命周期。关闭 Dialog 或改变全局覆盖关系后， Window 会在安全点完成清理和必要的全场景重绘。

Layout & Repaint

布局与重绘边界

v4.0.0 推荐使用水平轴和垂直轴独立配置的布局 API。 旧版 LayoutMode 与 Anchor 仍保留用于兼容。

布局枚举与结构

StellarX::LayoutMode 旧版兼容模式：Fixed、AnchorToEdges。
StellarX::Anchor 旧版锚点：NoAnchor、Left、Right、Top、Bottom。
StellarX::AxisSizePolicy Stretch 或 FixedSize，决定单轴尺寸是否变化。
StellarX::AxisAlignPolicy Start、End、Center、Proportional，决定固定尺寸时的位置。
StellarX::AxisLayoutSpec 描述一个坐标轴上的起止锚点、尺寸策略和位置策略。
StellarX::LayoutSpec 组合水平轴与垂直轴两份 AxisLayoutSpec。
StellarX::LayoutCapability 描述具体控件在哪些轴上允许 Stretch。
StellarX::ResolvedLayoutRect 保存布局解算后的父局部矩形和窗口世界坐标矩形，主要供框架内部应用。

布局示例

layout.cpp 
auto button = std::make_unique<Button>(40, 40, 200, 44, "自适应宽度");

button->setHorizontalAnchors(true, true);
button->setHorizontalSizePolicy(
    StellarX::AxisSizePolicy::Stretch
);

button->setVerticalAnchors(true, false);
button->setVerticalSizePolicy(
    StellarX::AxisSizePolicy::FixedSize
);

win.addControl(std::move(button));
能力边界： Canvas 和 TabControl 默认支持水平、垂直 Stretch； Table 当前支持水平 Stretch，但不支持垂直 Stretch。
设计态与运行态 localX/localY/localWidth/localHeight 是布局设计基线； x/y/width/height 是当前运行态绘制矩形。
dirty 与托管重绘 状态变化后优先使用公开 setter 或 setDirty(true)。 事件处理中不要随意直接绘制，Window 会在收口阶段统一提交托管重绘。
提交新设计基线 普通 resize 不会自动回写 local*。 只有明确需要把当前矩形作为新基线时，才调用 commitCurrentGeometryAsDesignRect()。

SxLog

SxLog 日志系统

SxLog 提供控制台与文件输出、级别过滤、Tag 过滤、双语文本选择、文件滚动和 RAII 日志行。

常用接口

StellarX::SxLogger::Get() 获取全局日志器单例。
setMinLevel(...) / getMinLevel() 设置或读取最低输出级别。
enableConsole(bool) 启用或关闭控制台输出。
enableFile(path, append, rotateBytes) 启用文件输出并返回是否打开成功，可设置滚动阈值。
disableFile() 关闭文件输出，不影响控制台输出。
setTagFilter(...) / clearTagFilter() 设置或清空 Tag 白名单、黑名单过滤。
setLanguage(...) / SX_T(zh, en) 选择中英文日志文本；不执行字符编码转换。
getConfigCopy() 获取当前日志配置副本。
setConfig(const SxLogConfig&) 整体应用配置并返回是否成功；新文件 sink 打开失败时保留原配置。
SX_LOG_TRACE / SX_LOGD / SX_LOGI / SX_LOGW / SX_LOGE / SX_LOGF 按级别输出日志的常用宏。
SX_TRACE_SCOPE(tag, name) 在 Trace 级别启用时统计作用域耗时。

日志示例

sxlog.cpp 
#include "StellarX.h"

int main()
{
    StellarX::SxLogger::setGBK();

    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");

    Window win(900, 600, NULL, RGB(246, 248, 251), "SxLog Demo");

    win.draw();

    return win.runEventLoop();
}
注意： SX_T 只选择字符串，不进行编码转换；控制台是否乱码仍取决于 codepage、字体和运行环境。 SxLog 宏使用 if/else 短路形式，不要把它裸放在没有大括号的单行 if/else 分支中。

Next Step

继续阅读

查询 API 后，可以结合示例 Demo、快速开始和公开头文件继续验证。