星垣 (StellarX) GUI Framework

「繁星为界，轻若尘埃」 —— 一个为Windows平台打造的、极致轻量级、高度模块化的C++原生GUI框架。

星垣 (StellarX) 诞生于对现代GUI框架"过度臃肿"的反抗。它拒绝动辄数百MB的依赖、漫长的编译时间和复杂的学习曲线，选择回归本质：用最精简的代码、最清晰的架构和最高的效率，解决桌面应用开发的核心需求。

它是一个纯粹的教学级、工具级框架，旨在让开发者深入理解GUI原理，并快速构建轻量级Windows工具。

---

📦 项目结构与设计哲学

星垣框架采用经典的面向对象和模块化设计，项目结构清晰规范：

StellarX/
├── include/               # 头文件目录
│   └── StellarX/          # 框架头文件
│       ├── StellarX.h     # 主包含头文件 - 一键引入整个框架
│       ├── CoreTypes.h    # ★ 核心 ★ - 所有枚举、结构体的唯一定义源
│       ├── Control.h      # 抽象基类 - 定义所有控件的统一接口
│       ├── Button.h       # 按钮控件
│       ├── Window.h       # 窗口管理
│       ├── Label.h        # 标签控件
│       ├── TextBox.h      # 文本框控件
│       ├── Canvas.h       # 画布容器
│       └── Table.h        # 表格控件
├── src/                   # 源文件目录
│   ├── Control.cpp
│   ├── Button.cpp
│   ├── Window.cpp
│   ├── Label.cpp
│   ├── TextBox.cpp
│   ├── Canvas.cpp
│   └── Table.cpp
├── examples/              # 示例代码目录
│   └── demo.cpp          # 基础演示
├── docs/                  # 文档目录
│   └── CODE_OF_CONDUCT.md # 行为准则
├── CMakeLists.txt        # CMake 构建配置
├── CONTRIBUTING.md       # 贡献指南
├── CHANGELOG.md          # 更新日志
├── Doxyfile              # Doxygen 配置
├── LICENSE               # MIT 许可证
└── README.md             # 项目说明

设计理念：

1. 单一职责原则 (SRP): 每个类/文件只负责一件事。
2. 依赖倒置原则 (DIP): 高层模块（如Window）不依赖低层模块（如Button），二者都依赖其抽象（Control）。
3. 开闭原则 (OCP): 通过继承Control基类，可以轻松扩展新的控件，而无需修改现有代码。
4. 一致性: 所有控件共享统一的draw()和handleEvent()接口。

🚀 核心特性

• 极致的轻量级: 核心库编译后仅 ~1.2MB，无任何外部依赖。生成的应用程序小巧玲珑。
• 清晰的模块化架构: 使用CoreTypes.h统一管理所有类型，消除重复定义，极大提升可维护性。
• 原生C++性能: 直接基于EasyX和Win32 API，提供接近原生的执行效率，内存占用极低（通常<10MB）。
• 丰富的控件库: 提供按钮、标签、文本框、表格、画布等常用控件，满足基本桌面应用需求。
• 高度可定制化: 从控件颜色、形状（矩形、圆角、圆形、椭圆）到填充模式、字体样式，均有详尽枚举支持，可轻松定制。
• 简洁直观的API: 采用经典的面向对象设计，代码即文档，学习成本极低。
• 标准项目结构: 采用标准的include/src分离结构，支持CMake构建，易于集成和使用。

⚡ 快速开始（5分钟上手）

环境要求

• 操作系统: Windows 10 或更高版本
• 编译器: 支持C++17的编译器 (如: Visual Studio 2019+)
• 图形库: EasyX (2022版本或更高，安装时请选择与您编译器匹配的版本)
• 构建工具: CMake 3.12+ (可选，推荐使用)

安装 EasyX

1. 访问 EasyX 官网 下载最新版本
2. 运行安装程序，选择与您的 Visual Studio 版本匹配的版本
3. 安装完成后，无需额外配置，星垣框架会自动链接 EasyX

方法一：使用CMake构建（推荐）

1. 克隆项目:

   git clone https://github.com/Ysm-04/StellarX.git
   cd StellarX
   

2. 生成构建系统:

   mkdir build
   cd build
   cmake ..
   

3. 编译项目:

   cmake --build .
   

4. 运行示例:

   ./examples/Demo
   

方法二：手动集成到现有项目

1. 将include和src目录复制到您的项目中
2. 配置包含路径，确保编译器可以找到include/StellarX/目录
3. 将所有.cpp文件添加到您的项目中编译

