1.控件体系总览
“这一页将带你从整体认识 StellarX 控件体系，到学会使用常见控件，最后给出通往完整 API 文档的入口。”
StellarX 的控件体系围绕 Control 这一基类展开，所有可视控件都继承自它。Window 负责创建窗口与事件循环；Canvas、TabControl、Dialog、Table 属于容器控件，用来承载其他控件；Label、Button、TextBox 等属于基础交互控件。控件 API 文档 (StellarX GUI Framewo…
简单理解就是：
- Window：应用外壳，负责事件循环与统一绘制。
- Control：所有控件的基类，封装了位置、尺寸、可见性和重绘标记等共通能力。
- Canvas：通用容器控件，可以嵌套，用来组织布局。
- Label / Button / TextBox：常见的文本、按钮、输入框控件。
- TabControl / Dialog / Table：选项卡、对话框、表格等复合控件。
详细的类关系与完整 API 请在 GitHub 文档中查看。
2.核心概念（坐标 / 可见性 / 重绘 / 事件）
坐标与尺寸
所有控件都带有 x, y, width, height 四个基础属性，用来描述控件在窗口坐标系中的位置与大小（相对于窗口原点 (0,0)）。
这些值主要用于布局与调试，容器控件内部会负责把子控件绘制到正确位置。
可见性：setIsVisible（）
通过 setIsVisible(bool) 可以控制控件是否参与绘制与事件响应。父容器隐藏时，内部子控件也会被一并“看不见”。
重绘标记（Dirty Flag）
控件内部维护一个 “dirty” 标记，当内容或状态变化时调用 setDirty(true)，框架会在下一帧统一重绘这些脏控件，避免无意义的全局刷新，提高性能。
事件处理：handleEvent()
所有控件都实现 handleEvent(const ExMessage&) 用来响应鼠标、键盘等输入事件，并返回一个 bool 表示事件是否被消费。
ExMessage msg;
while (peekmessage(&msg, EM_MOUSE | EM_KEY))
{
for (auto& ctrl : controls)
{
if (ctrl->handleEvent(msg))
{
break; // 事件已被某个控件消费
}
}
}
3.创建第一个窗口（Window / Canvas / Button）
示例代码
#include "StellarX.h"
int main() {
// 1. 创建主窗口
Window win(1300, 800, NULL, RGB(255, 255, 0),"StellarX Demo");
// 2. 准备一个 Canvas 容器
auto mainCanvas = std::make_unique<Canvas>(20, 20, 760, 560);
mainCanvas->setCanvasBkColor(RGB(245, 245, 245));
// 3. 添加一个标签
auto label = std::make_unique<Label>(40, 40, "Hello, StellarX!");
label->setTextdisap(true);//设置标签背景透明
// 4. 添加一个按钮
auto btn = std::make_unique<Button>(40, 100, 160, 40, "Click me");
btn->setOnClickListener([&win](){
StellarX::MessageBox::showAsync(win, "欢迎使用StellarX\n作者：我在人间做废物", "欢迎"); });
});
mainCanvas->addControl(std::move(label));
mainCanvas->addControl(std::move(btn));
win.addControl(std::move(mainCanvas));
//绘制窗口
win.draw()
// 5. 进入事件循环
win.runEventLoop();
return 0;
}
- 创建一个Window类的对象，即创建窗口主体。
参数为（宽，高，创建模式，背景颜色，窗口标题）还有其他几个重载模式，详见API文档- 创建一个容器，即Canvas类的对象。
参数（x坐标，y坐标，宽，高）然后通过setCanvasBkColor设置容器的背景色- 创建一个标签，即Label类的对象
参数（x，y，文本）通过setTextdisap设置标签背景是否透明- 创建一个按钮，即Button类的对象
参数（x，y，宽，高，文本）有其他重载详见API文档，通过setOnClickListener为按钮注册事件回调，这里用了一个lambda表达式
注意在按钮为默认模式时用setOnClickListener注册回调，如果为开关模式要是有对应的API来为不同状态分别注册回调- 进入事件循环，事件循环会一直阻塞直到用户关闭窗口
4.常用控件使用示例（按控件分类的小节）
4.1 Label
- 设置文本：
setText(const std::string&) - 设置文字背景：
setTextBkColor(COLORREF)
auto label = std::make_unique<Label>(10, 10, "FPS: 60");
label->setTextBkColor(RGB(255,0,0));
canvas->addControl(std::move(label));
4.2 Button
- 普通点击回调：
setOnClickListener(function<void()>)- 开关模式回调：
setOnToggleOnListener/setOnToggleOffListener- 提示气泡：
setTooltipText()/setTooltipOffset()
auto btn = std::make_unique<Button>(100, 40, 100, 50, "点击我",StellarX::ButtonMode::TOGGLE);
//也可以通过setbuttonMode来设置按钮的模式
//按钮为TOGGLE模式时，要分别设置开和关的监听器
btn->setOnToggleOnListener([&win](){
StellarX::MessageBox::showAsync(win, "被点击了", "提示"); });
btn->setOnToggleOffListener([&win]() {
StellarX::MessageBox::showAsync(win, "点击被取消了", "提示"); });
//开启提示气泡，默认为按钮文本，可通过setTooltipText修改
btn->enableTooltip(true);
4.3 TextBox
- 获取文本：
getText()- 设置文本：
setText()- 限制长度：
setMaxCharLen(size_t)- 模式切换：
setMode(TextBoxMode)（只读/可输入）
auto box = std::make_unique<TextBox>(100, 40, 100, 50);
//设置文本框内容
box->setText("输入框");
//获取文本框内容
std::string content = box->getText();
//限制最大可输入字符长度
box->setMaxCharLen(20);
//设置文本框为只读模式
box->setMode(StellarX::TextBoxmode::READONLY_MODE);4.4 容器类：Canvas / TabControl / Dialog / Table
4.4.1 Canvas
Canvas是一个画布容器，继承自Control，主要用来统一管理其他控件，Canvas可以嵌套
auto can = std::make_unique<Canvas>(100, 40, 100, 50);
//设置边框颜色
can->setBorderColor(RGB(255, 0, 0));
//设置填充(背景)颜色
can->setCanvasBkColor(RGB(132,222,0));
//设置画布样式为无边框矩形
can->setShape(StellarX::ControlShape::B_ROUND_RECTANGLE);
auto label = std::make_unique<Label>(0, 0, "FPS: 60");
label->setTextBkColor(RGB(255, 0, 0));
//添加标签到画布
can->addControl(std::move(label));4.4.2 TabControl
TabControl用于创建选项卡，本身继承自Canvas。先创建一组“按钮 + Canvas”的页，再通过add()注册到 TabControl。
auto tc = std::make_unique<TabControl>(100, 40, 300, 300);
//设置页签位置
tc->setTabPlacement(StellarX::TabPlacement::Left);
//设置页签栏高度 两侧排列时为宽度
tc->setTabBarHeight(80);
//创建页签及对应页面
std::pair<std::unique_ptr<Button>, std::unique_ptr<Canvas>> tab1;
tab1.first = std::make_unique<Button>(0, 0, 80, 80, "页签1");
tab1.second = std::make_unique<Canvas>(0, 0, 300, 300);
//将页签及对应页面添加到TabControl
tc->add(std::move(tab1));如果需要给某个 tab 的页面添加控件，可以使用
TabControl::add("页签文本", std::unique_ptr<Control>)这个重载
4.4.3 Dialog
Dialog是一个消息框，有模态和非模态两种形式，模态会阻塞主循环，一般不直接调用而是通过StellarX::MessageBox静态工厂调用
auto tc = std::make_unique<Dialog>(win,"这是一个消息框","提示");
//设置模态属性,默认为模态
tc->SetModal(false);
//设置对话框类型，详情参见枚举MessageBoxType
tc->SetType(StellarX::MessageBoxType::AbortRetryIgnore);
//显示对话框 不直接在窗口上显示，而是添加到按钮等的事件回调中
tc->Show();4.4.3 Table
Table控件是一个表格控件，用来将数据表格化展现出来
auto table = std::make_unique<Table>(220, 330);
//设置表头
table->setHeaders({ "日期","收入","支出","备注" });
//设置表格数据
table->setData({
{"2024-01-01","1000","200","购买办公用品"},
{"2024-01-02","1500","300","员工工资"},
{"2024-01-03","2000","500","市场推广"},
{"2024-01-04","2500","400","设备维护"},
{"2024-01-05","1800","600","差旅费用"},
{"2024-01-06","2200","350","客户招待"},
{"2024-01-07","3000","800","租金支付"},
{"2024-01-08","2700","450","水电费"},
{"2024-01-09","3200","700","税务支出"},
{"2024-01-10","2900","500","其他杂项"}
});
//设置每页显示的行数
table->setRowsPerPage(3);
//设置是否显示翻页按钮和页码，默认显示
table->showPageButton(false);5.布局与自适应（Anchor / adaptiveLayout）
- 通过
Control::setLayoutMode(AnchorMode)启用锚定系统，通过steAnchor这是锚点（左/右/上下对齐、拉伸等）。- 对于
Canvas等容器，在处理完窗口大小变化之后，调用adaptiveLayout()让内部控件按锚点规则自动调整位置和尺寸
auto btn = std::make_unique<Button>(100, 40, 100, 50, "点击我", StellarX::ButtonMode::TOGGLE);
btn->setLayoutMode(StellarX::LayoutMode::AnchorToEdges);
btn->steAnchor(StellarX::Anchor::Top, StellarX::Anchor::NoAnchor);6.完整 API 文档入口
完整 API 文档 / More Details
本页面只介绍了常用控件与典型用法，完整的类/函数说明（包括参数表、行为细节与更多示例）请参见 GitHub 上的 《StellarX 控件 API 文档》
点击下方按钮跳转，进入页面点击右侧三条刚可列出大纲目录