From 95149238e221b19a15bfa750bcf937620e23fd47 Mon Sep 17 00:00:00 2001 From: Ysm-04 <3150131407@qq.com> Date: Fri, 3 Oct 2025 16:34:58 +0800 Subject: [PATCH] feat: add a new awesome feature --- CHANGELOG.en.md | 151 ++++++++++ CHANGELOG.md | 8 +- CONTRIBUTING.en.md | 94 ++++++ README.en.md | 451 ++++++++++++++++++++++++++++ README.md | 8 +- docs/CODE_OF_CONDUCT.en.md | 25 ++ examples/register-viewer/README.md | 17 ++ examples/register-viewer/main.cpp | 462 +++++++++++++++++++++++++++++ src/textBox.cpp | 1 + 9 files changed, 1215 insertions(+), 2 deletions(-) create mode 100644 CHANGELOG.en.md create mode 100644 CONTRIBUTING.en.md create mode 100644 README.en.md create mode 100644 docs/CODE_OF_CONDUCT.en.md create mode 100644 examples/register-viewer/README.md create mode 100644 examples/register-viewer/main.cpp diff --git a/CHANGELOG.en.md b/CHANGELOG.en.md new file mode 100644 index 0000000..9b98cd4 --- /dev/null +++ b/CHANGELOG.en.md @@ -0,0 +1,151 @@ +# Changelog + +All notable changes to the StellarX project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +[中文文档](CHANGELOG.md) + +## [v2.0.1] - 2025-10-03 + +### Added + +- New example: 32-bit register viewer tool implemented based on StellarX (supports bit inversion, left shift, right shift, hexadecimal/decimal signed/unsigned toggle, grouped binary display). + - Example path: `examples/register-viewer/` +- `TextBox` added `setText` API, allowing external setting of text box content +- `TextBox::setText` API modified: immediately calls `draw` method to redraw after setting text +- `Button` added `setButtonClick` API, allowing external functions to modify button click state and execute corresponding callback functions +- ==All documents updated with corresponding English versions(.en)== + +## [v2.0.0] - 2025-09-21 + +### Overview +v2.0.0 is a major release. This release introduces dialog and message box factory (Dialog / MessageBox), with several important fixes and improvements to event distribution, API semantics, and internal resource management. + +Some APIs/behaviors have breaking changes that are not backward compatible. + +### Added +- **Dialog System**: + - Added `Dialog` class, inheriting from `Canvas`, for building modal and non-modal dialogs + - Added `MessageBox` factory class, providing two convenient APIs: `ShowModal` (synchronous blocking) and `ShowAsync` (asynchronous callback) + - Supports six standard message box types: `OK`, `OKCancel`, `YesNo`, `YesNoCancel`, `RetryCancel`, `AbortRetryIgnore` + - Automatically handles dialog layout, background saving and restoration, event propagation, and lifecycle management + +- **Enhanced Event System**: + - All controls' `handleEvent` methods now return `bool` type, indicating whether the event was consumed + - Introduced event consumption mechanism, supporting finer-grained event propagation control + - Window class event loop now prioritizes dialog event processing + +- **Control State Management**: + - Control base class added `dirty` flag and `setDirty()` method, uniformly managing redraw state + - All controls now implement `IsVisible()` and `model()` methods + +- **API Enhancements**: + - Button class added `setButtonFalseColor()` method + - TextBox class `setMaxCharLen()` now accepts `size_t` type parameter + - Window class added dialog management methods and duplicate detection mechanism + +### Breaking Changes +- **API Signature Changes**: + - All controls' `handleEvent(const ExMessage& msg)` method changed from returning `void` to returning `bool` + - Control base class added pure virtual functions `IsVisible() const` and `model() const`, all derived classes must implement them + +- **Resource Management Changes**: + - Control base class style saving changed from stack objects to heap objects, managed using pointers + - Enhanced resource release safety, all resources are properly released in destructors + +- **Event Handling Logic**: + - Window's `runEventLoop()` method completely rewritten, now prioritizes dialog events + - Introduced event consumption mechanism, events do not continue propagating after being consumed + +### Fixed +- **Memory Management**: + - Fixed memory leak issue in `Button::setFillIma()` + - Fixed resource release issues in Control base class destructor + - Fixed background image resource management issues in Dialog class + +- **Layout and Rendering**: + - Fixed pagination calculation, column width, and row height boundary issues in `Table` component + - Fixed layout disorder caused by `pX` coordinate accumulation error in `Table` + - Fixed dirty determination issue in `Canvas::draw()` that prevented child controls from being drawn + - Fixed asymmetric call issues between `TextBox::draw()` and `restoreStyle()` + +- **Event Handling**: + - Fixed window event distribution logic to ensure dialog/top-level controls prioritize event processing + - Fixed delayed state updates when mouse moves out of button area + - Fixed race conditions in non-modal dialog event handling + +- **Other Issues**: + - Fixed potential errors in text measurement and rendering + - Fixed incomplete background restoration after dialog closure + - Fixed z-order management issues in multi-dialog scenarios + +### Changed +- **Code Quality**: + - Refactored numerous internal APIs, enhancing exception safety and maintainability + - Used smart pointers and modern C++ features to replace raw new/delete + - Unified code style and naming conventions + +- **Performance Optimization**: + - Optimized event processing flow, reducing unnecessary redraws + - Improved dialog background saving and restoration mechanism + - Reduced memory allocation and copy operations + +- **Documentation and Examples**: + - Added detailed usage examples for all new features + - Improved code comments and API documentation + - Updated README and CHANGELOG to reflect latest changes + +## [1.1.0] - 2025-09-08 + +### Added +- **Window Class API Enhancements**: + - Added complete getter method set, improving class encapsulation and usability + - `getHwnd()` - Get window handle for integration with native Windows API + - `getWidth()` - Get window width + - `getHeight()` - Get window height + - `getHeadline()` - Get window title + - `getBkcolor()` - Get window background color + - `getBkImage()` - Get window background image pointer + - `getControls()` - Get reference to control management container, allowing iteration and manipulation of added controls + +### Improved +- **API Consistency**: Provided symmetric setter and getter methods for all important attributes +- **Code Documentation**: Further improved class comments, making them clearer and more professional + +## [1.0.0] - 2025-09-08 + +### Release Summary +First stable release + +### Added + +- First stable version of StellarX framework +- Complete control library: Button, Label, TextBox, Canvas, Table, and Window +- CMake-based build system +- Detailed documentation and example code +- **Explicit declaration: This framework is specifically designed for Windows platform** + +### Released +- **First release of pre-compiled binary library files**, facilitating quick integration without compiling from source +- Provided release packages include: + - `StellarX-v1.0.0-x64-Windows-msvc-x64.zip` + - **Build Environment**: Visual Studio 2022 (MSVC v143) + - **Architecture**: x64 (64-bit) + - **Runtime Library**: `/MD` + - **Build Modes**: `Release | Debug` + - **Contents**: Includes all necessary header files (`include/`) and static library files (`lib/StellarX-Debug.lib StellarX-Release.lib`) + +### Core Features +- Modular design following SOLID principles +- Unified control interface (`draw()` and `handleEvent()`) +- Support for multiple control shapes and styles +- Custom event handling callbacks +- Lightweight design with no external dependencies + +## [0.1.0] - 2025-08-15 +### Added +- Initial project structure and core architecture +- Control base class and basic event handling system +- Basic examples and documentation setup \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index ed2aa08..d9afaa4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,12 +5,18 @@ StellarX 项目所有显著的变化都将被记录在这个文件中。 格式基于 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 -## [v2.0.1] - 2025 - 10 - 01 +[English document](CHANGELOG.en.md) + +## [v2.0.1] - 2025 - 10 - 03 ### 新增 +- 新增示例：基于 StellarX 实现的 32 位寄存器查看工具（支持位取反、左移、右移，十六进制/十进制带符号/无符号切换，分组二进制显示）。 + - 示例路径：`examples/register-viewer/` - `TextBox`新增`setText`API，可在外部设置文本框内容 +- `TextBox::setText`API修改：在设置文本后立即调用`draw`方法重绘 - `Button`新增`setButtonClick`API,允许通过外部函数修改按钮的点击状态，并执行相应的回调函数 +- ==所有文档更新对应英文版本== ## [v2.0.0] - 2025-09-21 diff --git a/CONTRIBUTING.en.md b/CONTRIBUTING.en.md new file mode 100644 index 0000000..8fead7f --- /dev/null +++ b/CONTRIBUTING.en.md @@ -0,0 +1,94 @@ +# Contributing to StellarX + +Thank you for your interest in contributing to StellarX! This document provides guidelines and steps for contributing. + +StellarX is a C++ GUI framework built for the **Windows platform**, based on the EasyX graphics library. + +## Development Environment Setup + +1. Install Visual Studio 2019 or later +2. Install the corresponding version of EasyX graphics library +3. Install CMake 3.12 or later +4. Clone the project repository +5. Use CMake to generate the solution and compile + +## How to Contribute + +### Reporting Bugs +1. Check [Issues](../../issues) to see if the bug has already been reported. +2. If not, create a new Issue. +3. Use the "Bug Report" template. +4. Provide a **clear title and description**. +5. Include relevant code snippets, screenshots, or steps to reproduce the issue. + +### Suggesting Enhancements +1. Check existing Issues to see if your idea has been suggested. +2. Create a new Issue using the "Feature Request" template. +3. Clearly describe the new feature and explain why it would be useful. + +### Submitting Code Changes (Pull Requests) +1. **Fork** the repository on GitHub. +2. **Clone** your forked repository to your local machine. +3. Create a **new branch** for your feature or bug fix (`git checkout -b my-feature-branch`). +4. **Make your changes**. Ensure your code follows the project's style (see below). +5. **Commit your changes** with clear, descriptive commit messages. +6. **Push** your branch to your forked GitHub repository (`git push origin my-feature-branch`). +7. Open a **Pull Request** against the original StellarX repository's `main` branch. + +## Code Style Guide + +* Follow the existing code formatting and naming conventions in the project. +* Use meaningful names for variables, functions, and classes. +* Comment your code when necessary, especially for complex logic. +* Ensure your code compiles without warnings. +* Test your changes thoroughly. +* Use **4 spaces** for indentation (no tabs) +* Class names use **PascalCase** (e.g., `ClassName`) +* Functions and variables use **camelCase** (e.g., `functionName`, `variableName`) +* Constants use **UPPER_CASE** (e.g., `CONSTANT_VALUE`) +* Member variables use **m_** prefix (e.g., `m_memberVariable`) +* Use meaningful names for control properties, avoid abbreviations +* Add detailed comments for all public interfaces +* Follow RAII principles for resource management + +## Example Code Style + +```c++ +// Good Example +class MyControl : public Control { +public: + MyControl(int x, int y, int width, int height) + : Control(x, y, width, height), m_isActive(false) {} + + void draw() override { + // Drawing logic + } + +private: + bool m_isActive; +}; + +// Bad Example +class my_control: public Control{ +public: + my_control(int x,int y,int w,int h):Control(x,y,w,h),active(false){} + void Draw() override{ + // Drawing logic + } +private: + bool active; +}; +``` + +## Project Structure + +Please follow the project's directory structure: + +- Header files go in the `include/StellarX/` directory +- Implementation files go in the `src/` directory +- Example code goes in the `examples/` directory + +## Questions? + +If you have any questions, feel free to open an Issue or contact the maintainers. + diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..5c6fb66 --- /dev/null +++ b/README.en.md @@ -0,0 +1,451 @@ +# StellarX GUI Framework + +[中文文档](README.md) + +------ + +![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) + +![C++](https://img.shields.io/badge/C++-17+-00599C?logo=cplusplus&logoColor=white) +![Windows](https://img.shields.io/badge/Platform-Windows-0078D6?logo=windows) +![EasyX](https://img.shields.io/badge/Based_on-EasyX-00A0EA) +![License](https://img.shields.io/badge/License-MIT-blue.svg) +![Architecture](https://img.shields.io/badge/Architecture-Modular%20OOP-brightgreen) +![CMake](https://img.shields.io/badge/Build-CMake-064F8C?logo=cmake) + +> **"Bound by Stars, Light as Dust"** — A native C++ GUI framework for Windows platform, featuring extreme lightweight 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. + +It is a **pure teaching-level, tool-level framework** designed to help developers deeply understand GUI principles and quickly build lightweight Windows tools. + +--- + + + +## 📦 Project Structure & Design Philosophy + +StellarX framework adopts classic **Object-Oriented** and **modular** design with a clear and standardized project structure: + +```markdown + +StellarX/ +├── include/ # Header files directory +│ └── StellarX/ # Framework header files +│ ├── StellarX.h # Main include header - one-click import of entire framework +│ ├── CoreTypes.h # ★ Core ★ - Single source of truth for all enums and structs +│ ├── Control.h # Abstract base class - defines unified interface for all controls +│ ├── Button.h # Button control +│ ├── Window.h # Window management +│ ├── Label.h # Label control +│ ├── TextBox.h # Text box control +│ ├── Canvas.h # Canvas container +│ ├── Dialog.h # Dialog control (new in v2.0.0) +│ ├── MessageBox.h # Message box factory (new in v2.0.0) +│ └── Table.h # Table control +├── src/ # Source files directory +│ ├── Control.cpp +│ ├── Button.cpp +│ ├── Window.cpp +│ ├── Label.cpp +│ ├── TextBox.cpp +│ ├── Canvas.cpp +│ ├── Table.cpp +│ ├── Dialog.cpp # v2.0.0 new +│ └── MessageBox.cpp # v2.0.0 new +├── examples/ # Example code directory +│ └── demo.cpp # Basic demonstration +├── docs/ # Documentation directory +│ └── CODE_OF_CONDUCT.md # Code of Conduct +├── CMakeLists.txt # CMake build configuration +├── CONTRIBUTING.md # Contribution guide +├── CHANGELOG.md # Changelog +├── Doxyfile # Doxygen configuration +├── LICENSE # MIT License +└── README.md # Project description +``` + +### **Design Philosophy:** + +1. **Single Responsibility Principle (SRP)**: Each class/file is responsible for one thing only. +2. **Dependency Inversion Principle (DIP)**: High-level modules (like `Window`) don't depend on low-level modules (like `Button`), both depend on abstractions (`Control`). +3. **Open/Closed Principle (OCP)**: New controls can be easily extended by inheriting the `Control` base class without modifying existing code. +4. **Consistency**: All controls share unified `draw()` and `handleEvent()` interfaces. + +## 🚀 Core Features + +- **Extreme Lightweight**: Core library compiles to only ~1.2MB, with zero external dependencies. Generated applications are compact. +- **Clear Modular Architecture**: Uses `CoreTypes.h` to uniformly manage all types, eliminating duplicate definitions and greatly improving maintainability. +- **Native C++ Performance**: Built directly on EasyX and Win32 API, providing near-native execution efficiency with very low memory footprint (typically <10MB). +- **Complete Control System**: 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. +- **Simple & Intuitive API**: Uses classic object-oriented design, code as documentation, low learning curve. +- **Standard Project Structure**: Adopts standard include/src separation structure, supports CMake build, easy to integrate and use. +- **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. +- **Dialog System**: New complete dialog support, including modal and non-modal dialogs, automatically handling background saving and restoration. + +## ⚡ Quick Start (5 Minutes to Get Started) + +> **🎯 Latest Version Download** +> 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 + +- **OS**: Windows 10 or higher +- **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) +- **Build Tool**: CMake 3.12+ (optional, recommended) + +### Install EasyX + +1. Visit [EasyX official website](https://easyx.cn/) to download the latest version +2. Run the installer, select the version matching your Visual Studio version +3. After installation, no additional configuration is needed, StellarX framework will automatically link EasyX + +### Method 1: Using CMake Build (Recommended) + +1. **Clone the project**: + + ```bash + git clone https://github.com/Ysm-04/StellarX.git + cd StellarX + ``` + +2. **Generate build system**: + + ```bash + mkdir build + cd build + cmake .. + ``` + +3. **Compile the project**: + + ```bash + cmake --build . + ``` + +4. **Run the example**: + + ```bash + ./examples/Demo + ``` + +### Method 2: Manual Integration into Existing Project + +1. **Copy the include and src directories** to your project +2. **Configure include paths** to ensure the compiler can find the `include/StellarX/` directory +3. **Add all .cpp files** to your project for compilation + +### Create Your First StellarX Application + +```cpp +// Just include this one header to use all features +#include "StellarX.h" + +// Program entry point (use WinMain for better compatibility) +int WINAPI WinMain(_In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, _In_ LPSTR lpCmdLine, _In_ int nShowCmd) +{ + // 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