创建你的第一个星垣应用

// 只需包含这一个头文件即可使用所有功能
#include "StellarX/StellarX.h"

// 程序入口点（请使用WinMain以获得更好的兼容性）
int WINAPI WinMain(_In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, _In_ LPSTR lpCmdLine, _In_ int nShowCmd) {
    
    // 1. 创建一个640x480的窗口，背景为白色，标题为"我的应用"
    StellarX::Window mainWindow(640, 480, 0, RGB(255, 255, 255), "我的第一个星垣应用");

    // 2. 创建一个按钮 (使用智能指针管理)
    auto myButton = std::make_unique<StellarX::Button>(
        250, 200, 140, 40, // x, y, 宽度, 高度
        "点击我",           // 按钮文本
        StellarX::ButtonMode::NORMAL,
        StellarX::ControlShape::ROUND_RECTANGLE
    );

    // 3. 为按钮设置点击事件（使用Lambda表达式）
    myButton->setOnClickListener([]() {
        MessageBox(nullptr, L"Hello, 星垣！", L"问候", MB_OK | MB_ICONINFORMATION);
    });

    // 4. (可选)设置按钮样式
    myButton->textStyle.nHeight = 20;
    myButton->textStyle.color = RGB(0, 0, 128); // 深蓝色文字
    myButton->setButtonBorder(RGB(0, 128, 255)); // 蓝色边框

    // 5. 将按钮添加到窗口
    mainWindow.addControl(std::move(myButton));

    // 6. 绘制窗口
    mainWindow.draw();

    // 7. 进入消息循环，等待用户交互
    mainWindow.runEventLoop();

    return 0;
}

5. 编译并运行！ 您将看到一个带有蓝色圆角按钮的窗口，点击它将会弹出消息框。

📚 核心类型详解 (CoreTypes.h)

星垣框架的所有视觉和行为属性都通过CoreTypes.h中定义的精美枚举和结构体来控制。

枚举类型 (Enums)

枚举类型	描述	常用值
ControlShape	控件几何形状	RECTANGLE, B_RECTANGLE, ROUND_RECTANGLE, CIRCLE, ELLIPSE等
ButtonMode	按钮行为模式	NORMAL（普通）, TOGGLE（切换）, DISABLED（禁用）
TextBoxMode	文本框模式	INPUT_MODE（输入）, READONLY_MODE（只读）
FillMode	图形填充模式	SOLID（实心）, NULL（空心）, HATCHED（图案）等
FillStyle	图案填充样式	HORIZONTAL（水平线）, CROSS（十字线）等
LineStyle	边框线型	SOLID（实线）, DASH（虚线）, DOT（点线）等

结构体 (Structs)

结构体	描述
ControlText	封装了所有文本样式属性，包括字体、大小、颜色、粗体、斜体、下划线、删除线等。

使用示例：

// 创建一个复杂的文本样式
StellarX::ControlText myStyle;
myStyle.nHeight = 25; // 字体高度
myStyle.lpszFace = _T("微软雅黑"); // 字体
myStyle.color = RGB(255, 0, 0); // 红色
myStyle.nWeight = FW_BOLD; // 粗体
myStyle.bUnderline = true; // 下划线

// 应用于控件
myLabel->textStyle = myStyle;
myButton->textStyle = myStyle;

🧩 控件库大全

1. 基础控件

控件	头文件	描述	关键特性
Button	Button.h	多功能按钮	支持多种模式/形状/状态，可设置悬停/点击颜色，自定义回调
Label	Label.h	文本标签	支持背景透明/不透明，自定义字体样式
TextBox	TextBox.h	输入框/显示框	支持输入和只读模式，集成EasyX的InputBox

2. 容器控件

控件	头文件	描述
Canvas	Canvas.h	容器控件，可作为其他控件的父容器，支持自定义边框和背景。
Window	Window.h	顶级窗口，所有控件的最终容器，负责消息循环和调度。

3. 高级控件

控件	头文件	描述	关键特性
Table	Table.h	数据表格	框架功能亮点，支持分页显示、自定义表头和数据、自动计算列宽、翻页按钮。

表格控件示例：

// 创建一个表格
auto myTable = std::make_unique<StellarX::Table>(50, 50);

// 设置表头
myTable->setHeaders({ "ID", "姓名", "年龄", "职业" });

// 添加数据行
myTable->addDataRow({ "1", "张三", "25", "工程师" });
myTable->addDataRow({ "2", "李四", "30", "设计师" });
myTable->addDataRow({ "3", "王五", "28", "产品经理" });

