feat: add a new awesome feature
This commit is contained in:
Ysm-04
@@ -7,12 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||||||
|
|
||||||
[中文文档](CHANGELOG.md)
|
[中文文档](CHANGELOG.md)
|
||||||
|
|
||||||
## [v2.1.0] - 2025-10-05
|
## [v2.1.0] - 2025-10-27
|
||||||
|
|
||||||
**Focus**: Resizable/maximized window (EasyX reinforced by Win32), first-phase layout manager (HBox/VBox), early Tabs control. We also fixed black borders, maximize “ghosts”, flicker, and the issue where controls only appeared after interaction. Control-level **background snapshot/restore**, **single-line truncation**, and **tooltips** are now standardized.
|
**Focus**: Resizable/maximized window (EasyX reinforced by Win32), first-phase layout manager (HBox/VBox), early Tabs control. We also fixed black borders, maximize “ghosts”, flicker, and the issue where controls only appeared after interaction. Control-level **background snapshot/restore**, **single-line truncation**, and **tooltips** are now standardized.
|
||||||
|
|
||||||
### ✨ Added
|
### ✨ Added
|
||||||
|
|
||||||
|
- **Bilingual API Documentation (Chinese and English)**
|
||||||
|
- The documentation provides a detailed introduction of each class, including API descriptions, functionalities, and points to note, with a comprehensive explanation of each control.
|
||||||
|
|
||||||
- **Window resize/maximize reinforcement (EasyX + Win32)**
|
- **Window resize/maximize reinforcement (EasyX + Win32)**
|
||||||
- `Window::enableResize(bool enable, int minW, int minH)`; toggle at runtime and set min track size.
|
- `Window::enableResize(bool enable, int minW, int minH)`; toggle at runtime and set min track size.
|
||||||
- Subclassed WndProc for `WM_GETMINMAXINFO / WM_SIZE / WM_EXITSIZEMOVE / WM_ERASEBKGND / WM_PAINT` with `WS_THICKFRAME | WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_CLIPCHILDREN | WS_CLIPSIBLINGS`.
|
- Subclassed WndProc for `WM_GETMINMAXINFO / WM_SIZE / WM_EXITSIZEMOVE / WM_ERASEBKGND / WM_PAINT` with `WS_THICKFRAME | WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_CLIPCHILDREN | WS_CLIPSIBLINGS`.
|
||||||
|
|||||||
@@ -13,6 +13,9 @@ StellarX 项目所有显著的变化都将被记录在这个文件中。
|
|||||||
|
|
||||||
### ✨ 新增
|
### ✨ 新增
|
||||||
|
|
||||||
|
- **中英文双语 API文档**
|
||||||
|
- 文档详细介绍了每个类，以及API描述、功能和需要注意的地方，详细介绍了每个控件
|
||||||
|
|
||||||
- **窗口拉伸 / 最大化补强（在 EasyX 基础上用 Win32 加固）**
|
- **窗口拉伸 / 最大化补强（在 EasyX 基础上用 Win32 加固）**
|
||||||
- 新增 `Window::enableResize(bool enable, int minW, int minH)`；运行时开关可拉伸并设置最小跟踪尺寸。
|
- 新增 `Window::enableResize(bool enable, int minW, int minH)`；运行时开关可拉伸并设置最小跟踪尺寸。
|
||||||
- 子类化窗口过程：处理 `WM_GETMINMAXINFO / WM_SIZE / WM_EXITSIZEMOVE / WM_ERASEBKGND / WM_PAINT`，并启用 `WS_THICKFRAME | WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_CLIPCHILDREN | WS_CLIPSIBLINGS`，解决 EasyX 窗口原生不可拉伸问题。
|
- 子类化窗口过程：处理 `WM_GETMINMAXINFO / WM_SIZE / WM_EXITSIZEMOVE / WM_ERASEBKGND / WM_PAINT`，并启用 `WS_THICKFRAME | WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_CLIPCHILDREN | WS_CLIPSIBLINGS`，解决 EasyX 窗口原生不可拉伸问题。
|
||||||
|
|||||||
549
README.en.md
549
README.en.md
@@ -5,11 +5,10 @@
|
|||||||
------
|
------
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
[](https://github.com/Ysm-04/StellarX)
|
[](https://github.com/Ysm-04/StellarX)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -18,37 +17,55 @@
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
> **"Bound by Stars, Light as Dust"** — A native C++ GUI framework for Windows platform, featuring extreme lightweight and high modularity.
|
> **"Bound by Stars, Light as Dust"** — A native C++ GUI framework for Windows, featuring extreme lightness and high modularity.
|
||||||
|
|
||||||
`StellarX` was born from resistance against "overly bloated" modern GUI frameworks. It rejects dependencies that often reach hundreds of MB, long compilation times, and steep learning curves, choosing to return to the essence: solving core desktop application development needs with the most concise code, clearest architecture, and highest efficiency.
|
`StellarX` was born from resistance against bloat. It avoids huge dependencies, long build times, and steep learning curves, returning to the essence: using concise code, clear architecture, and high efficiency to solve desktop GUI needs.
|
||||||
|
|
||||||
It is a **pure teaching-level, tool-level framework** designed to help developers deeply understand GUI principles and quickly build lightweight Windows tools.
|
It is a **pure teaching/tool-level framework** that helps developers understand GUI principles and quickly build lightweight Windows tools.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 🆕 What's New in v2.1.0
|
||||||
|
|
||||||
|
**Bilingual API Documentation (Chinese and English)**
|
||||||
|
|
||||||
|
- The documentation provides a detailed introduction of each class, including API descriptions, functionalities, and points to note, with a comprehensive explanation of each control.
|
||||||
|
|
||||||
|
- **Resizable/Maximizable Window (EasyX + Win32 reinforcement)**
|
||||||
|
Subclassed WndProc with `WM_GETMINMAXINFO / WM_SIZE / WM_EXITSIZEMOVE / WM_ERASEBKGND / WM_PAINT` and window styles `WS_THICKFRAME | WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_CLIPCHILDREN | WS_CLIPSIBLINGS`. Full-surface background paint in `WM_PAINT` eliminates black borders and maximize “ghosts”. Coalesced resize with one-shot redraw.
|
||||||
|
- **Layout Manager (Phase 1)**
|
||||||
|
`Canvas` now supports `LayoutKind::{Absolute, HBox, VBox, Grid(placeholder), Flow(placeholder), Stack(placeholder)}` with `LayoutParams` (`margins`, `fixedW/fixedH`, `weight`, `Align{Start,Center,End,Stretch}`). Implemented **HBox/VBox** auto layout (containers remain absolutely positioned; nesting supported).
|
||||||
|
- **Tabs (early)**
|
||||||
|
Tab strip + page container separated; background snapshot avoids trails on transparent themes.
|
||||||
|
- **Button Single-Line Truncation (MBCS, CN/EN aware)**
|
||||||
|
Pixel-width based `...` truncation prevents half-glyph artifacts.
|
||||||
|
- **Hover Tooltip**
|
||||||
|
Implemented via `Label`, supports delay and auto-hide; per-control background snapshot/restore.
|
||||||
|
|
||||||
|
See details in `CHANGELOG.en.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 📦 Project Structure & Design Philosophy
|
## 📦 Project Structure & Design Philosophy
|
||||||
|
|
||||||
StellarX framework adopts classic **Object-Oriented** and **modular** design with a clear and standardized project structure:
|
StellarX adopts classic **OOP** and **modular** design with a clear structure:
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
|
|
||||||
StellarX/
|
StellarX/
|
||||||
├── include/ # Header files directory
|
├── include/
|
||||||
│ └── StellarX/ # Framework header files
|
│ └── StellarX/
|
||||||
│ ├── StellarX.h # Main include header - one-click import of entire framework
|
│ ├── StellarX.h
|
||||||
│ ├── CoreTypes.h # ★ Core ★ - Single source of truth for all enums and structs
|
│ ├── CoreTypes.h # Single source of truth for enums/structs
|
||||||
│ ├── Control.h # Abstract base class - defines unified interface for all controls
|
│ ├── Control.h
|
||||||
│ ├── Button.h # Button control
|
│ ├── Button.h
|
||||||
│ ├── Window.h # Window management
|
│ ├── Window.h
|
||||||
│ ├── Label.h # Label control
|
│ ├── Label.h
|
||||||
│ ├── TextBox.h # Text box control
|
│ ├── TextBox.h
|
||||||
│ ├── Canvas.h # Canvas container
|
│ ├── Canvas.h
|
||||||
│ ├── Dialog.h # Dialog control (new in v2.0.0)
|
│ ├── Dialog.h
|
||||||
│ ├── MessageBox.h # Message box factory (new in v2.0.0)
|
│ ├── MessageBox.h
|
||||||
│ └── Table.h # Table control
|
│ └── Table.h
|
||||||
├── src/ # Source files directory
|
├── src/
|
||||||
│ ├── Control.cpp
|
│ ├── Control.cpp
|
||||||
│ ├── Button.cpp
|
│ ├── Button.cpp
|
||||||
│ ├── Window.cpp
|
│ ├── Window.cpp
|
||||||
@@ -56,396 +73,252 @@ StellarX/
|
|||||||
│ ├── TextBox.cpp
|
│ ├── TextBox.cpp
|
||||||
│ ├── Canvas.cpp
|
│ ├── Canvas.cpp
|
||||||
│ ├── Table.cpp
|
│ ├── Table.cpp
|
||||||
│ ├── Dialog.cpp # v2.0.0 new
|
│ ├── Dialog.cpp
|
||||||
│ └── MessageBox.cpp # v2.0.0 new
|
│ └── MessageBox.cpp
|
||||||
├── examples/ # Example code directory
|
├── examples/
|
||||||
│ └── demo.cpp # Basic demonstration
|
│ └── demo.cpp
|
||||||
├── docs/ # Documentation directory
|
├── docs/
|
||||||
│ └── CODE_OF_CONDUCT.md # Code of Conduct
|
│ └── CODE_OF_CONDUCT.md
|
||||||
├── CMakeLists.txt # CMake build configuration
|
├── CMakeLists.txt
|
||||||
├── CONTRIBUTING.md # Contribution guide
|
├── CONTRIBUTING.md
|
||||||
├── CHANGELOG.md # Changelog
|
├── CHANGELOG.en.md
|
||||||
├── Doxyfile # Doxygen configuration
|
├── CHANGELOG.md
|
||||||
├── LICENSE # MIT License
|
├── Doxyfile
|
||||||
└── README.md # Project description
|
├── LICENSE
|
||||||
|
├──API 文档.md
|
||||||
|
├──API Documentation.en.md
|
||||||
|
└── README.en.md
|
||||||
```
|
```
|
||||||
|
|
||||||
### **Design Philosophy:**
|
### Design Philosophy
|
||||||
|
|
||||||
1. **Single Responsibility Principle (SRP)**: Each class/file is responsible for one thing only.
|
1. **SRP**: each class/file does one thing.
|
||||||
2. **Dependency Inversion Principle (DIP)**: High-level modules (like `Window`) don't depend on low-level modules (like `Button`), both depend on abstractions (`Control`).
|
2. **DIP**: high-level modules depend on abstractions (`Control`), not concrete controls.
|
||||||
3. **Open/Closed Principle (OCP)**: New controls can be easily extended by inheriting the `Control` base class without modifying existing code.
|
3. **OCP**: new controls extend `Control` without touching existing code.
|
||||||
4. **Consistency**: All controls share unified `draw()` and `handleEvent()` interfaces.
|
4. **Consistency**: all controls expose `draw()` and `handleEvent()`.
|
||||||
|
|
||||||
## 🚀 Core Features
|
## 🚀 Core Features
|
||||||
|
|
||||||
- **Extreme Lightweight**: Core library compiles to only ~12MB, with zero external dependencies. Generated applications are compact.
|
- **Extreme Lightweight**: tiny footprint with zero external dependencies beyond EasyX.
|
||||||
- **Clear Modular Architecture**: Uses `CoreTypes.h` to uniformly manage all types, eliminating duplicate definitions and greatly improving maintainability.
|
- **Clear Modular Architecture**: `CoreTypes.h` centralizes types and enums.
|
||||||
- **Native C++ Performance**: Built directly on EasyX and Win32 API, providing near-native execution efficiency with very low memory footprint (typically <10MB).
|
- **Native C++ Performance**: EasyX + Win32 API for near-native speed, low memory (<10MB typical).
|
||||||
- **Complete Control System**: Button, Label, TextBox, Canvas, Table, Dialog, and MessageBox factory.
|
- **Complete Control Set**: Button, Label, TextBox, Canvas, Table, Dialog, and MessageBox factory.
|
||||||
- **Highly Customizable**: From control colors, shapes (rectangle, rounded, circle, ellipse) to fill modes and font styles, all have detailed enum support for easy customization.
|
- **Highly Customizable**: colors, shapes (rectangle/rounded/circle/ellipse), fill modes, fonts via enums.
|
||||||
- **Simple & Intuitive API**: Uses classic object-oriented design, code as documentation, low learning curve.
|
- **Simple, Intuitive API**: OOP-oriented, code as documentation.
|
||||||
- **Standard Project Structure**: Adopts standard include/src separation structure, supports CMake build, easy to integrate and use.
|
- **Standard Project Layout**: include/src split, CMake build.
|
||||||
- **Enhanced Event System**: v2.0.0 introduces event consumption mechanism, all `handleEvent` methods return `bool` indicating whether event was consumed, supporting finer-grained event propagation control.
|
- **Enhanced Event System**: `handleEvent` returns `bool` for consumption (since v2.0.0).
|
||||||
- **Dialog System**: New complete dialog support, including modal and non-modal dialogs, automatically handling background saving and restoration.
|
- **Dialog System**: modal and modeless; auto background save/restore.
|
||||||
|
|
||||||
## ⚡ Quick Start (5 Minutes to Get Started)
|
------
|
||||||
|
|
||||||
> **🎯 Latest Version Download**
|
## ⚡ Quick Start (5 Minutes)
|
||||||
> Download pre-compiled library files and header files from [GitHub Releases](https://github.com/Ysm-04/StellarX/releases/latest) for quick integration into your project.
|
|
||||||
|
|
||||||
### Environment Requirements
|
> Download prebuilt headers/libs from [Releases](https://github.com/Ysm-04/StellarX/releases/latest).
|
||||||
|
|
||||||
- **OS**: Windows 10 or higher
|
### Requirements
|
||||||
- **Compiler**: C++17 supported compiler (e.g., **Visual Studio 2019+**)
|
|
||||||
- **Graphics Library**: [EasyX](https://easyx.cn/) (2022 version or higher, please select the version matching your compiler during installation)
|
- **OS**: Windows 10+
|
||||||
- **Build Tool**: CMake 3.12+ (optional, recommended)
|
- **Compiler**: C++17 (e.g., Visual Studio 2019+)
|
||||||
|
- **Graphics**: [EasyX](https://easyx.cn/) 2022+ (match your compiler)
|
||||||
|
- **Build**: CMake 3.12+ (optional)
|
||||||
|
|
||||||
### Install EasyX
|
### Install EasyX
|
||||||
|
|
||||||
1. Visit [EasyX official website](https://easyx.cn/) to download the latest version
|
1. Download latest EasyX
|
||||||
2. Run the installer, select the version matching your Visual Studio version
|
2. Install matching your Visual Studio
|
||||||
3. After installation, no additional configuration is needed, StellarX framework will automatically link EasyX
|
3. No extra configuration needed for StellarX
|
||||||
|
|
||||||
### Method 1: Using CMake Build (Recommended)
|
### CMake Build (Recommended)
|
||||||
|
|
||||||
1. **Clone the project**:
|
```
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/Ysm-04/StellarX.git
|
git clone https://github.com/Ysm-04/StellarX.git
|
||||||
cd StellarX
|
cd StellarX
|
||||||
```
|
mkdir build && cd build
|
||||||
|
|
||||||
2. **Generate build system**:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir build
|
|
||||||
cd build
|
|
||||||
cmake ..
|
cmake ..
|
||||||
```
|
|
||||||
|
|
||||||
3. **Compile the project**:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cmake --build .
|
cmake --build .
|
||||||
```
|
|
||||||
|
|
||||||
4. **Run the example**:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
./examples/Demo
|
./examples/Demo
|
||||||
```
|
```
|
||||||
|
|
||||||
### Method 2: Manual Integration into Existing Project
|
### Manual Integration
|
||||||
|
|
||||||
1. **Copy the include and src directories** to your project
|
- Copy `include` and `src` into your project
|
||||||
2. **Configure include paths** to ensure the compiler can find the `include/StellarX/` directory
|
- Add include paths for `include/StellarX/`
|
||||||
3. **Add all .cpp files** to your project for compilation
|
- Add all `.cpp` files to your build
|
||||||
|
|
||||||
### Create Your First StellarX Application
|
### Your First App (now Resizable)
|
||||||
|
|
||||||
```cpp
|
```
|
||||||
// Just include this one header to use all features
|
|
||||||
#include "StellarX.h"
|
#include "StellarX.h"
|
||||||
|
|
||||||
// Program entry point (use WinMain for better compatibility)
|
int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int) {
|
||||||
int WINAPI WinMain(_In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, _In_ LPSTR lpCmdLine, _In_ int nShowCmd)
|
Window mainWindow(800, 600, 0, RGB(255,255,255), "StellarX App");
|
||||||
{
|
|
||||||
// 1. Create a 640x480 window with white background, titled "My App"
|
|
||||||
Window mainWindow(640, 480, 0, RGB(255, 255, 255), "My First StellarX App");
|
|
||||||
|
|
||||||
// 2. Create a button (managed with smart pointer)
|
|
||||||
auto myButton = std::make_unique<Button>(
|
|
||||||
250, 200, 140, 40, // x, y, width, height
|
|
||||||
"Click Me", // button text
|
|
||||||
StellarX::ButtonMode::NORMAL,
|
|
||||||
StellarX::ControlShape::ROUND_RECTANGLE
|
|
||||||
);
|
|
||||||
|
|
||||||
// 3. Set click event for the button (using Lambda expression)
|
|
||||||
myButton->setOnClickListener([&mainWindow]() {
|
|
||||||
// Use message box factory to create modal dialog
|
|
||||||
auto result = StellarX::MessageBox::ShowModal(
|
|
||||||
mainWindow,
|
|
||||||
"Welcome to StellarX GUI\r\nAuthor: Ysm-04",
|
|
||||||
"Greeting",
|
|
||||||
StellarX::MessageBoxType::OKCancel
|
|
||||||
);
|
|
||||||
// Handle dialog result
|
|
||||||
if (result == StellarX::MessageBoxResult::OK) {
|
|
||||||
// User clicked OK button
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
// 4. (Optional) Set button style
|
|
||||||
myButton->textStyle.nHeight = 20;
|
|
||||||
myButton->textStyle.color = RGB(0, 0, 128); // Dark blue text
|
|
||||||
myButton->setButtonBorder(RGB(0, 128, 255)); // Blue border
|
|
||||||
|
|
||||||
// 5. Add button to window
|
|
||||||
mainWindow.addControl(std::move(myButton));
|
|
||||||
|
|
||||||
// 6. Draw the window
|
|
||||||
mainWindow.draw();
|
mainWindow.draw();
|
||||||
|
|
||||||
// 7. Enter message loop, wait for user interaction
|
// Enable resize + minimum track size
|
||||||
mainWindow.runEventLoop();
|
mainWindow.enableResize(true, 480, 360);
|
||||||
|
|
||||||
|
// Add your controls here...
|
||||||
|
// mainWindow.addControl(std::move(btn));
|
||||||
|
|
||||||
|
mainWindow.runEventLoop();
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
1. **Compile and run!** You'll see a window with a blue rounded button, clicking it will pop up a message box.
|
> Internally, we paint the **entire client area** in `WM_PAINT` (solid/image) and use EasyX batch drawing to avoid flicker and black borders.
|
||||||
|
|
||||||
## 📚 Core Types Detailed Explanation (`CoreTypes.h`)
|
------
|
||||||
|
|
||||||
All visual and behavioral properties of the StellarX framework are controlled through the elegant enums and structs defined in `CoreTypes.h`.
|
## 📚 Core Types (`CoreTypes.h`)
|
||||||
|
|
||||||
### Enum Types (Enums)
|
### Enums (selection)
|
||||||
|
|
||||||
| Enum Type | Description | Common Values |
|
| Enum | Description | Values |
|
||||||
| :--------------------- | :---------------------- | :----------------------------------------------------------- |
|
| ------------------ | ----------- | ------------------------------------------------------------ |
|
||||||
| **`ControlShape`** | Control geometric shape | `RECTANGLE`, `B_RECTANGLE`, `ROUND_RECTANGLE`, `CIRCLE`, `ELLIPSE`, etc. |
|
| `ControlShape` | geometry | `RECTANGLE`, `B_RECTANGLE`, `ROUND_RECTANGLE`, `CIRCLE`, `ELLIPSE`, ... |
|
||||||
| **`ButtonMode`** | Button behavior mode | `NORMAL`, `TOGGLE`, `DISABLED` |
|
| `ButtonMode` | behavior | `NORMAL`, `TOGGLE`, `DISABLED` |
|
||||||
| **`TextBoxMode`** | Text box mode | `INPUT_MODE`, `READONLY_MODE` |
|
| `TextBoxMode` | modes | `INPUT_MODE`, `READONLY_MODE` |
|
||||||
| **`FillMode`** | Graphics fill mode | `SOLID`, `NULL`, `HATCHED`, etc. |
|
| `FillMode` | fill | `SOLID`, `NULL`, `HATCHED`, ... |
|
||||||
| **`FillStyle`** | Pattern fill style | `HORIZONTAL`, `CROSS`, etc. |
|
| `FillStyle` | pattern | `HORIZONTAL`, `CROSS`, ... |
|
||||||
| **`LineStyle`** | Border line style | `SOLID`, `DASH`, `DOT`, etc. |
|
| `LineStyle` | border | `SOLID`, `DASH`, `DOT`, ... |
|
||||||
| **`MessageBoxType`** | Message box type | `OK`, `OKCancel`, `YesNo`, `YesNoCancel`, `RetryCancel`, `AbortRetryIgnore` |
|
| `MessageBoxType` | dialog | `OK`, `OKCancel`, `YesNo`, ... |
|
||||||
| **`MessageBoxResult`** | Message box result | `OK`, `Cancel`, `Yes`, `No`, `Abort`, `Retry`, `Ignore` |
|
| `MessageBoxResult` | result | `OK`, `Cancel`, `Yes`, `No`, `Abort`, `Retry`, `Ignore` |
|
||||||
|
|
||||||
### Structs (Structs)
|
### Structs
|
||||||
|
|
||||||
| Struct | Description |
|
| Struct | Description |
|
||||||
| :----------------- | :----------------------------------------------------------- |
|
| -------------- | -------------------------------------------- |
|
||||||
| **`ControlText`** | Encapsulates all text style attributes, including font, size, color, bold, italic, underline, strikethrough, etc. |
|
| `ControlText` | font/size/color/bold/italic/underline/strike |
|
||||||
| **`RouRectangle`** | Defines rounded rectangle corner ellipse dimensions, contains width and height properties. |
|
| `RouRectangle` | rounded-rectangle corner ellipse size |
|
||||||
|
|
||||||
**Usage Example:**
|
------
|
||||||
|
|
||||||
```c++
|
## 🧩 Control Library
|
||||||
// Create a complex text style
|
|
||||||
StellarX::ControlText myStyle;
|
|
||||||
myStyle.nHeight = 25; // Font height
|
|
||||||
myStyle.lpszFace = _T("Microsoft YaHei"); // Font
|
|
||||||
myStyle.color = RGB(255, 0, 0); // Red color
|
|
||||||
myStyle.nWeight = FW_BOLD; // Bold
|
|
||||||
myStyle.bUnderline = true; // Underline
|
|
||||||
|
|
||||||
// Apply to controls
|
### 1) Basic
|
||||||
myLabel->textStyle = myStyle;
|
|
||||||
myButton->textStyle = myStyle;
|
| Control | Header | Description | Key Points |
|
||||||
|
| ------- | ----------- | ----------------------- | ------------------------------------------------------------ |
|
||||||
|
| Button | `Button.h` | multi-functional button | shapes/modes, hover/click colors, callbacks, **single-line truncation** + **tooltip** (v2.1.0) |
|
||||||
|
| Label | `Label.h` | text label | transparent/opaque backgrounds, custom font styles |
|
||||||
|
| TextBox | `TextBox.h` | input/display | input & read-only, integrates EasyX `InputBox` |
|
||||||
|
|
||||||
|
### 2) Containers
|
||||||
|
|
||||||
|
| Control | Header | Description |
|
||||||
|
| ------- | ---------- | ------------------------------------------------------------ |
|
||||||
|
| Canvas | `Canvas.h` | parent container, custom border/background, **auto layout HBox/VBox** (v2.1.0) |
|
||||||
|
| Window | `Window.h` | top-level container, message loop/dispatch, **resizable** (v2.1.0) |
|
||||||
|
|
||||||
|
### 3) Advanced
|
||||||
|
|
||||||
|
| Control | Header | Description | Key Points |
|
||||||
|
| ------- | ---------- | ----------- | ------------------------------------------------------------ |
|
||||||
|
| Table | `Table.h` | data table | pagination, header/data, auto column widths, page controls fixed overlap/centering (v2.1.0) |
|
||||||
|
| Dialog | `Dialog.h` | dialogs | modal/modeless, layout & background save/restore |
|
||||||
|
|
||||||
|
### 4) Static Factory
|
||||||
|
|
||||||
|
| Control | Header | Description | Key Points |
|
||||||
|
| ---------- | -------------- | -------------- | ------------------------------------------- |
|
||||||
|
| MessageBox | `MessageBox.h` | dialog factory | static API; modal/modeless; dedup mechanism |
|
||||||
|
|
||||||
|
------
|
||||||
|
|
||||||
|
## 📐 Layout Management (HBox/VBox)
|
||||||
|
|
||||||
|
- **Container-level**: `Canvas::layout.kind = HBox / VBox / Absolute (default)`; optional container `padding`.
|
||||||
|
- **Child-level**: `LayoutParams`
|
||||||
|
- `margin{L,R,T,B}`
|
||||||
|
- `fixedW/fixedH` (`-1` = keep current)
|
||||||
|
- `weight` (distribute along main axis; width in HBox, height in VBox)
|
||||||
|
- `alignX/alignY` = `Start/Center/End/Stretch` (cross-axis)
|
||||||
|
|
||||||
|
**Example** (3 items HBox, center vertically, stretch height):
|
||||||
|
|
||||||
|
```
|
||||||
|
Canvas row(20, 20, 760, 120);
|
||||||
|
row.layout.kind = LayoutKind::HBox;
|
||||||
|
|
||||||
|
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));
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🧩 Complete Control Library
|
------
|
||||||
|
|
||||||
### 1. Basic Controls
|
## 🗂 Tabs (Early)
|
||||||
|
|
||||||
| Control | Header File | Description | Key Features |
|
- Tab strip (buttons) + page container (`Canvas`)
|
||||||
| :---------- | :---------- | :-------------------- | :----------------------------------------------------------- |
|
- Transparent themes: page area uses **background snapshot** on switch
|
||||||
| **Button** | `Button.h` | Multi-function button | Supports multiple modes/shapes/states, hover/click colors, custom callbacks |
|
- API sketch: `tabs.addPage(title, canvasPtr); tabs.setActive(index);`
|
||||||
| **Label** | `Label.h` | Text label | Supports transparent/opaque background, custom font styles |
|
|
||||||
| **TextBox** | `TextBox.h` | Input box/Display box | Supports input and read-only modes, integrates EasyX's `InputBox` |
|
|
||||||
|
|
||||||
### 2. Container Controls
|
------
|
||||||
|
|
||||||
| Control | Header File | Description |
|
## ✂️ Single-Line Truncation & 🫧 Tooltip
|
||||||
| :--------- | :---------- | :----------------------------------------------------------- |
|
|
||||||
| **Canvas** | `Canvas.h` | Container control, can serve as parent container for other controls, supports custom borders and background. |
|
|
||||||
| **Window** | `Window.h` | Top-level window, ultimate container for all controls, responsible for message loop and dispatching. |
|
|
||||||
|
|
||||||
### 3. Advanced Controls
|
- **Button truncation**: MBCS CN/EN aware pixel-width threshold + `...`
|
||||||
|
- **Tooltip**: delayed show, auto-hide; default text = button label; customizable; uses per-control **background snapshot/restore**.
|
||||||
|
|
||||||
| Control | Header File | Description | Key Features |
|
------
|
||||||
| :--------- | :---------- | :----------- | :----------------------------------------------------------- |
|
|
||||||
| **Table** | `Table.h` | Data table | **Framework highlight feature**, supports paginated display, custom headers and data, automatic column width calculation, page turn buttons. |
|
|
||||||
| **Dialog** | `Dialog.h` | Dialog class | Implements complete dialog functionality, supports multiple button combinations and asynchronous result callbacks. Automatically handles layout, background save/restore and lifecycle management. |
|
|
||||||
|
|
||||||
**Table Control Example:**
|
## 🧊 Transparent Background & Background Snapshot
|
||||||
|
|
||||||
```c++
|
- **Convention**: `captureBackground(rect)` before first draw; `restoreBackground()` before hiding/overdraw.
|
||||||
// Create a table
|
- **Table**: snapshot area now **includes header**; pagination re-centers controls and restores backgrounds immediately.
|
||||||
auto myTable = std::make_unique<Table>(50, 50);
|
|
||||||
|
|
||||||
// Set headers
|
------
|
||||||
myTable->setHeaders({ "ID", "Name", "Age", "Occupation" });
|
|
||||||
|
|
||||||
// Add data rows
|
|
||||||
myTable->setData({ "1", "Zhang San", "25", "Engineer" });
|
|
||||||
myTable->setData({ "2", "Li Si", "30", "Designer" });
|
|
||||||
myTable->setData({ "3", "Wang Wu", "28", "Product Manager" });
|
|
||||||
|
|
||||||
// Set rows per page
|
|
||||||
myTable->setRowsPerPage(2);
|
|
||||||
|
|
||||||
// Set table style
|
|
||||||
myTable->textStyle.nHeight = 16;
|
|
||||||
myTable->setTableBorder(RGB(50, 50, 50));
|
|
||||||
myTable->setTableBk(RGB(240, 240, 240));
|
|
||||||
|
|
||||||
// Add to window
|
|
||||||
mainWindow.addControl(std::move(myTable));
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Static Factory Class
|
|
||||||
|
|
||||||
| Control | Header File | Description | Key Features |
|
|
||||||
| :------------- | :------------- | :------------------- | :----------------------------------------------------------- |
|
|
||||||
| **MessageBox** | `MessageBox.h` | Dialog factory calls | Static method calls, no instantiation needed, automatically handles modal and non-modal logic differences, integrated into window's dialog management system, provides deduplication mechanism to prevent duplicate dialogs |
|
|
||||||
|
|
||||||
**MessageBox Usage Example:**
|
|
||||||
|
|
||||||
```c++
|
|
||||||
// Modal message box (blocks until closed)
|
|
||||||
auto result = StellarX::MessageBox::ShowModal(
|
|
||||||
mainWindow,
|
|
||||||
"Confirm to perform this operation?",
|
|
||||||
"Confirmation",
|
|
||||||
StellarX::MessageBoxType::YesNo
|
|
||||||
);
|
|
||||||
|
|
||||||
if (result == StellarX::MessageBoxResult::Yes)
|
|
||||||
{
|
|
||||||
// User selected "Yes"
|
|
||||||
}
|
|
||||||
|
|
||||||
// Non-modal message box (asynchronous callback)
|
|
||||||
StellarX::MessageBox::ShowAsync(
|
|
||||||
mainWindow,
|
|
||||||
"Operation completed",
|
|
||||||
"Notification",
|
|
||||||
StellarX::MessageBoxType::OK,
|
|
||||||
[](StellarX::MessageBoxResult result) {
|
|
||||||
// Asynchronously handle result
|
|
||||||
}
|
|
||||||
);
|
|
||||||
```
|
|
||||||
|
|
||||||
## Examples
|
|
||||||
|
|
||||||
- **Register Viewer (≈450 lines)** — An interactive 32-bit register visualization tool implemented based on StellarX (supports bit inversion, left/right shift, hex/decimal conversion, signed/unsigned toggle, binary grouping display).
|
|
||||||
Path: `examples/register-viewer/`
|
|
||||||
|
|
||||||
## 🔧 Advanced Topics & Best Practices
|
## 🔧 Advanced Topics & Best Practices
|
||||||
|
|
||||||
### 1. Custom Controls
|
- Custom controls: inherit `Control` and implement `draw()` / `handleEvent()`.
|
||||||
|
- Performance:
|
||||||
|
- **Dirty rendering**: set `dirty=true` when state changes; framework repaints as needed.
|
||||||
|
- **Avoid extra `cleardevice()`**: background is already handled in `WM_PAINT` full-surface path.
|
||||||
|
- Use `SetWorkingImage(nullptr)` before drawing to the screen.
|
||||||
|
- Event consumption: return `true` if handled to stop propagation.
|
||||||
|
|
||||||
You can create custom controls by inheriting from the `Control` base class. Just implement the two pure virtual functions `draw()` and `handleEvent()`.
|
------
|
||||||
|
|
||||||
```c++
|
## ⚠️ Limitations & When Not To Use
|
||||||
class MyCustomControl : public Control {
|
|
||||||
public:
|
|
||||||
MyCustomControl(int x, int y) : Control(x, y, 100, 100) {}
|
|
||||||
|
|
||||||
void draw() override {
|
- High-performance games or complex animations
|
||||||
saveStyle();
|
- High DPI scaling extremes (re-verify coordinates/metrics)
|
||||||
// Your custom drawing logic
|
- Accessibility requirements
|
||||||
setfillcolor(RGB(255, 100, 100));
|
- Cross-platform targets (Windows-only)
|
||||||
fillrectangle(x, y, x + width, y + height);
|
- Heavy enterprise frontends (consider Qt/wxWidgets/ImGui/Electron)
|
||||||
restoreStyle();
|
|
||||||
}
|
|
||||||
|
|
||||||
bool handleEvent(const ExMessage& msg) override {
|
------
|
||||||
// Your custom event handling logic
|
|
||||||
if (msg.message == WM_LBUTTONDOWN &&
|
|
||||||
msg.x > x && msg.x < x + width &&
|
|
||||||
msg.y > y && msg.y < y + height) {
|
|
||||||
// Handle click
|
|
||||||
return true; // Event consumed
|
|
||||||
}
|
|
||||||
return false; // Event not consumed
|
|
||||||
}
|
|
||||||
|
|
||||||
bool IsVisible() const override { return true; }
|
|
||||||
bool model() const override { return false; }
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Layout Management
|
|
||||||
|
|
||||||
Current version of StellarX primarily uses **absolute positioning**. For simple layouts, you can achieve this by calculating coordinates. For complex layouts, consider:
|
|
||||||
|
|
||||||
- Nesting controls in `Canvas` to achieve relative positioning.
|
|
||||||
- Implementing simple flow layout or grid layout managers yourself.
|
|
||||||
|
|
||||||
### 3. Performance Optimization
|
|
||||||
|
|
||||||
- **Dirty Rectangle Rendering**: Implemented internally in the framework, controls set `dirty=true` when state changes, only redraw when necessary.
|
|
||||||
- **Image Resources**: Use `IMAGE` objects to load images, then reuse them to avoid multiple loads.
|
|
||||||
- **Reduce Operations in Loops**: Avoid heavy calculations in `draw()` and `handleEvent()`.
|
|
||||||
- **Event Consumption Mechanism**: Use event consumption return values appropriately to avoid unnecessary event propagation.
|
|
||||||
|
|
||||||
### 4. Dialog Usage Tips
|
|
||||||
|
|
||||||
- **Modal Dialogs**: Use `ShowModal` method, blocks current thread until dialog closes, suitable for important operations requiring user confirmation.
|
|
||||||
- **Non-modal Dialogs**: Use `ShowAsync` method, doesn't block main thread, suitable for informational prompts or background tasks.
|
|
||||||
- **Dialog Deduplication**: Framework has built-in non-modal dialog deduplication mechanism to prevent multiple dialogs for the same message from appearing simultaneously.
|
|
||||||
|
|
||||||
## ⚠️ Important Limitations & Suitable Scenarios
|
|
||||||
|
|
||||||
**StellarX framework's design goals are lightness, clarity, and teaching value, therefore it explicitly is NOT suitable for the following scenarios:**
|
|
||||||
|
|
||||||
- **High-performance games or complex animations**: Rendering is based on EasyX's CPU software rendering, performance is limited.
|
|
||||||
- **Applications requiring high DPI scaling**: Limited support for high DPI displays, interface may not display correctly.
|
|
||||||
- **Applications requiring accessibility features**: No support for screen readers and other assistive technologies.
|
|
||||||
- **Cross-platform applications**: Deeply dependent on Windows API and EasyX, cannot run directly on Linux/macOS.
|
|
||||||
- **Complex commercial software frontends**: Lacks advanced controls (like tree views, rich text boxes, tabs, advanced lists) and mature automatic layout managers.
|
|
||||||
|
|
||||||
**If you need to develop the aforementioned types of applications, please consider the following mature solutions:**
|
|
||||||
|
|
||||||
- **Qt**: Extremely powerful, cross-platform, suitable for large commercial applications.
|
|
||||||
- **wxWidgets**: Native appearance, cross-platform.
|
|
||||||
- **Dear ImGui**: Immediate mode GUI, very suitable for tools and debug interfaces.
|
|
||||||
- **Web Technology Stack (Electron/CEF)**: Suitable for scenarios requiring web technologies.
|
|
||||||
|
|
||||||
## 📜 License
|
## 📜 License
|
||||||
|
|
||||||
This project uses the **MIT License**.
|
MIT License (see `LICENSE`).
|
||||||
|
|
||||||
You are free to:
|
## 👥 Contributing
|
||||||
|
|
||||||
- Use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the framework.
|
- Follow the existing C++ style (spaces, brace on new line).
|
||||||
- Use it for private or commercial projects.
|
- New features should include an example and README update.
|
||||||
|
- Test before PR; describe changes and motivation.
|
||||||
The only requirement is:
|
- Use Issues for bugs/ideas.
|
||||||
|
|
||||||
- Please retain the original copyright notice in your projects.
|
|
||||||
|
|
||||||
See the [LICENSE](https://license/) file in the project root directory for details.
|
|
||||||
|
|
||||||
## 👥 Contribution Guide
|
|
||||||
|
|
||||||
We welcome all forms of contributions! If you want to contribute to the StellarX framework, please read the following guidelines:
|
|
||||||
|
|
||||||
1. **Code Style**: Please follow the existing Google C++ style guide (use spaces for indentation, braces on new lines, etc.).
|
|
||||||
2. **New Features**: Must provide **example code** and update relevant parts of this README document.
|
|
||||||
3. **Submitting PRs**: Please ensure your code is tested before submission and clearly describe your changes and motivation.
|
|
||||||
4. **Issue Reporting**: If you find a bug or have new ideas, welcome to submit Issues on GitHub.
|
|
||||||
|
|
||||||
Detailed contribution guide please refer to [CONTRIBUTING.md](CONTRIBUTING.en.md).
|
|
||||||
|
|
||||||
## 🙏 Acknowledgements
|
## 🙏 Acknowledgements
|
||||||
|
|
||||||
- Thanks to [EasyX Graphics Library](https://easyx.cn/) for providing the simple and easy-to-use graphics foundation for this project, making C++ GUI programming education possible.
|
- Thanks to [EasyX](https://easyx.cn/).
|
||||||
- Thanks to all developers pursuing the **concise, efficient, clear** coding philosophy, you are the inspiration for StellarX's birth.
|
- Thanks to developers who value **concise, efficient, clear** code.
|
||||||
|
|
||||||
------
|
------
|
||||||
|
|
||||||
**Star Ocean Vast, Code as Boat.**
|
**Star Ocean Vast, Code as Boat.**
|
||||||
|
|
||||||
May `StellarX` become a reliable cornerstone for your exploration of the GUI world, whether for learning, teaching, or creating practical tools.
|
|
||||||
|
|
||||||
## 📞 Support & Feedback
|
## 📞 Support & Feedback
|
||||||
|
|
||||||
If you encounter problems during use or have any suggestions:
|
- See [examples/](examples/)
|
||||||
|
- See [Changelog](CHANGELOG.en.md)
|
||||||
1. Check [Example Code](examples/) for usage reference
|
- Open Issues on GitHub
|
||||||
2. Check [Changelog](CHANGELOG.en.md) to learn about latest changes
|
|
||||||
3. Submit Issues on GitHub repository to report problems
|
|
||||||
|
|
||||||
------
|
|
||||||
|
|
||||||
*StellarX Framework - Light as Dust, Bound by Stars*
|
|
||||||
|
|
||||||
529
README.md
529
README.md
@@ -5,11 +5,10 @@
|
|||||||
------
|
------
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
[](https://github.com/Ysm-04/StellarX)
|
[](https://github.com/Ysm-04/StellarX)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -20,32 +19,53 @@
|
|||||||
|
|
||||||
> **「繁星为界，轻若尘埃」** —— 一个为 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
|
```markdown
|
||||||
StellarX/
|
StellarX/
|
||||||
├── include/ # 头文件目录
|
├── include/
|
||||||
│ └── StellarX/ # 框架头文件
|
│ └── StellarX/
|
||||||
│ ├── StellarX.h # 主包含头文件 - 一键引入整个框架
|
│ ├── StellarX.h
|
||||||
│ ├── CoreTypes.h # ★ 核心 ★ - 所有枚举、结构体的唯一定义源
|
│ ├── CoreTypes.h # 唯一定义源（枚举/结构体）
|
||||||
│ ├── Control.h # 抽象基类 - 定义所有控件的统一接口
|
│ ├── Control.h
|
||||||
│ ├── Button.h # 按钮控件
|
│ ├── Button.h
|
||||||
│ ├── Window.h # 窗口管理
|
│ ├── Window.h
|
||||||
│ ├── Label.h # 标签控件
|
│ ├── Label.h
|
||||||
│ ├── TextBox.h # 文本框控件
|
│ ├── TextBox.h
|
||||||
│ ├── Canvas.h # 画布容器
|
│ ├── Canvas.h
|
||||||
│ ├── Dialog.h # 对话框控件（v2.0.0新增）
|
│ ├── Dialog.h # v2.0.0
|
||||||
│ ├── MessageBox.h # 消息框工厂（v2.0.0新增）
|
│ ├── MessageBox.h # v2.0.0
|
||||||
│ └── Table.h # 表格控件
|
│ └── Table.h
|
||||||
├── src/ # 源文件目录
|
├── src/
|
||||||
│ ├── Control.cpp
|
│ ├── Control.cpp
|
||||||
│ ├── Button.cpp
|
│ ├── Button.cpp
|
||||||
│ ├── Window.cpp
|
│ ├── Window.cpp
|
||||||
@@ -53,403 +73,250 @@ StellarX/
|
|||||||
│ ├── TextBox.cpp
|
│ ├── TextBox.cpp
|
||||||
│ ├── Canvas.cpp
|
│ ├── Canvas.cpp
|
||||||
│ ├── Table.cpp
|
│ ├── Table.cpp
|
||||||
│ ├── Dialog.cpp # v2.0.0新增
|
│ ├── Dialog.cpp # v2.0.0
|
||||||
│ └── MessageBox.cpp # v2.0.0新增
|
│ └── MessageBox.cpp # v2.0.0
|
||||||
├── examples/ # 示例代码目录
|
├── examples/
|
||||||
│ └── demo.cpp # 基础演示
|
│ └── demo.cpp
|
||||||
├── docs/ # 文档目录
|
├── docs/
|
||||||
│ └── CODE_OF_CONDUCT.md # 行为准则
|
│ └── CODE_OF_CONDUCT.md
|
||||||
├── CMakeLists.txt # CMake 构建配置
|
├── CMakeLists.txt
|
||||||
├── CONTRIBUTING.md # 贡献指南
|
├── CONTRIBUTING.md
|
||||||
├── CHANGELOG.md # 更新日志
|
├── CHANGELOG.md
|
||||||
├── Doxyfile # Doxygen 配置
|
├── CHANGELOG.en.md
|
||||||
├── LICENSE # MIT 许可证
|
├── Doxyfile
|
||||||
└── README.md # 项目说明
|
├── LICENSE
|
||||||
|
├──API 文档.md
|
||||||
|
├──API Documentation.en.md
|
||||||
|
└── README.md
|
||||||
```
|
```
|
||||||
|
|
||||||
**设计理念：**
|
**设计理念：**
|
||||||
|
|
||||||
1. **单一职责原则 (SRP)**: 每个类/文件只负责一件事。
|
1. **单一职责（SRP）**：每个类/文件只做一件事。
|
||||||
2. **依赖倒置原则 (DIP)**: 高层模块（如`Window`）不依赖低层模块（如`Button`），二者都依赖其抽象（`Control`）。
|
2. **依赖倒置（DIP）**：高层模块依赖抽象（`Control`），而非具体控件。
|
||||||
3. **开闭原则 (OCP)**: 通过继承`Control`基类，可以轻松扩展新的控件，而无需修改现有代码。
|
3. **开闭原则（OCP）**：继承 `Control` 可扩展新控件，无需修改既有代码。
|
||||||
4. **一致性**: 所有控件共享统一的`draw()`和`handleEvent()`接口。
|
4. **一致性**：所有控件统一 `draw()` / `handleEvent()` 接口。
|
||||||
|
|
||||||
## 🚀 核心特性
|
## 🚀 核心特性
|
||||||
|
|
||||||
- **极致的轻量级**: 核心库编译后仅 ~12MB，无任何外部依赖。生成的应用程序小巧玲珑。
|
- **极致轻量**：除 EasyX 外无外部重量级依赖。
|
||||||
- **清晰的模块化架构**: 使用`CoreTypes.h`统一管理所有类型，消除重复定义，极大提升可维护性。
|
- **模块清晰**：`CoreTypes.h` 统一类型与枚举。
|
||||||
- **原生C++性能**: 直接基于EasyX和Win32 API，提供接近原生的执行效率，内存占用极低（通常<10MB）。
|
- **原生性能**：EasyX + Win32，执行高效、内存低占用（常见 <10MB）。
|
||||||
- **完整的控件体系**: 按钮（Button）、标签（Label）、文本框（TextBox）、画布（Canvas）、表格（Table）、对话框（Dialog）与消息框工厂（MessageBox）。
|
- **控件齐全**：Button、Label、TextBox、Canvas、Table、Dialog、MessageBox。
|
||||||
- **高度可定制化**: 从控件颜色、形状（矩形、圆角、圆形、椭圆）到填充模式、字体样式，均有详尽枚举支持，可轻松定制。
|
- **高度自定义**：颜色、形状（矩形/圆角/圆/椭圆）、填充、字体等皆有枚举。
|
||||||
- **简洁直观的API**: 采用经典的面向对象设计，代码即文档，学习成本极低。
|
- **简单直观 API**：OOP 设计，代码即文档。
|
||||||
- **标准项目结构**: 采用标准的include/src分离结构，支持CMake构建，易于集成和使用。
|
- **标准工程结构**：include/src 分离，支持 CMake。
|
||||||
- **增强的事件系统**: v2.0.0引入事件消费机制，所有`handleEvent`方法返回`bool`表示是否消费事件，支持更精细的事件传播控制。
|
- **增强事件系统**：`handleEvent` 返回是否消费（自 v2.0.0）。
|
||||||
- **对话框系统**: 新增完整的对话框支持，包括模态和非模态对话框，自动处理背景保存和恢复。
|
- **对话框系统**：支持模态/非模态，自动背景保存与恢复。
|
||||||
|
|
||||||
|
------
|
||||||
|
|
||||||
## ⚡ 快速开始（5 分钟上手）
|
## ⚡ 快速开始（5 分钟上手）
|
||||||
|
|
||||||
> **🎯 最新版本下载**
|
> 从 [Releases](https://github.com/Ysm-04/StellarX/releases/latest) 获取预编译包。
|
||||||
> 从 [GitHub Releases](https://github.com/Ysm-04/StellarX/releases/latest) 下载预编译的库文件和头文件，即可快速集成到你的项目中。
|
|
||||||
|
|
||||||
### 环境要求
|
### 环境要求
|
||||||
|
|
||||||
- **操作系统**: Windows 10 或更高版本
|
- **系统**：Windows 10+
|
||||||
- **编译器**: 支持C++17的编译器 (如: **Visual Studio 2019+**)
|
- **编译器**：C++17（如 VS 2019+）
|
||||||
- **图形库**: [EasyX](https://easyx.cn/) (2022版本或更高，安装时请选择与您编译器匹配的版本)
|
- **图形库**： [EasyX](https://easyx.cn/) 2022+（与编译器匹配）
|
||||||
- **构建工具**: CMake 3.12+ (可选，推荐使用)
|
- **构建**：CMake 3.12+（可选）
|
||||||
|
|
||||||
### 安装 EasyX
|
### 安装 EasyX
|
||||||
1. 访问 [EasyX 官网](https://easyx.cn/) 下载最新版本
|
|
||||||
2. 运行安装程序，选择与您的 Visual Studio 版本匹配的版本
|
|
||||||
3. 安装完成后，无需额外配置，星垣框架会自动链接 EasyX
|
|
||||||
|
|
||||||
### 方法一：使用CMake构建（推荐）
|
1. 下载 EasyX 最新版
|
||||||
|
2. 按 VS 版本安装匹配组件
|
||||||
|
3. 框架会自动链接，无需额外配置
|
||||||
|
|
||||||
1. **克隆项目**:
|
### CMake 构建（推荐）
|
||||||
```bash
|
|
||||||
|
```
|
||||||
git clone https://github.com/Ysm-04/StellarX.git
|
git clone https://github.com/Ysm-04/StellarX.git
|
||||||
cd StellarX
|
cd StellarX
|
||||||
```
|
mkdir build && cd build
|
||||||
|
|
||||||
2. **生成构建系统**:
|
|
||||||
```bash
|
|
||||||
mkdir build
|
|
||||||
cd build
|
|
||||||
cmake ..
|
cmake ..
|
||||||
```
|
|
||||||
|
|
||||||
3. **编译项目**:
|
|
||||||
```bash
|
|
||||||
cmake --build .
|
cmake --build .
|
||||||
```
|
|
||||||
|
|
||||||
4. **运行示例**:
|
|
||||||
```bash
|
|
||||||
./examples/Demo
|
./examples/Demo
|
||||||
```
|
```
|
||||||
|
|
||||||
### 方法二：手动集成到现有项目
|
### 手动集成
|
||||||
|
|
||||||
1. **将include和src目录复制**到您的项目中
|
- 拷贝 `include` 与 `src`
|
||||||
2. **配置包含路径**，确保编译器可以找到`include/StellarX/`目录
|
- 配置头文件搜索路径：`include/StellarX/`
|
||||||
3. **将所有.cpp文件**添加到您的项目中编译
|
- 将全部 `.cpp` 加入工程
|
||||||
|
|
||||||
### 创建你的第一个星垣应用
|
### 第一个可拉伸窗口
|
||||||
|
|
||||||
```cpp
|
```c++
|
||||||
// 只需包含这一个头文件即可使用所有功能
|
|
||||||
#include "StellarX.h"
|
#include "StellarX.h"
|
||||||
|
|
||||||
// 程序入口点（请使用WinMain以获得更好的兼容性）
|
int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
|
||||||
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), "我的第一个星垣应用");
|
Window mainWindow(800, 600, 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();
|
mainWindow.draw();
|
||||||
|
|
||||||
// 7. 进入消息循环，等待用户交互
|
// 添加你的控件...
|
||||||
mainWindow.runEventLoop();
|
// mainWindow.addControl(std::move(btn));
|
||||||
|
|
||||||
|
mainWindow.runEventLoop();
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
1. **编译并运行！** 您将看到一个带有蓝色圆角按钮的窗口，点击它将会弹出消息框。
|
> 实现要点：在 `WM_PAINT` 期进行**整窗背景绘制**（纯色/图片），并配合 EasyX 批量绘制抑制频闪与黑边。
|
||||||
|
|
||||||
## 📚 核心类型详解 (`CoreTypes.h`)
|
------
|
||||||
|
|
||||||
星垣框架的所有视觉和行为属性都通过`CoreTypes.h`中定义的精美枚举和结构体来控制。
|
## 📚 核心类型（`CoreTypes.h` 摘要）
|
||||||
|
|
||||||
### 枚举类型 (Enums)
|
### 枚举
|
||||||
|
|
||||||
| 枚举类型 | 描述 | 常用值 |
|
| 枚举 | 描述 | 常用值 |
|
||||||
| :--------------------- | :----------- | :----------------------------------------------------------- |
|
| ------------------ | ---------- | ------------------------------------------------------------ |
|
||||||
| **`ControlShape`** | 控件几何形状 | `RECTANGLE`, `B_RECTANGLE`, `ROUND_RECTANGLE`, `CIRCLE`, `ELLIPSE`等 |
|
| `ControlShape` | 几何形状 | `RECTANGLE`, `B_RECTANGLE`, `ROUND_RECTANGLE`, `CIRCLE`, `ELLIPSE` |
|
||||||
| **`ButtonMode`** | 按钮行为模式 | `NORMAL`（普通）, `TOGGLE`（切换）, `DISABLED`（禁用） |
|
| `ButtonMode` | 按钮行为 | `NORMAL`, `TOGGLE`, `DISABLED` |
|
||||||
| **`TextBoxMode`** | 文本框模式 | `INPUT_MODE`（输入）, `READONLY_MODE`（只读） |
|
| `TextBoxMode` | 文本框模式 | `INPUT_MODE`, `READONLY_MODE` |
|
||||||
| **`FillMode`** | 图形填充模式 | `SOLID`（实心）, `NULL`（空心）, `HATCHED`（图案）等 |
|
| `FillMode` | 填充模式 | `SOLID`, `NULL`, `HATCHED` |
|
||||||
| **`FillStyle`** | 图案填充样式 | `HORIZONTAL`（水平线）, `CROSS`（十字线）等 |
|
| `FillStyle` | 图案样式 | `HORIZONTAL`, `CROSS` |
|
||||||
| **`LineStyle`** | 边框线型 | `SOLID`（实线）, `DASH`（虚线）, `DOT`（点线）等 |
|
| `LineStyle` | 线型 | `SOLID`, `DASH`, `DOT` |
|
||||||
| **`MessageBoxType`** | 消息框类型 | `OK`, `OKCancel`, `YesNo`, `YesNoCancel`, `RetryCancel`, `AbortRetryIgnore` |
|
| `MessageBoxType` | 消息框类型 | `OK`, `OKCancel`, `YesNo`, ... |
|
||||||
| **`MessageBoxResult`** | 消息框结果 | `OK`, `Cancel`, `Yes`, `No`, `Abort`, `Retry`, `Ignore` |
|
| `MessageBoxResult` | 结果 | `OK`, `Cancel`, `Yes`, `No`, `Abort`, `Retry`, `Ignore` |
|
||||||
|
|
||||||
### 结构体 (Structs)
|
### 结构体
|
||||||
|
|
||||||
| 结构体 | 描述 |
|
| 结构体 | 描述 |
|
||||||
| :----------------- | :----------------------------------------------------------- |
|
| -------------- | -------------------------------------- |
|
||||||
| **`ControlText`** | 封装了所有文本样式属性，包括字体、大小、颜色、粗体、斜体、下划线、删除线等。 |
|
| `ControlText` | 字体/字号/颜色/粗体/斜体/下划线/删除线 |
|
||||||
| **`RouRectangle`** | 定义圆角矩形的圆角椭圆尺寸，包含宽度和高度属性。 |
|
| `RouRectangle` | 圆角矩形的角部椭圆尺寸 |
|
||||||
|
|
||||||
**使用示例：**
|
------
|
||||||
|
|
||||||
cpp
|
## 🧩 控件库
|
||||||
|
|
||||||
```c++
|
### 1) 基础控件
|
||||||
// 创建一个复杂的文本样式
|
|
||||||
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;
|
| Button | `Button.h` | 多功能按钮 | 形状/模式、悬停/点击色、回调，**单行截断** + **Tooltip**（v2.1.0） |
|
||||||
```
|
| Label | `Label.h` | 文本标签 | 透明/不透明背景，自定义字体 |
|
||||||
|
| TextBox | `TextBox.h` | 输入/显示框 | 输入/只读，整合 EasyX `InputBox` |
|
||||||
|
|
||||||
|
### 2) 容器控件
|
||||||
|
|
||||||
## 🧩 控件库大全
|
|
||||||
|
|
||||||
### 1. 基础控件
|
|
||||||
|
|
||||||
| 控件 | 头文件 | 描述 | 关键特性 |
|
|
||||||
| :---------- | :---------- | :------------ | :------------------------------------------------------ |
|
|
||||||
| **Button** | `Button.h` | 多功能按钮 | 支持多种模式/形状/状态，可设置悬停/点击颜色，自定义回调 |
|
|
||||||
| **Label** | `Label.h` | 文本标签 | 支持背景透明/不透明，自定义字体样式 |
|
|
||||||
| **TextBox** | `TextBox.h` | 输入框/显示框 | 支持输入和只读模式，集成EasyX的`InputBox` |
|
|
||||||
|
|
||||||
### 2. 容器控件
|
|
||||||
|
|
||||||
| 控件 | 头文件 | 描述 |
|
| 控件 | 头文件 | 描述 |
|
||||||
| :--------- | :--------- | :------------------------------------------------------- |
|
| ------ | ---------- | ------------------------------------------------------------ |
|
||||||
| **Canvas** | `Canvas.h` | 容器控件，可作为其他控件的父容器，支持自定义边框和背景。 |
|
| Canvas | `Canvas.h` | 父容器，自定义边框/背景，**内置 HBox/VBox 自动布局**（v2.1.0） |
|
||||||
| **Window** | `Window.h` | 顶级窗口，所有控件的最终容器，负责消息循环和调度。 |
|
| Window | `Window.h` | 顶层容器，消息循环与分发，**可拉伸**（v2.1.0） |
|
||||||
|
|
||||||
### 3. 高级控件
|
### 3) 高级控件
|
||||||
|
|
||||||
| 控件 | 头文件 | 描述 | 关键特性 |
|
| 控件 | 头文件 | 描述 | 关键点 |
|
||||||
| :--------- | :--------- | :------- | :----------------------------------------------------------- |
|
| ------ | ---------- | -------- | --------------------------------------------------------- |
|
||||||
| **Table** | `Table.h` | 数据表格 | **框架功能亮点**，支持分页显示、自定义表头和数据、自动计算列宽、翻页按钮。 |
|
| Table | `Table.h` | 数据表格 | 分页/表头/列宽自动、翻页控件重叠/透明叠影已修复（v2.1.0） |
|
||||||
| **Dialog** | `Dialog.h` | 对话框类 | 实现完整的对话框功能，支持多种按钮组合和异步结果回调。自动处理布局、背景保存恢复和生命周期管理。 |
|
| Dialog | `Dialog.h` | 对话框 | 支持模态/非模态，自动布局与背景保存/恢复 |
|
||||||
|
|
||||||
**表格控件示例：**
|
### 4) 静态工厂
|
||||||
|
|
||||||
cpp
|
| 控件 | 头文件 | 描述 | 关键点 |
|
||||||
|
| ---------- | -------------- | ---------- | ----------------------------------- |
|
||||||
|
| 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++
|
```c++
|
||||||
// 创建一个表格
|
Canvas row(20, 20, 760, 120);
|
||||||
auto myTable = std::make_unique<Table>(50, 50);
|
row.layout.kind = LayoutKind::HBox;
|
||||||
|
|
||||||
// 设置表头
|
auto mk = [](int w, int h, float weight){
|
||||||
myTable->setHeaders({ "ID", "姓名", "年龄", "职业" });
|
auto c = std::make_unique<Control>(0,0,w,h);
|
||||||
|
c->layout.marginL = 8; c->layout.marginR = 8;
|
||||||
// 添加数据行
|
c->layout.alignY = LayoutParams::Stretch;
|
||||||
myTable->setData({ "1", "张三", "25", "工程师" });
|
c->layout.weight = weight;
|
||||||
myTable->setData({ "2", "李四", "30", "设计师" });
|
return c;
|
||||||
myTable->setData({ "3", "王五", "28", "产品经理" });
|
};
|
||||||
|
row.addControl(mk(100,40, 1.f));
|
||||||
// 设置每页显示2行
|
row.addControl(mk(100,40, 2.f));
|
||||||
myTable->setRowsPerPage(2);
|
row.addControl(mk(100,40, 1.f));
|
||||||
|
|
||||||
// 设置表格样式
|
|
||||||
myTable->textStyle.nHeight = 16;
|
|
||||||
myTable->setTableBorder(RGB(50, 50, 50));
|
|
||||||
myTable->setTableBk(RGB(240, 240, 240));
|
|
||||||
|
|
||||||
// 添加到窗口
|
|
||||||
mainWindow.addControl(std::move(myTable));
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
------
|
||||||
|
|
||||||
|
## 🗂 选项卡（Tabs，早期版本）
|
||||||
|
|
||||||
### 4. 静态工厂类
|
- 页签条（按钮组） + 页面容器（`Canvas`）
|
||||||
|
- 透明主题：页面区域**背景快照**切换，避免叠影
|
||||||
|
- API 草图：`tabs.addPage(title, canvasPtr); tabs.setActive(index);`
|
||||||
|
|
||||||
| 控件 | 头文件 | 描述 | 关键特性 |
|
------
|
||||||
| :------------- | :------------- | :--------------- | :----------------------------------------------------------- |
|
|
||||||
| **MessageBox** | `MessageBox.h` | 对话框的工厂调用 | 静态方法调用，无需实例化，自动处理模态和非模态的逻辑差异集成到窗口的对话框管理系统中提供去重机制防止重复对话框 |
|
|
||||||
|
|
||||||
**消息框使用示例：**
|
## ✂️ 文本单行截断 & 🫧 Tooltip
|
||||||
|
|
||||||
cpp
|
- **按钮截断**：多字节字符集下**中/英分治**，基于像素宽度阈值追加 `...`
|
||||||
|
- **Tooltip**：延时出现、自动隐藏；默认文字=按钮文本，可自定义；使用控件级**背景快照/恢复**
|
||||||
|
|
||||||
```c++
|
------
|
||||||
// 模态消息框（阻塞直到关闭）
|
|
||||||
auto result = StellarX::MessageBox::ShowModal(
|
|
||||||
mainWindow,
|
|
||||||
"确认要执行此操作吗？",
|
|
||||||
"确认",
|
|
||||||
StellarX::MessageBoxType::YesNo
|
|
||||||
);
|
|
||||||
|
|
||||||
if (result == StellarX::MessageBoxResult::Yes)
|
## 🧊 透明背景与背景快照
|
||||||
{
|
|
||||||
// 用户选择了"是"
|
|
||||||
}
|
|
||||||
|
|
||||||
// 非模态消息框（异步回调）
|
- **通用约定**：首绘前 `captureBackground(rect)`，隐藏/覆盖前 `restoreBackground()`
|
||||||
StellarX::MessageBox::ShowAsync(
|
- **Table**：快照区域**包含表头**；翻页后立即恢复 + 重绘，分页控件整体居中
|
||||||
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++
|
- 不适合高性能游戏/复杂动画；极端 DPI 需复核度量
|
||||||
class MyCustomControl : public Control {
|
- 暂无无障碍能力
|
||||||
public:
|
- Windows 专用，不跨平台
|
||||||
MyCustomControl(int x, int y) : Control(x, y, 100, 100) {}
|
- 复杂商业前端建议用 Qt / wxWidgets / ImGui / Electron
|
||||||
|
|
||||||
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; }
|
MIT（见 `LICENSE`）。
|
||||||
bool model() const override { return false; }
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
|
## 👥 贡献指南
|
||||||
|
|
||||||
|
- 遵循现有 C++ 风格
|
||||||
|
- 新特性需附示例与 README 更新
|
||||||
|
- 提交前请自测，并说明变更动机
|
||||||
|
- Bug/想法请提 Issue
|
||||||
|
|
||||||
### 2. 布局管理
|
## 🙏 致谢
|
||||||
|
|
||||||
当前版本星垣主要采用**绝对定位**。对于简单布局，您可以通过计算坐标来实现。对于复杂布局，可以考虑：
|
- 感谢 [EasyX](https://easyx.cn/)
|
||||||
|
- 感谢推崇**简洁/高效/清晰**的开发者
|
||||||
- 在`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](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世界的一颗可靠基石，无论是用于学习、教学还是创造实用的工具。
|
|
||||||
|
|
||||||
## 📞 支持与反馈
|
## 📞 支持与反馈
|
||||||
|
|
||||||
如果您在使用过程中遇到问题或有任何建议：
|
- 查看 [examples/](examples/)
|
||||||
|
- 查阅 [更新日志](CHANGELOG.md / CHANGELOG.en.md)
|
||||||
1. 查看 [示例代码](examples/) 获取使用参考
|
- 在 GitHub 提交 Issue
|
||||||
2. 查阅 [更新日志](CHANGELOG.md) 了解最新变化
|
|
||||||
3. 在GitHub仓库提交Issue反馈问题
|
|
||||||
|
|
||||||
------
|
|
||||||
|
|
||||||
*星垣框架 - 轻若尘埃，繁星为界*
|
|
||||||
Reference in New Issue
Block a user