Quick Start

五分钟跑起第一个 StellarX 窗口

本页面只做一件事：帮助你完成环境准备、引入 StellarX，并运行第一个可交互的 C++ GUI 程序。

如果你已经安装 Visual Studio 与 EasyX，并具备基本 C++ 语法基础，可以直接从最小窗口示例开始。

下载 Release GitHub 仓库 API 指南

Before Start

开始前确认

Windows 当前基础版面向 Windows 桌面环境。
Visual Studio 建议使用 VS2022，创建 C++ 空项目。
EasyX 需要先安装 EasyX 图形库。
C++17 建议使用 C++17 或更高标准。
01 准备环境
02 获取 StellarX
03 创建 VS 项目
04 运行第一个窗口
05 验证按钮事件

Step 01

准备开发环境

StellarX 基础版基于 EasyX 与 Win32，适合 Windows 平台下的教学、小型工具和 GUI 原理学习。
Environment

安装 Visual Studio

建议安装 Visual Studio 2022，并勾选“使用 C++ 的桌面开发”工作负载。

Graphics

安装 EasyX

StellarX 当前基础版依赖 EasyX。安装完成后，VS 中应能正常包含 easyx.h 并编译 EasyX 示例。

Language

设置 C++17

推荐将项目语言标准设置为 C++17，避免因标准过旧导致部分语法或库特性不可用。

Step 02

获取 StellarX

你可以从 GitHub Release 下载稳定版本，也可以直接 clone 仓库源码。初学阶段推荐先使用 Release 包。
下载 Release 查看源码
Git 
git clone https://github.com/Ysm-04/StellarX.git

Step 03

创建 Visual Studio 项目

这一步的目标是创建一个 C++ 工程，并选择一种方式引入 StellarX。 你可以直接添加源码文件，也可以使用 Release 包中发布的头文件和静态库文件。
1

创建 C++ 空项目

在 Visual Studio 中新建一个 C++ 空项目，例如命名为 StellarXQuickStart。 建议先切到 所有配置 和 所有平台 后再统一设置项目属性。

2

选择 StellarX 引入方式

下面两种方式二选一即可：方式 A 适合直接阅读和调试源码；方式 B 适合使用 Release 包中的 .lib 进行链接。

A

方式 A：直接添加源码文件

右键项目，选择 添加 → 现有项， 将 StellarX 的 .h 和 .cpp 文件加入当前工程。 这种方式下，StellarX 源码会直接参与当前项目编译，不需要再额外链接 StellarX 的 .lib。

B

方式 B：使用发布包中的静态库

如果你使用 Release 包中的 .lib，需要配置 StellarX 的头文件目录、库文件目录和附加依赖项。 这种方式下，一般不需要再把 StellarX 的 .cpp 文件加入当前工程。

B1

配置 StellarX 附加包含目录

打开项目属性，进入 配置属性 → C/C++ → 常规 → 附加包含目录， 添加 StellarX 头文件所在目录。这样工程才能正常包含 StellarX.h。

B2

配置 StellarX 附加库目录

打开项目属性，进入 配置属性 → 链接器 → 常规 → 附加库目录， 添加 StellarX 的 .lib 文件所在目录。这个选项只负责告诉链接器去哪里查找库文件。

B3

配置 StellarX 附加依赖项

打开项目属性，进入 配置属性 → 链接器 → 输入 → 附加依赖项， 添加需要链接的 StellarX 库文件名，例如 StellarX.lib。 具体名称以 Release 包中实际提供的库文件为准。

3

确认 EasyX 可用

如果 EasyX 安装器已经自动完成 Visual Studio 配置，通常可以直接使用。 如果项目找不到 easyx.h，需要进入 配置属性 → C/C++ → 常规 → 附加包含目录， 添加 EasyX 头文件所在目录。

4

配置 EasyX 附加库目录

如果链接阶段找不到 EasyX 相关库，进入 配置属性 → 链接器 → 常规 → 附加库目录， 添加 EasyX 库文件所在目录。这个选项只负责告诉链接器去哪里查找 .lib 文件。

5

配置 EasyX 附加依赖项

如果仍然链接失败，进入 配置属性 → 链接器 → 输入 → 附加依赖项， 添加需要链接的 EasyX 库文件名。具体库名以你的 EasyX 安装目录和版本为准。

6

设置为多字节字符集

打开项目属性，进入 配置属性 → 高级 → 字符集， 选择 使用多字节字符集。StellarX 基础版当前主要按 EasyX 常见的多字节环境使用。

7

设置 C++ 语言标准

打开项目属性，进入 配置属性 → C/C++ → 语言 → C++ 语言标准， 建议选择 ISO C++17 标准 或更高版本。

8

确认配置和平台一致

检查 Debug / Release、Win32 / x64 下的附加包含目录、附加库目录、附加依赖项、字符集和 C++ 语言标准是否一致。 很多“Debug 能运行，Release 失败”的问题都来自这里。

Step 04

运行第一个窗口

新建 main.cpp，复制下面的代码。运行后，你应该能看到一个 StellarX 窗口。
提示： 如果窗口一闪而过，确认 runEventLoop() 正常执行，并且没有在事件循环前提前退出。
main.cpp 
#include "StellarX.h"

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

    win.draw();

    return win.runEventLoop();
}

Step 05

添加一个按钮

窗口跑起来之后，可以继续添加一个 Button，验证控件创建、事件回调和消息框是否正常工作。 这里使用 std::unique_ptr 把按钮交给窗口管理，避免手动释放控件对象。
注意： 这里使用 setOnClickListener 绑定按钮点击事件，和当前源码中的命名保持一致。
button_demo.cpp 
#include "StellarX.h"
#include <memory>
#include <utility>

int main()
{
    Window win(900, 600, NULL, RGB(246, 248, 251), "StellarX Quick Start");

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

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

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

    win.draw();

    return win.runEventLoop();
}

Troubleshooting

常见问题

如果第一个窗口没有正常运行，可以先从下面几个方向排查。
找不到 StellarX.h

检查是否已经添加 StellarX 头文件，或者是否正确配置了 配置属性 → C/C++ → 常规 → 附加包含目录。 如果使用静态库方式，也要确认该目录指向 Release 包中的头文件目录。

StellarX 相关符号链接失败

如果使用源码方式，确认 StellarX 的 .cpp 文件已经加入工程并参与编译； 如果使用 .lib 方式，检查 链接器 → 常规 → 附加库目录 和 链接器 → 输入 → 附加依赖项， 并确认库文件名与 Release 包中的实际文件名一致。

找不到 easyx.h 或 EasyX 链接失败

找不到 easyx.h 通常是 EasyX 附加包含目录没有配置正确； 链接失败通常需要检查 链接器 → 常规 → 附加库目录 和 链接器 → 输入 → 附加依赖项。 同时确认 Debug / Release、Win32 / x64 与 EasyX 安装环境一致。

窗口打开后马上关闭

确认代码最后返回的是 win.runEventLoop()，不要在绘制后直接 return 0。

中文显示异常或控制台乱码

先确认源文件编码、系统代码页、字体环境和项目字符集。StellarX 基础版建议在 配置属性 → 高级 → 字符集 中选择 使用多字节字符集。

Debug 可以运行，Release 出问题

检查 Release 配置下的附加包含目录、附加库目录、附加依赖项、字符集、C++ 语言标准和项目平台是否与 Debug 一致。

Next Step

下一步看什么？

第一个窗口跑起来之后，可以继续阅读 API 指南、示例 Demo 或文档总览。