Ysm-04/StellarX

Fork 0

Files

Ysm-04 95149238e2 feat: add a new awesome feature

2025-10-03 16:34:58 +08:00

19 KiB

Raw Blame History

星垣 (StellarX) GUI Framework

English document

「繁星为界，轻若尘埃」 —— 一个为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       # 画布容器
│       ├── Dialog.h       # 对话框控件（v2.0.0新增）
│       ├── MessageBox.h   # 消息框工厂（v2.0.0新增）
│       └── Table.h        # 表格控件
├── src/                   # 源文件目录
│   ├── Control.cpp
│   ├── Button.cpp
│   ├── Window.cpp
│   ├── Label.cpp
│   ├── TextBox.cpp
│   ├── Canvas.cpp
│   ├── Table.cpp     
│   ├── Dialog.cpp        # v2.0.0新增
│   └── MessageBox.cpp    # v2.0.0新增
├── examples/              # 示例代码目录
│   └── demo.cpp          # 基础演示
├── docs/                  # 文档目录
│   └── CODE_OF_CONDUCT.md # 行为准则
├── CMakeLists.txt        # CMake 构建配置
├── CONTRIBUTING.md       # 贡献指南
├── CHANGELOG.md          # 更新日志
├── Doxyfile              # Doxygen 配置
├── LICENSE               # MIT 许可证
└── README.md             # 项目说明

设计理念：

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

🚀 核心特性

极致的轻量级: 核心库编译后仅 ~1.2MB，无任何外部依赖。生成的应用程序小巧玲珑。
清晰的模块化架构: 使用CoreTypes.h统一管理所有类型，消除重复定义，极大提升可维护性。
原生C++性能: 直接基于EasyX和Win32 API，提供接近原生的执行效率，内存占用极低（通常<10MB）。
完整的控件体系: 按钮（Button）、标签（Label）、文本框（TextBox）、画布（Canvas）、表格（Table）、对话框（Dialog）与消息框工厂（MessageBox）。
高度可定制化: 从控件颜色、形状（矩形、圆角、圆形、椭圆）到填充模式、字体样式，均有详尽枚举支持，可轻松定制。
简洁直观的API: 采用经典的面向对象设计，代码即文档，学习成本极低。
标准项目结构: 采用标准的include/src分离结构，支持CMake构建，易于集成和使用。
增强的事件系统: v2.0.0引入事件消费机制，所有handleEvent方法返回bool表示是否消费事件，支持更精细的事件传播控制。
对话框系统: 新增完整的对话框支持，包括模态和非模态对话框，自动处理背景保存和恢复。

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

🎯 最新版本下载 从 GitHub Releases 下载预编译的库文件和头文件，即可快速集成到你的项目中。

环境要求

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

安装 EasyX

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

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

克隆项目:

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

生成构建系统:
```
mkdir build
cd build
cmake ..
```
编译项目:
```
cmake --build .
```
运行示例:
```
./examples/Demo
```

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

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

创建你的第一个星垣应用

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

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

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

    // 3. 为按钮设置点击事件（使用Lambda表达式）
    myButton->setOnClickListener([&mainWindow]() {
        // 使用消息框工厂创建模态对话框
        auto result = StellarX::MessageBox::ShowModal(
            mainWindow, 
            "欢迎使用星垣GUI\r\n作者：我在人间做废物", 
            "问候", 
            StellarX::MessageBoxType::OKCancel
        );
           // 处理对话框结果
        if (result == StellarX::MessageBoxResult::OK) {
            // 用户点击了确定按钮
        }
    });
        
     

    // 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;
}

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

📚 核心类型详解 (`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`（点线）等
`MessageBoxType`	消息框类型	`OK`, `OKCancel`, `YesNo`, `YesNoCancel`, `RetryCancel`, `AbortRetryIgnore`
`MessageBoxResult`	消息框结果	`OK`, `Cancel`, `Yes`, `No`, `Abort`, `Retry`, `Ignore`

结构体 (Structs)

结构体	描述
`ControlText`	封装了所有文本样式属性，包括字体、大小、颜色、粗体、斜体、下划线、删除线等。
`RouRectangle`	定义圆角矩形的圆角椭圆尺寸，包含宽度和高度属性。

使用示例：

cpp

// 创建一个复杂的文本样式
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`	数据表格	框架功能亮点，支持分页显示、自定义表头和数据、自动计算列宽、翻页按钮。
Dialog	`Dialog.h`	对话框类	实现完整的对话框功能，支持多种按钮组合和异步结果回调。自动处理布局、背景保存恢复和生命周期管理。

表格控件示例：

cpp

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

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

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

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

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

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

4. 静态工厂类

控件	头文件	描述	关键特性
MessageBox	`MessageBox.h`	对话框的工厂调用	静态方法调用，无需实例化，自动处理模态和非模态的逻辑差异集成到窗口的对话框管理系统中提供去重机制防止重复对话框

消息框使用示例：

cpp

// 模态消息框（阻塞直到关闭）
auto result = StellarX::MessageBox::ShowModal(
    mainWindow, 
    "确认要执行此操作吗？", 
    "确认", 
    StellarX::MessageBoxType::YesNo
);

if (result == StellarX::MessageBoxResult::Yes)
{
    // 用户选择了"是"
}

// 非模态消息框（异步回调）
StellarX::MessageBox::ShowAsync(
    mainWindow,
    "操作已完成", 
    "提示", 
    StellarX::MessageBoxType::OK,
    [](StellarX::MessageBoxResult result) {
        // 异步处理结果
    }
);

示例

寄存器查看器 (≈450 行) — 一个基于 StellarX 实现的交互式 32 位寄存器可视化工具（支持位取反、左/右移、十六进制/十进制转换、带有符号/无符号切换、二进制分组显示）。
路径：examples/register-viewer/

🔧 高级主题与最佳实践

1. 自定义控件

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

cpp

class MyCustomControl : public Control {
public:
    MyCustomControl(int x, int y) : Control(x, y, 100, 100) {}
    
    void draw() override {
        saveStyle();
        // 您的自定义绘制逻辑
        setfillcolor(RGB(255, 100, 100));
        fillrectangle(x, y, x + width, y + height);
        restoreStyle();
    }
    
    bool handleEvent(const ExMessage& msg) override {
        // 您的自定义事件处理逻辑
        if (msg.message == WM_LBUTTONDOWN && 
            msg.x > x && msg.x < x + width && 
            msg.y > y && msg.y < y + height) {
            // 处理点击
            return true; // 事件已消费
        }
        return false; // 事件未消费
    }
    
    bool IsVisible() const override { return true; }
    bool model() const override { return false; }
};

2. 布局管理

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

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

3. 性能优化

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

4. 对话框使用技巧

模态对话框: 使用ShowModal方法，会阻塞当前线程直到对话框关闭，适合需要用户确认的重要操作。
非模态对话框: 使用ShowAsync方法，不会阻塞主线程，适合提示性信息或后台任务。
对话框去重: 框架内置了非模态对话框去重机制，防止同一消息的多个对话框同时出现。

⚠️ 重要限制与适用场景

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

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

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

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

📜 许可证 (License)

本项目采用 MIT 许可证。

您可以自由地：

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

唯一要求是：

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

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

👥 贡献指南 (Contributing)

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

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

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

🙏 致谢 (Acknowledgements)

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

星辰大海，代码为舟。

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

📞 支持与反馈

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

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

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

19 KiB Raw Blame History Unescape Escape