快速开始快速开始 - StellarX 星垣 C++ GUI框架

快速开始

目标：从 0 到跑起第一个 StellarX 窗口，用最短路径验证环境没问题。

1. 使用前准备

你需要准备的东西：

已安装 Visual Studio 2019 / 2022（含 C++ 桌面开发）
Windows 10 / 11
基本的 C++ 语法基础（类、指针、new/delete）
Easyx图形库（点击直达下载链接）

如果你是完全零基础的同学，建议先完成学校/网上的 C++ 基础课程，再来尝试 GUI 开发。

2. 获取 StellarX

方式一：下载 Release 压缩包

前往「Release & 更新日志」或 GitHub Release 页面
下载最新版本的压缩包，解压到一个你喜欢的位置，例如 D:\StellarX

方式二：使用 Git 克隆仓库

在命令行执行：
git clone https://github.com/Ysm-04/StellarX.git
克隆完成后，源码目录中会包含框架代码和示例工程

如果在使用Git克隆仓库时出现：fatal: unable to access 'https://github.com/Ysm-04/StellarX.git/': Failed to connect to github.com port 443 after 21128 ms: Could not connect to server 或类似报错，可能是因为网络环境问题，请多尝试执行几次克隆命令。或者直接下载仓库ZIP

方式三：下载仓库zip

如果你没有git ，但是又想拿到框架的源代码而不是使用Release，
在GitHub仓库主页，点击code按钮，点击Dodwnload ZIP
即可下载仓库的完整压缩包

下文以「解压/克隆后的 StellarX 目录」记为 STELLARX_ROOT。

3. 创建第一个工程

创建工程

3.1.在 VS 中创建空项目

打开 VS → 新建项目 → 选择「空项目」（Console / 空项目均可）
项目类型选择 C++，设置好名称和路径

3.2.添加源文件倒工程

（如果你下载的是Release不用看这条）
如果你使用的是源码，那么把所有的头文件和源文件
添加到你的项目里即可，然后直接看第3.5条

在项目属性中：
- C/C++ → 常规 → 「附加包含目录」中加入：
  STELLARX_ROOT\include（按你实际目录写）
- 链接器 → 常规 → 「附加库目录」中加入：
  STELLARX_ROOT\lib

3.4.链接 StellarX 静态库

链接器 → 输入 → 「附加依赖项」中加入例如：
StellarX-vX.X.X-Release.lib\StellarX-vX.X.X-Debug.lib
注意：按lib目录下的实际.lib文件名替换

3.5.新建源文件

在工程中添加一个 main.cpp，用于写第一个窗口示例

4. 第一个窗口示例

代码示例

#include"StellarX.h"//包含头文件

int main()
{
	//创建一个窗口类的对象，参数为：宽度、高度、初始化模式、背景色、标题
	Window win(1300, 800, NULL, RGB(255, 255, 0), "欢迎使用Stellar 星垣-GUI");
	
	//绘制窗口（纯色背景版本）
	win.draw();

	//绘制窗口（背景图版本）参数为背景图文件路径
	//win.draw("image\\bk1.jpg");

	//进入事件循环
	//注意：runEventLoop 会阻塞当前线程直到窗口关闭
	//前面不能写死循环，否则会卡死导致无法响应事件
	return win.runEventLoop();
}

#include"StellarX.h"//包含头文件

int main()
{
	//创建一个窗口类的对象，参数为：宽度、高度、初始化模式、背景色、标题
	Window win(1300, 800, NULL, RGB(255, 255, 0), "欢迎使用Stellar 星垣-GUI");
	
	//绘制窗口（纯色背景版本）
	win.draw();

	//绘制窗口（背景图版本）参数为背景图文件路径
	//win.draw("image\\bk1.jpg");

	//进入事件循环
	//注意：runEventLoop 会阻塞当前线程直到窗口关闭
	//前面不能写死循环，否则会卡死导致无法响应事件
	return win.runEventLoop();
}

Window：负责创建 Win32 窗口并处理消息循环
draw()：让窗口显示出来
runEventLoop()：进入主循环，直到用户关闭窗口

5. 加一个按钮并响应点击

继续在上面的基础上加一点点控件逻辑，让用户看到“可交互”的 GUI。

：

#include"StellarX.h"

int main()
{
	Window win(1300, 800, NULL, RGB(255, 255, 0), "StellarX 星垣");

	//创建按钮  参数：x坐标，y坐标，宽度，高度，文本 ，还有其他重载形式，可以查看API文档或源码
	auto btn = std::make_unique<Button>(100, 40, 100, 50, "点击我");

	//设置点击事件，注册回调函数
	btn->setOnClickListener([&win](){
		StellarX::MessageBox::showAsync(win, "欢迎使用StellarX\n作者：我在人间做废物", "欢迎"); });
	

	//添加按钮到窗口,注意使用std::move转移所有权，这时btn不再拥有该对象
	//如果需要后续操作，可以在添加前保存原始指针或引用
	win.addControl(std::move(btn));

	win.draw();
	return win.runEventLoop();
}

#include"StellarX.h"

int main()
{
	Window win(1300, 800, NULL, RGB(255, 255, 0), "StellarX 星垣");

	//创建按钮  参数：x坐标，y坐标，宽度，高度，文本 ，还有其他重载形式，可以查看API文档或源码
	auto btn = std::make_unique<Button>(100, 40, 100, 50, "点击我");

	//设置点击事件，注册回调函数
	btn->setOnClickListener([&win](){
		StellarX::MessageBox::showAsync(win, "欢迎使用StellarX\n作者：我在人间做废物", "欢迎"); });
	

	//添加按钮到窗口,注意使用std::move转移所有权，这时btn不再拥有该对象
	//如果需要后续操作，可以在添加前保存原始指针或引用
	win.addControl(std::move(btn));

	win.draw();
	return win.runEventLoop();
}

按钮的参数含义：位置 (x, y)、宽度、高度、文本
setOnClick：按钮为默认模式或StellarX::ButtonMode::NORMAL模式注册点击回调，这里用 lambda 显示一个消息框
StellarX::MessageBox 框架自己的对话框工厂模式showAsync为非模态对话框
addControl：把控件添加到窗口/根容器中

这节的目的：证明控件正常绘制，事件可以响应。

6. 常见问题（精简版）

一些常见的问题

编译时报找不到头文件 / 库文件？
→ 检查 VS 属性里的「附加包含目录」和「附加库目录」是否配置正确。
链接错误：无法解析的外部符号？
→ 检查是否在「附加依赖项」中添加了正确的 .lib，以及 Debug/Release 是否匹配。
运行时窗口一闪而过？
→ 确认是否调用了 window.runEventLoop()，并且没有提前 return。
示例代码和实际 API 名称不一致？
→ 以当前版本的头文件/文档为准，本页示例仅用于说明流程。

如果遇到其他问题无法解决，可以联系作者或者在首页评论区反馈，作者会尽快解决

7. 下一步该看什么？

如果你已经成功跑起了示例窗口，可以继续查看：

API / 使用指南：了解 Window、Control、Canvas、Table 等模块的详细用法

示例 Demo：参考完整的小工具与界面示例

下载 & 更新日志：关注最新版本变化与下载方式