// 设置每页显示2行
myTable->setRowsPerPage(2);

// 设置表格样式
myTable->textStyle.nHeight = 16;
myTable->setTableBorder(RGB(50, 50, 50));
myTable->setTableBackground(RGB(240, 240, 240));

// 添加到窗口
mainWindow.addControl(std::move(myTable));

🔧 高级主题与最佳实践

1. 自定义控件

您可以通过继承Control基类来创建自定义控件。只需实现draw()和handleEvent()两个纯虚函数即可。

class MyCustomControl : public StellarX::Control {
public:
    MyCustomControl(int x, int y) : Control(x, y, 100, 100) {}
    void draw() override {
        // 您的自定义绘制逻辑
        setfillcolor(RGB(255, 100, 100));
        fillrectangle(x, y, x + width, y + height);
    }
    void handleEvent(const ExMessage& msg) override {
        // 您的自定义事件处理逻辑
        if (msg.message == WM_LBUTTONDOWN && isInControl(msg.x, msg.y)) {
            // 处理点击
        }
    }
};

2. 布局管理

当前版本星垣主要采用绝对定位。对于简单布局，您可以通过计算坐标来实现。对于复杂布局，可以考虑：

• 在Canvas中嵌套控件，实现相对定位。
• 自行实现简单的流式布局或网格布局管理器。

3. 性能优化

• 脏矩形渲染: 框架内部已实现，控件状态改变时dirty=true，仅在需要时重绘。
• 图像资源: 使用IMAGE对象加载图片后，可重复使用，避免多次加载。
• 减少循环内操作: 在draw()和handleEvent()中避免进行重型计算。

⚠️ 重要限制与适用场景

星垣框架的设计目标是轻便、清晰和教学价值，因此它明确 不适用于 以下场景：

• 高性能游戏或复杂动画: 渲染基于EasyX的CPU软件渲染，性能有限。
• 需要高DPI缩放的应用: 对高DPI显示器的支持有限，界面可能显示不正确。
• 需要无障碍功能的应用: 未提供对屏幕阅读器等辅助技术的支持。
• 跨平台应用: 深度依赖Windows API和EasyX，无法直接在Linux/macOS上运行。
• 复杂的商业软件前端: 缺乏高级控件（如树形图、富文本框、选项卡、高级列表等）和成熟的自动布局管理器。

如果您需要开发上述类型的应用，请考虑使用以下成熟方案：

• Qt: 功能极其强大，跨平台，适合大型商业应用。
• wxWidgets: 原生外观，跨平台。
• Dear ImGui: 即时模式GUI，非常适合工具和调试界面。
• Web技术栈 (Electron/CEF): 适合需要Web技术的场景。

📜 许可证 (License)

本项目采用 MIT 许可证。

您可以自由地：

• 使用、复制、修改、合并、出版发行、散布、再授权及销售本框架的副本。
• 将其用于私人或商业项目。

唯一要求是：

• 请在您的项目中保留原始的版权声明。

详见项目根目录的 LICENSE 文件。

👥 贡献指南 (Contributing)

我们欢迎任何形式的贡献！如果您想为星垣框架添砖加瓦，请阅读以下指南：

1. 代码风格: 请遵循现有的Google C++规范风格（使用空格缩进，大括号换行等）。
2. 新增功能: 必须提供示例代码，并更新本README文档的相关部分。
3. 提交PR: 请确保您的代码在提交前已经过测试，并描述清楚您的更改内容和动机。
4. 问题反馈: 如果您发现了Bug或有新的想法，欢迎在GitHub提交Issue。

详细贡献指南请参阅 CONTRIBUTING.md。

🙏 致谢 (Acknowledgements)

• 感谢 EasyX Graphics Library 为这个项目提供了简单易用的图形基础，使得用C++教学GUI编程成为可能。
• 感谢所有追求简洁、高效、清晰编码理念的开发者，你们是"星垣"诞生的灵感源泉。

---

星辰大海，代码为舟。

愿 星垣 (StellarX) 能成为您探索GUI世界的一颗可靠基石，无论是用于学习、教学还是创造实用的工具。

📞 支持与反馈

如果您在使用过程中遇到问题或有任何建议：

1. 查看 示例代码 获取使用参考
2. 查阅 更新日志 了解最新变化
3. 在GitHub仓库提交Issue反馈问题

---

星垣框架 - 轻若尘埃，繁星为界