Ysm-04/StellarX
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add a new awesome feature

Browse Source
This commit is contained in:
Ysm-04
2025-09-22 15:08:49 +08:00
parent bd4588731b
commit 9f2b175b17
25 changed files with 1962 additions and 616 deletions
Download Patch File Download Diff File Expand all files Collapse all files

256
README.md
View File

@@ -1,7 +1,7 @@
# 星垣 (StellarX) GUI Framework
![Version](https://img.shields.io/badge/Version-1.0.0-brightgreen.svg) <!-- 新增版本徽章 -->
![Download](https://img.shields.io/badge/Download-1.0.0_Release-blue.svg) <!-- 新增下载徽章 -->
![Version](https://img.shields.io/badge/Version-2.0.0-brightgreen.svg)
![Download](https://img.shields.io/badge/Download-1.0.0_Release-blue.svg)
![C++](https://img.shields.io/badge/C++-17+-00599C?logo=cplusplus&logoColor=white)
![Windows](https://img.shields.io/badge/Platform-Windows-0078D6?logo=windows)
@@ -22,7 +22,7 @@
星垣框架采用经典的**面向对象**和**模块化**设计，项目结构清晰规范：
```
```markdown
StellarX/
├── include/ # 头文件目录
│ └── StellarX/ # 框架头文件
@@ -34,6 +34,8 @@ StellarX/
│ ├── Label.h # 标签控件
│ ├── TextBox.h # 文本框控件
│ ├── Canvas.h # 画布容器
│ ├── Dialog.h # 对话框控件（v2.0.0新增）
│ ├── MessageBox.h # 消息框工厂（v2.0.0新增）
│ └── Table.h # 表格控件
├── src/ # 源文件目录
│ ├── Control.cpp
@@ -42,7 +44,9 @@ StellarX/
│ ├── Label.cpp
│ ├── TextBox.cpp
│ ├── Canvas.cpp
│ └── Table.cpp
│ ├── Table.cpp
│ ├── Dialog.cpp # v2.0.0新增
│ └── MessageBox.cpp # v2.0.0新增
├── examples/ # 示例代码目录
│ └── demo.cpp # 基础演示
├── docs/ # 文档目录
@@ -56,6 +60,7 @@ StellarX/
```
**设计理念：**
1. **单一职责原则 (SRP)**: 每个类/文件只负责一件事。
2. **依赖倒置原则 (DIP)**: 高层模块（如`Window`）不依赖低层模块（如`Button`），二者都依赖其抽象（`Control`）。
3. **开闭原则 (OCP)**: 通过继承`Control`基类，可以轻松扩展新的控件，而无需修改现有代码。
@@ -66,10 +71,12 @@ StellarX/
- **极致的轻量级**: 核心库编译后仅 ~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分钟上手）
@@ -126,43 +133,55 @@ StellarX/
#include "StellarX.h"
// 程序入口点（请使用WinMain以获得更好的兼容性）
int WINAPI WinMain(_In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, _In_ LPSTR lpCmdLine, _In_ int nShowCmd) {
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), "我的第一个星垣应用");
// 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
);
// 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) {
// 用户点击了确定按钮
}
});
// 3. 为按钮设置点击事件（使用Lambda表达式）
myButton->setOnClickListener([]() {
MessageBox(nullptr, "Hello, 星垣！", "问候", MB_OK | MB_ICONINFORMATION);
});
// 4. (可选)设置按钮样式
myButton->textStyle.nHeight = 20;
myButton->textStyle.color = RGB(0, 0, 128); // 深蓝色文字
myButton->setButtonBorder(RGB(0, 128, 255)); // 蓝色边框
// 4. (可选)设置按钮样式
myButton->textStyle.nHeight = 20;
myButton->textStyle.color = RGB(0, 0, 128); // 深蓝色文字
myButton->setButtonBorder(RGB(0, 128, 255)); // 蓝色边框
// 5. 将按钮添加到窗口
mainWindow.addControl(std::move(myButton));
// 5. 将按钮添加到窗口
mainWindow.addControl(std::move(myButton));
// 6. 绘制窗口
mainWindow.draw();
// 6. 绘制窗口
mainWindow.draw();
// 7. 进入消息循环，等待用户交互
mainWindow.runEventLoop();
// 7. 进入消息循环，等待用户交互
mainWindow.runEventLoop();
return 0;
return 0;
}
```
5. **编译并运行！** 您将看到一个带有蓝色圆角按钮的窗口，点击它将会弹出消息框。
1. **编译并运行！** 您将看到一个带有蓝色圆角按钮的窗口，点击它将会弹出消息框。
## 📚 核心类型详解 (`CoreTypes.h`)
@@ -170,23 +189,29 @@ int WINAPI WinMain(_In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, _
### 枚举类型 (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`（点线）等 |
| 枚举类型 | 描述 | 常用值 |
| :--------------------- | :----------- | :----------------------------------------------------------- |
| **`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`** | 封装了所有文本样式属性，包括字体、大小、颜色、粗体、斜体、下划线、删除线等。 |
| 结构体 | 描述 |
| :----------------- | :----------------------------------------------------------- |
| **`ControlText`** | 封装了所有文本样式属性，包括字体、大小、颜色、粗体、斜体、下划线、删除线等。 |
| **`RouRectangle`** | 定义圆角矩形的圆角椭圆尺寸，包含宽度和高度属性。 |
**使用示例：**
```cpp
cpp
```c++
// 创建一个复杂的文本样式
StellarX::ControlText myStyle;
myStyle.nHeight = 25; // 字体高度
@@ -200,6 +225,8 @@ myLabel->textStyle = myStyle;
myButton->textStyle = myStyle;
```
## 🧩 控件库大全
### 1. 基础控件
@@ -219,22 +246,26 @@ myButton->textStyle = myStyle;
### 3. 高级控件
| 控件 | 头文件 | 描述 | 关键特性 |
| :-------- | :-------- | :------- | :----------------------------------------------------------- |
| **Table** | `Table.h` | 数据表格 | **框架功能亮点**，支持分页显示、自定义表头和数据、自动计算列宽、翻页按钮。 |
| 控件 | 头文件 | 描述 | 关键特性 |
| :--------- | :--------- | :------- | :----------------------------------------------------------- |
| **Table** | `Table.h` | 数据表格 | **框架功能亮点**，支持分页显示、自定义表头和数据、自动计算列宽、翻页按钮。 |
| **Dialog** | `Dialog.h` | 对话框类 | 实现完整的对话框功能，支持多种按钮组合和异步结果回调。自动处理布局、背景保存恢复和生命周期管理。 |
**表格控件示例：**
```cpp
cpp
```c++
// 创建一个表格
auto myTable = std::make_unique<StellarX::Table>(50, 50);
auto myTable = std::make_unique<Table>(50, 50);
// 设置表头
myTable->setHeaders({ "ID", "姓名", "年龄", "职业" });
// 添加数据行
myTable->addDataRow({ "1", "张三", "25", "工程师" });
myTable->addDataRow({ "2", "李四", "30", "设计师" });
myTable->addDataRow({ "3", "王五", "28", "产品经理" });
myTable->setData({ "1", "张三", "25", "工程师" });
myTable->setData({ "2", "李四", "30", "设计师" });
myTable->setData({ "3", "王五", "28", "产品经理" });
// 设置每页显示2行
myTable->setRowsPerPage(2);
@@ -242,71 +273,140 @@ myTable->setRowsPerPage(2);
// 设置表格样式
myTable->textStyle.nHeight = 16;
myTable->setTableBorder(RGB(50, 50, 50));
myTable->setTableBackground(RGB(240, 240, 240));
myTable->setTableBk(RGB(240, 240, 240));
// 添加到窗口
mainWindow.addControl(std::move(myTable));
```
### 4. 静态工厂类
| 控件 | 头文件 | 描述 | 关键特性 |
| :------------- | :------------- | :--------------- | :----------------------------------------------------------- |
| **MessageBox** | `MessageBox.h` | 对话框的工厂调用 | 静态方法调用，无需实例化，自动处理模态和非模态的逻辑差异集成到窗口的对话框管理系统中提供去重机制防止重复对话框 |
**消息框使用示例：**
cpp
```c++
// 模态消息框（阻塞直到关闭）
auto result = StellarX::MessageBox::ShowModal(
mainWindow,
"确认要执行此操作吗？",
"确认",
StellarX::MessageBoxType::YesNo
);
if (result == StellarX::MessageBoxResult::Yes)
{
// 用户选择了"是"
}
// 非模态消息框（异步回调）
StellarX::MessageBox::ShowAsync(
mainWindow,
"操作已完成",
"提示",
StellarX::MessageBoxType::OK,
[](StellarX::MessageBoxResult result) {
// 异步处理结果
}
);
```
## 🔧 高级主题与最佳实践
### 1. 自定义控件
您可以通过继承`Control`基类来创建自定义控件。只需实现`draw()`和`handleEvent()`两个纯虚函数即可。
```cpp
class MyCustomControl : public StellarX::Control {
cpp
```c++
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();
}
void handleEvent(const ExMessage& msg) override {
bool handleEvent(const ExMessage& msg) override {
// 您的自定义事件处理逻辑
if (msg.message == WM_LBUTTONDOWN && isInControl(msg.x, msg.y)) {
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上运行。
- **复杂的商业软件前端**: 缺乏高级控件（如树形图、富文本框、选项卡、高级列表等）和成熟的自动布局管理器。
- **高性能游戏或复杂动画**: 渲染基于EasyX的CPU软件渲染，性能有限。
- **需要高DPI缩放的应用**: 对高DPI显示器的支持有限，界面可能显示不正确。
- **需要无障碍功能的应用**: 未提供对屏幕阅读器等辅助技术的支持。
- **跨平台应用**: 深度依赖Windows API和EasyX，无法直接在Linux/macOS上运行。
- **复杂的商业软件前端**: 缺乏高级控件（如树形图、富文本框、选项卡、高级列表等）和成熟的自动布局管理器。
**如果您需要开发上述类型的应用，请考虑使用以下成熟方案：**
- **Qt**: 功能极其强大，跨平台，适合大型商业应用。
- **wxWidgets**: 原生外观，跨平台。
- **Dear ImGui**: 即时模式GUI，非常适合工具和调试界面。
- **Web技术栈 (Electron/CEF)**: 适合需要Web技术的场景。
- **Qt**: 功能极其强大，跨平台，适合大型商业应用。
- **wxWidgets**: 原生外观，跨平台。
- **Dear ImGui**: 即时模式GUI，非常适合工具和调试界面。
- **Web技术栈 (Electron/CEF)**: 适合需要Web技术的场景。
## 📜 许可证 (License)
本项目采用 **MIT 许可证**。
您可以自由地：
- 使用、复制、修改、合并、出版发行、散布、再授权及销售本框架的副本。
- 将其用于私人或商业项目。
- 使用、复制、修改、合并、出版发行、散布、再授权及销售本框架的副本。
- 将其用于私人或商业项目。
唯一要求是：
- 请在您的项目中保留原始的版权声明。
- 请在您的项目中保留原始的版权声明。
详见项目根目录的 [LICENSE](LICENSE) 文件。
@@ -314,19 +414,19 @@ public:
我们欢迎任何形式的贡献！如果您想为星垣框架添砖加瓦，请阅读以下指南：
1. **代码风格**: 请遵循现有的Google C++规范风格（使用空格缩进，大括号换行等）。
2. **新增功能**: 必须提供**示例代码**，并更新本README文档的相关部分。
3. **提交PR**: 请确保您的代码在提交前已经过测试，并描述清楚您的更改内容和动机。
4. **问题反馈**: 如果您发现了Bug或有新的想法，欢迎在GitHub提交Issue。
1. **代码风格**: 请遵循现有的Google C++规范风格（使用空格缩进，大括号换行等）。
2. **新增功能**: 必须提供**示例代码**，并更新本README文档的相关部分。
3. **提交PR**: 请确保您的代码在提交前已经过测试，并描述清楚您的更改内容和动机。
4. **问题反馈**: 如果您发现了Bug或有新的想法，欢迎在GitHub提交Issue。
详细贡献指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 🙏 致谢 (Acknowledgements)
- 感谢 [EasyX Graphics Library](https://easyx.cn/) 为这个项目提供了简单易用的图形基础，使得用C++教学GUI编程成为可能。
- 感谢所有追求**简洁、高效、清晰**编码理念的开发者，你们是"星垣"诞生的灵感源泉。
- 感谢 [EasyX Graphics Library](https://easyx.cn/) 为这个项目提供了简单易用的图形基础，使得用C++教学GUI编程成为可能。
- 感谢所有追求**简洁、高效、清晰**编码理念的开发者，你们是"星垣"诞生的灵感源泉。
---
------
**星辰大海，代码为舟。**
@@ -335,9 +435,11 @@ public:
## 📞 支持与反馈
如果您在使用过程中遇到问题或有任何建议：
1. 查看 [示例代码](examples/) 获取使用参考
2. 查阅 [更新日志](CHANGELOG.md) 了解最新变化
3. 在GitHub仓库提交Issue反馈问题
---
------
*星垣框架 - 轻若尘埃，繁星为界*