API Guide

StellarX API 指南

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

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

Public API Map

主要模块

Core Types枚举、文本样式、布局结构体 Window窗口、背景、事件循环 Control控件基类与布局入口 ContainersCanvas / TabControl WidgetsButton / Label / TextBox / Table DialogDialog / MessageBox Layout锚点、尺寸策略、重绘边界 SxLog日志、Tag、双语文本

Full Reference

完整 API 文档

当前页面主要整理常用公开接口、最小示例和使用注意事项，不替代完整 API 文档。如果需要查看更完整的类、方法、参数和源码级说明，可以前往 GitHub 中的 API 文档。

查看完整 API 文档

控件通常交给容器管理

Window、Canvas、TabControl 等接口通过 std::unique_ptr 接管控件生命周期。

多数控件类在全局命名空间

Window、Button、Label 等是全局类；枚举和 MessageBox 位于 StellarX 命名空间。具体声明位置以头文件为准。

部分接口命名保留历史风格

例如 setbuttonMode、setCanvasfillMode、setTextBoxshape、setTextdisap，使用时按源码大小写书写。

Index

API 快速索引

先按模块定位，再查看构造函数、常用方法和最小示例。

Core 核心类型 枚举、文本样式、布局结构体 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`

文本样式：ControlText

多个控件公开了 textStyle 字段，可用于设置字体高度、字体名、颜色、加粗、斜体、下划线等。

ControlText

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

label->textStyle.nHeight = 28;
label->textStyle.lpszFace = "微软雅黑";
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()`	进入主事件循环，处理事件分发和统一重绘收口。
`addControl(std::unique_ptr<Control> control)`	添加顶层控件，Window 接管控件生命周期。
`setBkImage(...)` / `setBkcolor(...)` / `setHeadline(...)`	设置背景图、背景色和窗口标题。

最小窗口示例

main.cpp

#include "StellarX.h"

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

    win.draw();

    return win.runEventLoop();
}

常用访问器 getHwnd()、getWidth()、getHeight()、getHeadline()、getBkcolor()、getControls()

对话框相关 addDialog(...)、hasNonModalDialogWithCaption(...) 主要由 Dialog / MessageBox 工厂使用。

进阶重绘接口 requestManagedRepaint(...)、flushManagedRepaint() 等偏框架内部，普通使用者通常不需要直接调用。

Control

Control：所有控件的基础接口

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

通用几何与状态接口

接口	说明
`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(...)`	直接设置单轴布局规格。
`commitCurrentGeometryAsDesignRect()`	将当前运行态矩形提交为新的设计基线，属于进阶接口。

Containers

Canvas 与 TabControl

Canvas 用于分组和管理子控件；TabControl 用于管理页签按钮与页面 Canvas。

Canvas

Canvas 是容器控件，支持背景、边框、形状、填充模式和子控件托管。

`Canvas()` / `Canvas(int x, int y, int width, int height)`	创建容器。
`addControl(std::unique_ptr<Control>)`	添加子控件，Canvas 接管生命周期。
`setShape(...)`	设置容器形状。
`setCanvasfillMode(...)`	设置填充模式。
`setCanvasBkColor(...)` / `setBorderColor(...)`	设置背景色和边框颜色。
`setCanvasLineStyle(...)` / `setLinewidth(...)`	设置线型和线宽。
`getControls()`	获取直接子控件列表。

TabControl

TabControl 继承 Canvas，但外部不要直接调用 Canvas 的 addControl；应使用 TabControl 自己的 add 接口。

`TabControl()` / `TabControl(int x, int y, int width, int height)`	创建页签控件。
`add(std::pair<std::unique_ptr<Button>, std::unique_ptr<Canvas>>&&)`	添加一个页签按钮与对应页面。
`add(std::string tabText, std::unique_ptr<Control> control)`	按页签文本把控件添加到对应页面。
`setTabPlacement(...)`	设置页签位置：Top / Bottom / Left / Right。
`setTabBarHeight(...)`	设置页签栏高度，左右排列时作为宽度使用。
`getActiveIndex()` / `setActiveIndex(...)`	获取或设置当前激活页签。
`count()` / `indexOf(...)`	获取页签数量或按文本查找索引。

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();
}

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()`、公开字段 `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(...)`	显示模态消息框，阻塞直到关闭并返回 `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()
recenterInHostWindow()
公开字段：textStyle

建议： 标准提示、确认、选择类场景优先用 MessageBox。直接操作 Dialog 时要注意模态与非模态生命周期。

Layout & Repaint

布局与重绘边界

StellarX 当前提供固定布局、锚点布局和单轴布局规格。普通页面开发优先使用锚点与尺寸策略。

布局枚举与结构

`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` 组成。

布局示例

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

边界： Table 当前明确支持横向拉伸，纵向 Stretch 会被控件能力边界限制。

dirty 标记 setDirty(true) 表示控件需要重绘。部分控件会在内容变化时自动标脏。

托管重绘 托管重绘相关接口主要服务框架内部重绘链路。普通使用者通常只需要调用控件 setter，或在必要时调用 setDirty(true)。

设计态与运行态 local* 表示设计基线，运行时 resize 后会解算成当前绘制位置与尺寸。

SxLog

SxLog 日志系统

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

常用接口

`StellarX::SxLogger::Get()`	获取全局日志器单例。
`setMinLevel(...)`	设置最低输出级别。
`enableConsole(bool)`	启用或关闭控制台输出。
`enableFile(path, append, rotateBytes)`	启用文件输出，可设置滚动阈值。
`setTagFilter(...)` / `clearTagFilter()`	设置或清空 Tag 过滤。
`setLanguage(...)` / `SX_T(zh, en)`	选择中英文输出文本。
`SX_LOG_TRACE` / `SX_LOGD` / `SX_LOGI` / `SX_LOGW` / `SX_LOGE` / `SX_LOGF`	常用日志宏。
`SX_TRACE_SCOPE(tag, name)`	作用域耗时统计宏。

日志示例

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

    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、字体和运行环境。

Next Step

继续阅读

查完 API 后，可以结合示例 Demo、快速开始和源码继续验证。

StellarX API 指南

主要模块

完整 API 文档

推荐只包含 StellarX.h

控件通常交给容器管理

多数控件类在全局命名空间

部分接口命名保留历史风格

API 快速索引

核心类型与枚举

常用枚举

文本样式：ControlText

Window：窗口与事件循环

构造函数与核心方法

最小窗口示例

Control：所有控件的基础接口

通用几何与状态接口

布局相关入口

Canvas 与 TabControl

Canvas

TabControl

常用控件 API

Button：按钮控件

Label：文本标签

常用接口

使用提示

TextBox：文本框

Table：表格控件

常用接口

常用读取接口

Dialog 与 MessageBox

MessageBox 工厂接口

Dialog 公开接口

布局与重绘边界

布局枚举与结构

布局示例

SxLog 日志系统

常用接口

日志示例

继续阅读