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-10-27 16:29:43 +08:00
parent dcf13895da
commit c4852d080f
5 changed files with 442 additions and 696 deletions
Download Patch File Download Diff File Expand all files Collapse all files

565
README.md
View File

@@ -5,11 +5,10 @@
------
![GitHub all releases](https://img.shields.io/github/downloads/Ysm-04/StellarX/total)
[![Star GitHub Repo](https://img.shields.io/github/stars/Ysm-04/StellarX.svg?style=social&label=Star%20This%20Repo)](https://github.com/Ysm-04/StellarX)
![Version](https://img.shields.io/badge/Version-2.0.0-brightgreen.svg)
![Download](https://img.shields.io/badge/Download-2.0.0_Release-blue.svg)
![Version](https://img.shields.io/badge/Version-2.1.0-brightgreen.svg)
![Download](https://img.shields.io/badge/Download-2.1.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)
@@ -18,438 +17,306 @@
![Architecture](https://img.shields.io/badge/Architecture-Modular%20OOP-brightgreen)
![CMake](https://img.shields.io/badge/Build-CMake-064F8C?logo=cmake)
> **「繁星为界，轻若尘埃」** —— 一个为Windows平台打造的、极致轻量级、高度模块化的C++原生GUI框架。
> **「繁星为界，轻若尘埃」** —— 一个为 Windows 平台打造的、极致轻量级、高度模块化的 C++ 原生 GUI 框架。
`星垣 (StellarX)` 诞生于对现代GUI框架"过度臃肿"的反抗。它拒绝动辄数百MB的依赖、漫长的编译时间和复杂的学习曲线，选择回归本质：用最精简的代码、最清晰的架构和最高的效率，解决桌面应用开发的核心需求。
`星垣 (StellarX)` 反对臃肿，拒绝动辄数百 MB 的依赖、漫长编译与高门槛学习曲线，回归本质：以精简代码、清晰架构与高效率，解决桌面应用开发的核心需求。
它是一个**纯粹的教学级、工具级框架**，旨在让开发者深入理解GUI原理，并快速构建轻量级Windows工具。
这是一个**教学级、工具级**框架，帮助开发者深入理解 GUI 原理，并快速构建轻量工具。
---
## 🆕 v2.1.0 有何变化
- **中英文双语 API文档**
- 文档详细介绍了每个类，以及API描述、功能和需要注意的地方，详细介绍了每个控件
- **窗口可拉伸/最大化补强（基于 EasyX + Win32）**
子类化窗口过程，处理 `WM_GETMINMAXINFO / WM_SIZE / WM_EXITSIZEMOVE / WM_ERASEBKGND / WM_PAINT`，启用 `WS_THICKFRAME | WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_CLIPCHILDREN | WS_CLIPSIBLINGS`。在 `WM_PAINT` 期进行**整窗背景绘制**（纯色/图片），彻底消除黑边与最大化“残影”；合并拉伸为**一次性重绘**。
- **布局管理器（第一阶段）**
`Canvas` 支持 `LayoutKind::{Absolute, HBox, VBox, Grid(预留), Flow(预留), Stack(预留)}` 与 `LayoutParams`（边距、固定尺寸、`weight`、`Align{Start,Center,End,Stretch}`）；实装 **HBox/VBox** 自动布局（容器仍绝对定位，可嵌套）。
- **选项卡（Tabs）雏形**
页签条与页面容器分离；透明主题下使用**背景快照**避免叠影。
- **按钮文本单行截断（MBCS：中/英分治）**
基于像素宽度阈值的 `...` 截断，杜绝半字符。
- **悬停提示（Tooltip）**
以 `Label` 实现，支持延时出现、自动隐藏；控件级**背景快照/恢复**。
详见 `CHANGELOG.md / CHANGELOG.en.md`。
---
## 📦 项目结构与设计哲学
星垣框架采用经典的**面向对象**和**模块化**设计，项目结构清晰规范：
星垣采用经典 **OOP** 与 **模块化** 设计，结构清晰：
```markdown
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/ # 源文件目录
├── 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 # 项目说明
│ ├── Table.cpp
│ ├── Dialog.cpp # v2.0.0
│ └── MessageBox.cpp # v2.0.0
├── examples/
│ └── demo.cpp
├── docs/
│ └── CODE_OF_CONDUCT.md
├── CMakeLists.txt
├── CONTRIBUTING.md
├── CHANGELOG.md
├── CHANGELOG.en.md
├── Doxyfile
├── LICENSE
├──API 文档.md
├──API Documentation.en.md
└── README.md
```
**设计理念：**
1. **单一职责原则 (SRP)**: 每个类/文件只负责一件事。
2. **依赖倒置原则 (DIP)**: 高层模块（如`Window`）不依赖低层模块（如`Button`），二者都依赖其抽象（`Control`）。
3. **开闭原则 (OCP)**: 通过继承`Control`基类，可以轻松扩展新的控件，而无需修改现有代码。
4. **一致性**: 所有控件共享统一的`draw()`和`handleEvent()`接口。
1. **单一职责（SRP）**：每个类/文件只做一件事。
2. **依赖倒置（DIP）**：高层模块依赖抽象（`Control`），而非具体控件。
3. **开闭原则（OCP）**：继承 `Control` 可扩展新控件，无需修改既有代码。
4. **一致性**：所有控件统一 `draw()` / `handleEvent()` 接口。
## 🚀 核心特性
- **极致的轻量级**: 核心库编译后仅 ~12MB，无任何外部依赖。生成的应用程序小巧玲珑。
- **清晰的模块化架构**: 使用`CoreTypes.h`统一管理所有类型，消除重复定义，极大提升可维护性。
- **原生C++性能**: 直接基于EasyX和Win32 API，提供接近原生的执行效率，内存占用极低（通常<10MB）。
- **完整的控件体系**: 按钮（Button）、标签（Label）、文本框（TextBox）、画布（Canvas）、表格（Table）、对话框（Dialog）与消息框工厂（MessageBox）。
- **高度可定制化**: 从控件颜色、形状（矩形、圆角、圆形、椭圆）到填充模式、字体样式，均有详尽枚举支持，可轻松定制。
- **简洁直观的API**: 采用经典的面向对象设计，代码即文档，学习成本极低。
- **标准项目结构**: 采用标准的include/src分离结构，支持CMake构建，易于集成和使用。
- **增强的事件系统**: v2.0.0引入事件消费机制，所有`handleEvent`方法返回`bool`表示是否消费事件，支持更精细的事件传播控制。
- **对话框系统**: 新增完整的对话框支持，包括模态和非模态对话框，自动处理背景保存和恢复。
- **极致轻量**：除 EasyX 外无外部重量级依赖。
- **模块清晰**：`CoreTypes.h` 统一类型与枚举。
- **原生性能**：EasyX + Win32，执行高效、内存低占用（常见 <10MB）。
- **控件齐全**：Button、Label、TextBox、Canvas、Table、Dialog、MessageBox。
- **高度自定义**：颜色、形状（矩形/圆角/圆/椭圆）、填充、字体等皆有枚举。
- **简单直观 API**：OOP 设计，代码即文档。
- **标准工程结构**：include/src 分离，支持 CMake。
- **增强事件系统**：`handleEvent` 返回是否消费（自 v2.0.0）。
- **对话框系统**：支持模态/非模态，自动背景保存与恢复。
## ⚡ 快速开始（5分钟上手）
------
> **🎯 最新版本下载**
> 从 [GitHub Releases](https://github.com/Ysm-04/StellarX/releases/latest) 下载预编译的库文件和头文件，即可快速集成到你的项目中。
## ⚡ 快速开始（5 分钟上手）
> 从 [Releases](https://github.com/Ysm-04/StellarX/releases/latest) 获取预编译包。
### 环境要求
- **操作系统**: Windows 10 或更高版本
- **编译器**: 支持C++17的编译器 (如: **Visual Studio 2019+**)
- **图形库**: [EasyX](https://easyx.cn/) (2022版本或更高，安装时请选择与您编译器匹配的版本)
- **构建工具**: CMake 3.12+ (可选，推荐使用)
- **系统**：Windows 10+
- **编译器**：C++17（如 VS 2019+）
- **图形库**： [EasyX](https://easyx.cn/) 2022+（与编译器匹配）
- **构建**：CMake 3.12+（可选）
### 安装 EasyX
1. 访问 [EasyX 官网](https://easyx.cn/) 下载最新版本
2. 运行安装程序，选择与您的 Visual Studio 版本匹配的版本
3. 安装完成后，无需额外配置，星垣框架会自动链接 EasyX
### 方法一：使用CMake构建（推荐）
1. 下载 EasyX 最新版
2. 按 VS 版本安装匹配组件
3. 框架会自动链接，无需额外配置
1. **克隆项目**:
```bash
git clone https://github.com/Ysm-04/StellarX.git
cd StellarX
```
### CMake 构建（推荐）
2. **生成构建系统**:
```bash
mkdir build
cd build
cmake ..
```
```
git clone https://github.com/Ysm-04/StellarX.git
cd StellarX
mkdir build && cd build
cmake ..
cmake --build .
./examples/Demo
```
3. **编译项目**:
```bash
cmake --build .
```
### 手动集成
4. **运行示例**:
```bash
./examples/Demo
```
- 拷贝 `include` 与 `src`
- 配置头文件搜索路径：`include/StellarX/`
- 将全部 `.cpp` 加入工程
### 方法二：手动集成到现有项目
### 第一个可拉伸窗口
1. **将include和src目录复制**到您的项目中
2. **配置包含路径**，确保编译器可以找到`include/StellarX/`目录
3. **将所有.cpp文件**添加到您的项目中编译
### 创建你的第一个星垣应用
```cpp
// 只需包含这一个头文件即可使用所有功能
```c++
#include "StellarX.h"
// 程序入口点（请使用WinMain以获得更好的兼容性）
int WINAPI WinMain(_In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, _In_ LPSTR lpCmdLine, _In_ int nShowCmd)
int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
{
// 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. 绘制窗口
//默认启动拉伸，当前尺寸为最小尺寸
Window mainWindow(800, 600, 0, RGB(255,255,255), "我的星垣应用");
mainWindow.draw();
// 7. 进入消息循环，等待用户交互
mainWindow.runEventLoop();
// 添加你的控件...
// mainWindow.addControl(std::move(btn));
mainWindow.runEventLoop();
return 0;
}
```
1. **编译并运行！** 您将看到一个带有蓝色圆角按钮的窗口，点击它将会弹出消息框。
> 实现要点：在 `WM_PAINT` 期进行**整窗背景绘制**（纯色/图片），并配合 EasyX 批量绘制抑制频闪与黑边。
## 📚 核心类型详解 (`CoreTypes.h`)
------
星垣框架的所有视觉和行为属性都通过`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` |
| 枚举 | 描述 | 常用值 |
| ------------------ | ---------- | ------------------------------------------------------------ |
| `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`, ... |
| `MessageBoxResult` | 结果 | `OK`, `Cancel`, `Yes`, `No`, `Abort`, `Retry`, `Ignore` |
### 结构体 (Structs)
### 结构体
| 结构体 | 描述 |
| :----------------- | :----------------------------------------------------------- |
| **`ControlText`** | 封装了所有文本样式属性，包括字体、大小、颜色、粗体、斜体、下划线、删除线等。 |
| **`RouRectangle`** | 定义圆角矩形的圆角椭圆尺寸，包含宽度和高度属性。 |
| 结构体 | 描述 |
| -------------- | -------------------------------------- |
| `ControlText` | 字体/字号/颜色/粗体/斜体/下划线/删除线 |
| `RouRectangle` | 圆角矩形的角部椭圆尺寸 |
**使用示例：**
------
cpp
## 🧩 控件库
### 1) 基础控件
| 控件 | 头文件 | 描述 | 关键点 |
| ------- | ----------- | ----------- | ------------------------------------------------------------ |
| Button | `Button.h` | 多功能按钮 | 形状/模式、悬停/点击色、回调，**单行截断** + **Tooltip**（v2.1.0） |
| Label | `Label.h` | 文本标签 | 透明/不透明背景，自定义字体 |
| TextBox | `TextBox.h` | 输入/显示框 | 输入/只读，整合 EasyX `InputBox` |
### 2) 容器控件
| 控件 | 头文件 | 描述 |
| ------ | ---------- | ------------------------------------------------------------ |
| Canvas | `Canvas.h` | 父容器，自定义边框/背景，**内置 HBox/VBox 自动布局**（v2.1.0） |
| Window | `Window.h` | 顶层容器，消息循环与分发，**可拉伸**（v2.1.0） |
### 3) 高级控件
| 控件 | 头文件 | 描述 | 关键点 |
| ------ | ---------- | -------- | --------------------------------------------------------- |
| Table | `Table.h` | 数据表格 | 分页/表头/列宽自动、翻页控件重叠/透明叠影已修复（v2.1.0） |
| Dialog | `Dialog.h` | 对话框 | 支持模态/非模态，自动布局与背景保存/恢复 |
### 4) 静态工厂
| 控件 | 头文件 | 描述 | 关键点 |
| ---------- | -------------- | ---------- | ----------------------------------- |
| MessageBox | `MessageBox.h` | 消息框工厂 | 静态 API；支持模态/非模态；内置去重 |
------
## 📐 布局管理（HBox/VBox）
- **容器级**：`Canvas::layout.kind = HBox / VBox / Absolute (默认)`；可选容器 `padding`。
- **子项级**：`LayoutParams`
- `margin{L,R,T,B}`
- `fixedW/fixedH`（`-1` 表示沿用控件当前尺寸）
- `weight`（主轴分配权重：HBox→宽、VBox→高）
- `alignX/alignY` = `Start/Center/End/Stretch`（用于次轴方向对齐/拉伸）
**示例**（三列水平自适应，整体垂直拉伸）：
```c++
// 创建一个复杂的文本样式
StellarX::ControlText myStyle;
myStyle.nHeight = 25; // 字体高度
myStyle.lpszFace = _T("微软雅黑"); // 字体
myStyle.color = RGB(255, 0, 0); // 红色
myStyle.nWeight = FW_BOLD; // 粗体
myStyle.bUnderline = true; // 下划线
Canvas row(20, 20, 760, 120);
row.layout.kind = LayoutKind::HBox;
// 应用于控件
myLabel->textStyle = myStyle;
myButton->textStyle = myStyle;
auto mk = [](int w, int h, float weight){
auto c = std::make_unique<Control>(0,0,w,h);
c->layout.marginL = 8; c->layout.marginR = 8;
c->layout.alignY = LayoutParams::Stretch;
c->layout.weight = weight;
return c;
};
row.addControl(mk(100,40, 1.f));
row.addControl(mk(100,40, 2.f));
row.addControl(mk(100,40, 1.f));
```
------
## 🗂 选项卡（Tabs，早期版本）
## 🧩 控件库大全
- 页签条（按钮组） + 页面容器（`Canvas`）
- 透明主题：页面区域**背景快照**切换，避免叠影
- API 草图：`tabs.addPage(title, canvasPtr); tabs.setActive(index);`
### 1. 基础控件
------
| 控件 | 头文件 | 描述 | 关键特性 |
| :---------- | :---------- | :------------ | :------------------------------------------------------ |
| **Button** | `Button.h` | 多功能按钮 | 支持多种模式/形状/状态，可设置悬停/点击颜色，自定义回调 |
| **Label** | `Label.h` | 文本标签 | 支持背景透明/不透明，自定义字体样式 |
| **TextBox** | `TextBox.h` | 输入框/显示框 | 支持输入和只读模式，集成EasyX的`InputBox` |
## ✂️ 文本单行截断 & 🫧 Tooltip
### 2. 容器控件
- **按钮截断**：多字节字符集下**中/英分治**，基于像素宽度阈值追加 `...`
- **Tooltip**：延时出现、自动隐藏；默认文字=按钮文本，可自定义；使用控件级**背景快照/恢复**
| 控件 | 头文件 | 描述 |
| :--------- | :--------- | :------------------------------------------------------- |
| **Canvas** | `Canvas.h` | 容器控件，可作为其他控件的父容器，支持自定义边框和背景。 |
| **Window** | `Window.h` | 顶级窗口，所有控件的最终容器，负责消息循环和调度。 |
------
### 3. 高级控件
## 🧊 透明背景与背景快照
| 控件 | 头文件 | 描述 | 关键特性 |
| :--------- | :--------- | :------- | :----------------------------------------------------------- |
| **Table** | `Table.h` | 数据表格 | **框架功能亮点**，支持分页显示、自定义表头和数据、自动计算列宽、翻页按钮。 |
| **Dialog** | `Dialog.h` | 对话框类 | 实现完整的对话框功能，支持多种按钮组合和异步结果回调。自动处理布局、背景保存恢复和生命周期管理。 |
- **通用约定**：首绘前 `captureBackground(rect)`，隐藏/覆盖前 `restoreBackground()`
- **Table**：快照区域**包含表头**；翻页后立即恢复 + 重绘，分页控件整体居中
**表格控件示例：**
cpp
```c++
// 创建一个表格
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
```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) {
// 异步处理结果
}
);
```
## 示例
- **寄存器查看器 (≈450 行)** — 一个基于 StellarX 实现的交互式 32 位寄存器可视化工具（支持位取反、左/右移、十六进制/十进制转换、带有符号/无符号切换、二进制分组显示）。
路径：`examples/register-viewer/`
------
## 🔧 高级主题与最佳实践
### 1. 自定义控件
- 自定义控件：继承 `Control`，实现 `draw()` / `handleEvent()`
- 性能：
- **脏矩形**：状态改变时置 `dirty=true`，按需重绘
- **避免额外 `cleardevice()`**：背景已由 `WM_PAINT` 统一处理
- 绘制前确保 `SetWorkingImage(nullptr)` 将输出落到屏幕
- 事件消费：处理后返回 `true` 终止传播
您可以通过继承`Control`基类来创建自定义控件。只需实现`draw()`和`handleEvent()`两个纯虚函数即可。
------
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();
}
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; }
};
```
- 不适合高性能游戏/复杂动画；极端 DPI 需复核度量
- 暂无无障碍能力
- Windows 专用，不跨平台
- 复杂商业前端建议用 Qt / wxWidgets / ImGui / Electron
------
## 📜 许可证
### 2. 布局管理
MIT（见 `LICENSE`）。
当前版本星垣主要采用**绝对定位**。对于简单布局，您可以通过计算坐标来实现。对于复杂布局，可以考虑：
## 👥 贡献指南
- 在`Canvas`中嵌套控件，实现相对定位。
- 自行实现简单的流式布局或网格布局管理器。
- 遵循现有 C++ 风格
- 新特性需附示例与 README 更新
- 提交前请自测，并说明变更动机
- Bug/想法请提 Issue
### 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](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编程成为可能。
- 感谢所有追求**简洁、高效、清晰**编码理念的开发者，你们是"星垣"诞生的灵感源泉。
- 感谢 [EasyX](https://easyx.cn/)
- 感谢推崇**简洁/高效/清晰**的开发者
------
**星辰大海，代码为舟。**
愿 `星垣 (StellarX)` 能成为您探索GUI世界的一颗可靠基石，无论是用于学习、教学还是创造实用的工具。
## 📞 支持与反馈
如果您在使用过程中遇到问题或有任何建议：
1. 查看 [示例代码](examples/) 获取使用参考
2. 查阅 [更新日志](CHANGELOG.md) 了解最新变化
3. 在GitHub仓库提交Issue反馈问题
------
*星垣框架 - 轻若尘埃，繁星为界*
- 查看 [examples/](examples/)
- 查阅 [更新日志](CHANGELOG.md / CHANGELOG.en.md)
- 在 GitHub 提交 Issue