337 lines
14 KiB
Markdown
337 lines
14 KiB
Markdown
# 星垣 (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](https://easyx.cn/) (2022版本或更高，安装时请选择与您编译器匹配的版本)
|
||
- **构建工具**: CMake 3.12+ (可选，推荐使用)
|
||
|
||
### 安装 EasyX
|
||
1. 访问 [EasyX 官网](https://easyx.cn/) 下载最新版本
|
||
2. 运行安装程序，选择与您的 Visual Studio 版本匹配的版本
|
||
3. 安装完成后，无需额外配置，星垣框架会自动链接 EasyX
|
||
|
||
### 方法一：使用CMake构建（推荐）
|
||
|
||
1. **克隆项目**:
|
||
```bash
|
||
git clone https://github.com/Ysm-04/StellarX.git
|
||
cd StellarX
|
||
```
|
||
|
||
2. **生成构建系统**:
|
||
```bash
|
||
mkdir build
|
||
cd build
|
||
cmake ..
|
||
```
|
||
|
||
3. **编译项目**:
|
||
```bash
|
||
cmake --build .
|
||
```
|
||
|
||
4. **运行示例**:
|
||
```bash
|
||
./examples/Demo
|
||
```
|
||
|
||
### 方法二：手动集成到现有项目
|
||
|
||
1. **将include和src目录复制**到您的项目中
|
||
2. **配置包含路径**，确保编译器可以找到`include/StellarX/`目录
|
||
3. **将所有.cpp文件**添加到您的项目中编译
|
||
|
||
### 创建你的第一个星垣应用
|
||
|
||
```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`** | 封装了所有文本样式属性，包括字体、大小、颜色、粗体、斜体、下划线、删除线等。 |
|
||
|
||
**使用示例：**
|
||
```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` | 数据表格 | **框架功能亮点**，支持分页显示、自定义表头和数据、自动计算列宽、翻页按钮。 |
|
||
|
||
**表格控件示例：**
|
||
```cpp
|
||
// 创建一个表格
|
||
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()`两个纯虚函数即可。
|
||
|
||
```cpp
|
||
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](LICENSE) 文件。
|
||
|
||
## 👥 贡献指南 (Contributing)
|
||
|
||
我们欢迎任何形式的贡献！如果您想为星垣框架添砖加瓦，请阅读以下指南：
|
||
|
||
1. **代码风格**: 请遵循现有的Google C++规范风格（使用空格缩进，大括号换行等）。
|
||
2. **新增功能**: 必须提供**示例代码**，并更新本README文档的相关部分。
|
||
3. **提交PR**: 请确保您的代码在提交前已经过测试，并描述清楚您的更改内容和动机。
|
||
4. **问题反馈**: 如果您发现了Bug或有新的想法，欢迎在GitHub提交Issue。
|
||
|
||
详细贡献指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||
|
||
## 🙏 致谢 (Acknowledgements)
|
||
|
||
- 感谢 [EasyX Graphics Library](https://easyx.cn/) 为这个项目提供了简单易用的图形基础，使得用C++教学GUI编程成为可能。
|
||
- 感谢所有追求**简洁、高效、清晰**编码理念的开发者，你们是"星垣"诞生的灵感源泉。
|
||
|
||
---
|
||
|
||
**星辰大海，代码为舟。**
|
||
|
||
愿 `星垣 (StellarX)` 能成为您探索GUI世界的一颗可靠基石，无论是用于学习、教学还是创造实用的工具。
|
||
|
||
## 📞 支持与反馈
|
||
|
||
如果您在使用过程中遇到问题或有任何建议：
|
||
1. 查看 [示例代码](examples/) 获取使用参考
|
||
2. 查阅 [更新日志](CHANGELOG.md) 了解最新变化
|
||
3. 在GitHub仓库提交Issue反馈问题
|
||
|
||
---
|
||
*星垣框架 - 轻若尘埃，繁星为界* |