Quick Start

五分钟跑起第一个 StellarX 窗口

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

以下步骤以 Visual Studio 2022、Windows x64 和 EasyX 为例。你可以使用预编译静态库，也可以直接将框架源码加入自己的项目。

下载 Release GitHub 仓库 API 指南

Before Start

开始前确认

Windows 10+ StellarX 当前面向 Windows 桌面环境。
Visual Studio 2022 预编译包使用 MSVC v143 工具集构建。
EasyX 2022+ 需要先安装与 Visual Studio 匹配的 EasyX。
C++17 / x64 当前预编译包提供 x64 Debug 与 Release 静态库。
01 准备环境
02 获取 StellarX
03 配置 VS 项目
04 运行第一个窗口
05 验证按钮事件

Step 01

准备开发环境

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

安装 Visual Studio

建议安装 Visual Studio 2022，并勾选“使用 C++ 的桌面开发”工作负载，确保已经安装 MSVC v143 和 Windows SDK。

Graphics

安装 EasyX

StellarX 当前依赖 EasyX。安装完成后，Visual Studio 中应能正常包含 easyx.h 并运行 EasyX 示例。

Language

使用 C++17 与 x64

将项目语言标准设置为 C++17 或更高版本。使用 v4.0.0 预编译库时，项目平台必须选择 x64。

Step 02

获取 StellarX v4.0.0

可以下载包含公共头文件和预编译静态库的 Release 包，也可以获取完整源码并直接加入自己的工程。初次使用建议选择 Release 包。
下载 Release 查看源码
Git 
git clone --branch v4.0.0 --depth 1 https://github.com/Ysm-04/StellarX.git

Step 03

配置 Visual Studio 项目

创建一个 C++ 工程，然后从源码接入和预编译静态库中选择一种方式。两种方式不能同时使用。
1

创建 C++ 空项目

在 Visual Studio 中新建一个 C++ 空项目，例如命名为 StellarXQuickStart。 将解决方案平台切换为 x64，并在项目属性中分别检查 Debug 和 Release 配置。

2

选择 StellarX 引入方式

方式 A 适合阅读、调试或修改框架源码；方式 B 直接链接 Release 包中的静态库，配置更简单。 两种方式二选一，不要在编译 StellarX 源码的同时链接 StellarX 静态库。

A

方式 A：直接加入框架源码

将 include/StellarX/*.h、src/*.cpp 和 src/internal/*.h 按原有结构放入项目，例如统一放在 third_party/StellarX 目录下。

A1

配置源码包含目录

打开 配置属性 → C/C++ → 常规 → 附加包含目录， 添加 third_party\StellarX\include\StellarX 和 third_party\StellarX\src\internal。

A2

加入实现文件

将 src 根目录下的 11 个 .cpp 文件全部加入工程，并确保每个文件只参与一次编译。 不要直接 #include 任何 .cpp 文件。

A3

保留私有头文件边界

src/internal 中的头文件只供 StellarX 实现文件使用。 业务代码统一包含 StellarX.h，不要直接包含 SxEventLoopInternal.h 或 SxTextInternal.h。

B

方式 B：使用预编译静态库

v4.0.0 Release 包提供公共头文件以及 x64 Debug、Release 静态库。 该预编译包使用 Visual Studio 2022 的 MSVC v143 工具集构建。

B1

配置公共头文件目录

打开 配置属性 → C/C++ → 常规 → 附加包含目录， 添加解压目录中的 include\StellarX。业务代码随后可以使用 #include "StellarX.h"。

B2

配置静态库目录

打开 配置属性 → 链接器 → 常规 → 附加库目录， 添加 Release 包中的 lib 目录。

B3

配置 StellarX 附加依赖项

打开 配置属性 → 链接器 → 输入 → 附加依赖项。 Debug x64 添加 StellarX-v4.0.0-Debug.lib； Release x64 添加 StellarX-v4.0.0-Release.lib。

B4

匹配运行库设置

打开 配置属性 → C/C++ → 代码生成 → 运行库。 Debug 使用 多线程调试 DLL (/MDd)， Release 使用 多线程 DLL (/MD)。

3

确认 EasyX 与系统库

确保项目可以找到 easyx.h 并链接 EasyX。 手动配置依赖项时，还需要链接 user32.lib、 gdi32.lib 和 shell32.lib。

4

设置多字节字符集

打开 配置属性 → 高级 → 字符集， 选择 使用多字节字符集。

5

设置源文件与执行字符集

打开 配置属性 → C/C++ → 命令行 → 其他选项， 添加 /source-charset:utf-8 /execution-charset:.936， 让 UTF-8 源文件中的中文按当前 EasyX 多字节环境正确转换。

6

设置 C++ 语言标准

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

7

检查配置是否匹配

最后确认项目平台为 x64，并分别检查 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 交给 Window 管理。调用 addControl() 后，不要继续长期保存或使用原始控件指针。
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

检查 配置属性 → C/C++ → 常规 → 附加包含目录。 使用 Release 包时，该目录应指向解压后的 include\StellarX； 使用源码方式时，应指向源码中的 include\StellarX。

找不到 SxEventLoopInternal.h 或 SxTextInternal.h

这个问题只会出现在直接编译源码时。请保留 src\internal 中的私有头文件， 并将该目录加入框架实现所使用的附加包含目录。业务代码不应直接包含这些私有头。

StellarX 相关符号链接失败

使用源码方式时，确认 src 根目录下的 11 个 .cpp 文件均已加入工程并参与编译。 使用静态库方式时，检查附加库目录和附加依赖项，并确认 Debug、Release 使用了对应的库文件。

出现重复符号或重复定义

检查是否同时编译了 StellarX 的 .cpp 文件并链接了 StellarX 静态库。 两种接入方式只能选择一种，同时确认每个实现文件没有被多个项目重复编译和链接。

出现运行库不匹配或 LNK2038

确认项目平台为 x64。Debug 应链接 StellarX-v4.0.0-Debug.lib 并使用 /MDd； Release 应链接 StellarX-v4.0.0-Release.lib 并使用 /MD。

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

确认已经为当前 Visual Studio 安装 EasyX，并检查 EasyX 的包含目录和库目录。 手动配置时还应确认 EasyX 库以及 user32.lib、 gdi32.lib、shell32.lib 已加入附加依赖项。

窗口打开后马上关闭

确认代码最后返回的是 win.runEventLoop()，不要在绘制后直接 return 0。 如果调试器报告异常，还应先查看 Visual Studio 的输出窗口和调用堆栈。

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

将项目字符集设为“使用多字节字符集”，并在编译器其他选项中加入 /source-charset:utf-8 /execution-charset:.936。 同时确认源码以 UTF-8 保存，并检查当前字体是否包含所需中文字形。

Debug 可以运行，Release 出问题

Debug 和 Release 拥有独立的项目属性。请分别检查附加包含目录、附加库目录、附加依赖项、运行库、字符集、C++ 语言标准和 x64 平台设置。

Next Step

下一步看什么？

第一个窗口运行成功后，可以继续阅读 API 指南、示例 Demo 或文档总览。