commit d62d8a90d6bec7ffdcdcc0583e6881da83e05255 Author: Ysm-04 <3150131407@qq.com> Date: Sun Sep 7 00:19:40 2025 +0800 initial commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..87d81c7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,77 @@ +# 编译生成文件 +*.exe +*.ilk +*.obj +*.pdb +*.o +*.a +*.lib +*.dll +*.exp +*.so +*.dylib + +# 构建目录 +build/ +bin/ +obj/ +Debug/ +Release/ +x64/ +x86/ +Win32/ + +# Visual Studio 文件 +.vs/ +*.sln +*.vcxproj +*.vcxproj.filters +*.vcxproj.user +*.suo +*.ncb +*.user +*.sdf +ipch/ +*.aps +*.res +*.tlog +*.lastbuildstate +*.idb +*.pch + +# CMake 生成文件 +CMakeFiles/ +CMakeCache.txt +cmake_install.cmake +Makefile +*.cmake +*.cmake.* +CTestTestfile.cmake +Testing/ +_deps/ + +# 文档生成 +docs/html/ +docs/latex/ +docs/man/ +docs/rtf/ +docs/xml/ + +# 临时文件 +*.tmp +*.temp +*.log +*.swp +*.swo + +# EasyX 临时文件 +*.jpg +*.bmp +*.png +*.tga + +# 其他 +.DS_Store +Thumbs.db +ehthumbs.db +Desktop.ini \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..751bb51 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,28 @@ +# 更新日志 + +StellarX 项目所有显著的变化都将被记录在这个文件中。 + +格式基于 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 + +## [1.0.0] - 2025-09-06 + +### 新增 +- StellarX 框架的第一个稳定版本 +- 完整的控件库：按钮、标签、文本框、画布、表格和窗口 +- 基于 CMake 的构建系统 +- 详细的文档和示例代码 +- **明确声明：本框架专为 Windows 平台设计** + +### 核心特性 +- 模块化设计，遵循 SOLID 原则 +- 统一的控件接口（draw() 和 handleEvent()） +- 支持多种控件形状和样式 +- 自定义事件处理回调 +- 轻量级设计，无外部依赖 + +## [0.1.0] - 2025-08-15 +### 新增 +- 初始项目结构和核心架构 +- Control 基类和基本事件处理系统 +- 基础示例和文档设置 \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..d9f20ed --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,130 @@ +cmake_minimum_required(VERSION 3.15) +project(StellarX VERSION 1.0.0 LANGUAGES CXX) + +# 设置C++标准 +set(CMAKE_CXX_STANDARD 17) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_CXX_EXTENSIONS OFF) + +# Windows特定设置 +if(WIN32) + add_definitions(-DWIN32 -D_WINDOWS) + set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON) + + # 设置Windows子系统 + set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} /SUBSYSTEM:WINDOWS") +endif() + +# 设置输出目录 +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) + +# 包含目录 +include_directories(include) + +# Windows API库 +if(WIN32) + find_library(GDI32_LIBRARY gdi32) + find_library(USER32_LIBRARY user32) + find_library(KERNEL32_LIBRARY kernel32) + set(WIN32_LIBS ${GDI32_LIBRARY} ${USER32_LIBRARY} ${KERNEL32_LIBRARY}) +endif() + +# 创建库 +file(GLOB_RECURSE SOURCES "src/*.cpp") +add_library(StellarX STATIC ${SOURCES}) + +# 链接Windows库 +if(WIN32) + target_link_libraries(StellarX ${WIN32_LIBS}) +endif() + +# 设置库属性 +set_target_properties(StellarX PROPERTIES + VERSION ${PROJECT_VERSION} + SOVERSION 1 + PUBLIC_HEADER "include/StellarX/StellarX.h" + OUTPUT_NAME "StellarX" +) + +# 安装规则 +install(DIRECTORY include/StellarX DESTINATION include) +install(TARGETS StellarX + ARCHIVE DESTINATION lib + LIBRARY DESTINATION lib + RUNTIME DESTINATION bin + PUBLIC_HEADER DESTINATION include/StellarX +) + +# 示例程序 +if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/examples) + file(GLOB EXAMPLE_SOURCES "examples/*.cpp") + foreach(example_source ${EXAMPLE_SOURCES}) + get_filename_component(example_name ${example_source} NAME_WE) + add_executable(${example_name} ${example_source}) + target_link_libraries(${example_name} StellarX ${WIN32_LIBS}) + + # 设置Windows子系统 + if(WIN32) + set_target_properties(${example_name} PROPERTIES + LINK_FLAGS "/SUBSYSTEM:WINDOWS" + ) + endif() + + # 安装示例 + install(TARGETS ${example_name} DESTINATION bin) + endforeach() +endif() + +# 文档生成选项 +option(BUILD_DOCS "Build documentation" OFF) +if(BUILD_DOCS) + find_package(Doxygen) + if(Doxygen_FOUND) + set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/docs) + set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${CMAKE_CURRENT_SOURCE_DIR}/README.md) + set(DOXYGEN_PROJECT_NAME "StellarX GUI Framework") + set(DOXYGEN_PROJECT_NUMBER ${PROJECT_VERSION}) + set(DOXYGEN_PROJECT_BRIEF "A lightweight, modular C++ GUI framework for Windows") + set(DOXYGEN_INPUT ${CMAKE_CURRENT_SOURCE_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR}/src) + set(DOXYGEN_RECURSIVE YES) + set(DOXYGEN_EXTRACT_ALL YES) + set(DOXYGEN_EXTRACT_PRIVATE YES) + set(DOXYGEN_EXTRACT_STATIC YES) + set(DOXYGEN_SOURCE_BROWSER YES) + set(DOXYGEN_GENERATE_TREEVIEW YES) + set(DOXYGEN_HAVE_DOT YES) + set(DOXYGEN_CALL_GRAPH YES) + set(DOXYGEN_CALLER_GRAPH YES) + + doxygen_add_docs( + docs + ${DOXYGEN_INPUT} + COMMENT "Generate HTML documentation" + ) + + install(DIRECTORY ${DOXYGEN_OUTPUT_DIRECTORY}/html DESTINATION docs) + endif() +endif() + +# 打包配置 +include(InstallRequiredSystemLibraries) +set(CPACK_PACKAGE_NAME ${PROJECT_NAME}) +set(CPACK_PACKAGE_VERSION ${PROJECT_VERSION}) +set(CPACK_PACKAGE_DESCRIPTION "A lightweight, modular C++ GUI framework for Windows") +set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "星垣 (StellarX) - A lightweight Windows GUI framework") +set(CPACK_PACKAGE_VENDOR "StellarX Development Team") +set(CPACK_PACKAGE_CONTACT "contact@stellarx.dev") +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE") +set(CPACK_RESOURCE_FILE_README "${CMAKE_CURRENT_SOURCE_DIR}/README.md") +set(CPACK_PACKAGE_INSTALL_DIRECTORY "StellarX") +set(CPACK_NSIS_MODIFY_PATH ON) + +if(WIN32) + set(CPACK_GENERATOR "ZIP;NSIS") +else() + set(CPACK_GENERATOR "ZIP") +endif() + +include(CPack) \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ab0c090 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,93 @@ +# 为 StellarX 做贡献 + +感谢您有兴趣为 StellarX 做出贡献！本文档提供了贡献的指南和步骤。 + +StellarX 是一个为 **Windows 平台**打造的 C++ GUI 框架，基于 EasyX 图形库。 + +## 开发环境设置 + +1. 安装 Visual Studio 2019 或更高版本 +2. 安装对应版本的 EasyX 图形库 +3. 安装 CMake 3.12 或更高版本 +4. 克隆项目仓库 +5. 使用 CMake 生成解决方案并编译 + +## 如何贡献 + +### 报告错误 +1. 检查 [Issues](../../issues) 看看这个错误是否已经被报告过。 +2. 如果没有，请创建一个新的 Issue。 +3. 使用 "Bug 报告" 模板。 +4. 提供**清晰的标题和描述**。 +5. 包括相关的代码片段、截图或重现问题的步骤。 + +### 建议功能增强 +1. 检查现有的 Issue 中是否有你的想法。 +2. 使用 "功能请求" 模板创建一个新的 Issue。 +3. 清晰地描述新功能，并解释它为何有用。 + +### 提交代码更改 (拉取请求 Pull Requests) +1. **Fork** GitHub 上的仓库。 +2. **Clone** 你 fork 的仓库到本地机器。 +3. 为你的功能或错误修复创建一个**新分支** (`git checkout -b my-feature-branch`)。 +4. **进行你的更改**。确保你的代码遵循项目的风格（见下文）。 +5. **提交你的更改**，并附上清晰描述性的提交信息。 +6. **Push** 你的分支到你 fork 的 GitHub 仓库 (`git push origin my-feature-branch`)。 +7. 针对原始 StellarX 仓库的 `main` 分支发起一个**拉取请求 (Pull Request)**。 + +## 代码风格指南 + +* 遵循项目中现有的代码格式和命名约定。 +* 为变量、函数和类使用有意义的名称。 +* 在必要时注释你的代码，特别是复杂的逻辑。 +* 确保你的代码编译时没有警告。 +* 彻底测试你的更改。 +* 使用 **4个空格** 进行缩进（不要使用制表符） +- 类名使用 **PascalCase**（如 `ClassName`） +- 函数和变量使用 **camelCase**（如 `functionName`, `variableName`） +- 常量使用 **UPPER_CASE**（如 `CONSTANT_VALUE`） +- 成员变量以 **m_** 前缀（如 `m_memberVariable`） +- 控件属性使用有意义的名称，避免缩写 +- 为所有公共接口添加详细的注释 +- 遵循 RAII 原则管理资源 + +## 示例代码风格 + +```c++ + +// 好的示例 +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 { + // 绘制逻辑 + } + +private: + bool m_isActive; +}; + +// 不好的示例 +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{ + // 绘制逻辑 + } +private: + bool active; +}; +``` + +## 项目结构 + +请遵循项目的目录结构： +- 头文件放在 `include/StellarX/` 目录 +- 实现文件放在 `src/` 目录 +- 示例代码放在 `examples/` 目录 + +## 问题？ + +如果你有任何问题，可以随时开一个 Issue 或联系维护者。 \ No newline at end of file diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..33e434c --- /dev/null +++ b/Doxyfile @@ -0,0 +1,219 @@ +# Doxyfile 1.9.1 + +# 项目相关配置 +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "星垣 (StellarX) GUI Framework" +PROJECT_NUMBER = 1.0.0 +PROJECT_BRIEF = "A lightweight, modular C++ GUI framework for Windows" +PROJECT_LOGO = +OUTPUT_DIRECTORY = docs +CREATE_SUBDIRS = NO +ALLOW_UNICODE_NAMES = YES +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = YES +JAVADOC_BANNER = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 4 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +EXTENSION_MAPPING = +MARKDOWN_SUPPORT = YES + +# 构建类型 +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_PACKAGE = YES +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE= NO +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTOR_1ST = NO +SORT_GROUP_NAMES = YES +SORT_BY_SCOPE_NAME = YES +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_FILES = YES +SHOW_NAMESPACES = YES +FILE_VERSION_FILTER = +LAYOUT_FILE = +CITE_BIB_FILES = + +# 输入配置 +INPUT = include src README.md +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.h *.hpp *.cpp *.c *.cc *.cxx *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.idl *.ddl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py *.f90 *.f *.for *.vhd *.vhdl *.md +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = examples +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = README.md + +# 源代码浏览配置 +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES + +# HTML输出配置 +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = +HTML_EXTRA_FILES = +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 +HTML_TIMESTAMP = YES +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_NAME = Publisher +GENERATE_HTMLHELP = NO +GENERATE_CHI = NO +GENERATE_QHP = NO +GENERATE_ECLIPSEHELP = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = YES +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +FORMULA_FONTSIZE = 10 +FORMULA_TRANSPARENT = YES +USE_MATHJAX = NO +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = +SEARCHENGINE = YES +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = + +# LaTeX输出配置 +GENERATE_LATEX = NO + +# RTF输出配置 +GENERATE_RTF = NO + +# Man page输出配置 +GENERATE_MAN = NO + +# XML输出配置 +GENERATE_XML = NO + +# DOCBOOK输出配置 +GENERATE_DOCBOOK = NO + +# 自动生成配置 +GENERATE_AUTOGEN_DEF = NO + +# 配置生成器 +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = WIN32=1 \ + _WINDOWS=1 \ + UNICODE=1 \ + _UNICODE=1 +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES + +# 外部引用 +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +EXTERNAL_PAGES = YES + +# 图表生成 +CLASS_DIAGRAMS = YES +MSCGEN_PATH = +DIA_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +DOT_NUM_THREADS = 0 +DOT_FONTNAME = Helvetica +DOT_FONTSIZE = 10 +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +UML_LIMIT_NUM_FIELDS = 10 +TEMPLATE_RELATIONS = YES +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = YES +CALLER_GRAPH = YES +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +INTERACTIVE_SVG = NO +DOT_PATH = +DOTFILE_DIRS = +MSCFILE_DIRS = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = YES +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..6b541e2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 我在人间做废物 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..1bcad9e --- /dev/null +++ b/README.md @@ -0,0 +1,337 @@ +# 星垣 (StellarX) GUI Framework + +![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) + +> **「繁星为界，轻若尘埃」** —— 一个为Windows平台打造的、极致轻量级、高度模块化的C++原生GUI框架。 + +`星垣 (StellarX)` 诞生于对现代GUI框架"过度臃肿"的反抗。它拒绝动辄数百MB的依赖、漫长的编译时间和复杂的学习曲线，选择回归本质：用最精简的代码、最清晰的架构和最高的效率，解决桌面应用开发的核心需求。 + +它是一个**纯粹的教学级、工具级框架**，旨在让开发者深入理解GUI原理，并快速构建轻量级Windows工具。 + +--- + +## 📦 项目结构与设计哲学 + +星垣框架采用经典的**面向对象**和**模块化**设计，项目结构清晰规范： + +``` +StellarX/ +├── include/ # 头文件目录 +│ └── StellarX/ # 框架头文件 +│ ├── StellarX.h # 主包含头文件 - 一键引入整个框架 +│ ├── CoreTypes.h # ★ 核心 ★ - 所有枚举、结构体的唯一定义源 +│ ├── Control.h # 抽象基类 - 定义所有控件的统一接口 +│ ├── Button.h # 按钮控件 +│ ├── Window.h # 窗口管理 +│ ├── Label.h # 标签控件 +│ ├── TextBox.h # 文本框控件 +│ ├── Canvas.h # 画布容器 +│ └── Table.h # 表格控件 +├── src/ # 源文件目录 +│ ├── Control.cpp +│ ├── Button.cpp +│ ├── Window.cpp +│ ├── Label.cpp +│ ├── TextBox.cpp +│ ├── Canvas.cpp +│ └── Table.cpp +├── examples/ # 示例代码目录 +│ └── demo.cpp # 基础演示 +├── docs/ # 文档目录 +│ └── CODE_OF_CONDUCT.md # 行为准则 +├── CMakeLists.txt # CMake 构建配置 +├── CONTRIBUTING.md # 贡献指南 +├── CHANGELOG.md # 更新日志 +├── Doxyfile # Doxygen 配置 +├── LICENSE # MIT 许可证 +└── README.md # 项目说明 +``` + +**设计理念：** +1. **单一职责原则 (SRP)**: 每个类/文件只负责一件事。 +2. **依赖倒置原则 (DIP)**: 高层模块（如`Window`）不依赖低层模块（如`Button`），二者都依赖其抽象（`Control`）。 +3. **开闭原则 (OCP)**: 通过继承`Control`基类，可以轻松扩展新的控件，而无需修改现有代码。 +4. **一致性**: 所有控件共享统一的`draw()`和`handleEvent()`接口。 + +## 🚀 核心特性 + +- **极致的轻量级**: 核心库编译后仅 ~1.2MB，无任何外部依赖。生成的应用程序小巧玲珑。 +- **清晰的模块化架构**: 使用`CoreTypes.h`统一管理所有类型，消除重复定义，极大提升可维护性。 +- **原生C++性能**: 直接基于EasyX和Win32 API，提供接近原生的执行效率，内存占用极低（通常<10MB）。 +- **丰富的控件库**: 提供按钮、标签、文本框、表格、画布等常用控件，满足基本桌面应用需求。 +- **高度可定制化**: 从控件颜色、形状（矩形、圆角、圆形、椭圆）到填充模式、字体样式，均有详尽枚举支持，可轻松定制。 +- **简洁直观的API**: 采用经典的面向对象设计，代码即文档，学习成本极低。 +- **标准项目结构**: 采用标准的include/src分离结构，支持CMake构建，易于集成和使用。 + +## ⚡ 快速开始（5分钟上手） + +### 环境要求 + +- **操作系统**: Windows 10 或更高版本 +- **编译器**: 支持C++17的编译器 (如: **Visual Studio 2019+**) +- **图形库**: [EasyX](https://easyx.cn/) (2022版本或更高，安装时请选择与您编译器匹配的版本) +- **构建工具**: CMake 3.12+ (可选，推荐使用) + +### 安装 EasyX +1. 访问 [EasyX 官网](https://easyx.cn/) 下载最新版本 +2. 运行安装程序，选择与您的 Visual Studio 版本匹配的版本 +3. 安装完成后，无需额外配置，星垣框架会自动链接 EasyX + +### 方法一：使用CMake构建（推荐） + +1. **克隆项目**: + ```bash + git clone https://github.com/Ysm-04/StellarX + cd StellarX + ``` + +2. **生成构建系统**: + ```bash + mkdir build + cd build + cmake .. + ``` + +3. **编译项目**: + ```bash + cmake --build . + ``` + +4. **运行示例**: + ```bash + ./examples/Demo + ``` + +### 方法二：手动集成到现有项目 + +1. **将include和src目录复制**到您的项目中 +2. **配置包含路径**，确保编译器可以找到`include/StellarX/`目录 +3. **将所有.cpp文件**添加到您的项目中编译 + +### 创建你的第一个星垣应用 + +```cpp +// 只需包含这一个头文件即可使用所有功能 +#include "StellarX/StellarX.h" + +// 程序入口点（请使用WinMain以获得更好的兼容性） +int WINAPI WinMain(_In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, _In_ LPSTR lpCmdLine, _In_ int nShowCmd) { + + // 1. 创建一个640x480的窗口，背景为白色，标题为"我的应用" + StellarX::Window mainWindow(640, 480, 0, RGB(255, 255, 255), "我的第一个星垣应用"); + + // 2. 创建一个按钮 (使用智能指针管理) + auto myButton = std::make_unique( + 250, 200, 140, 40, // x, y, 宽度, 高度 + "点击我", // 按钮文本 + StellarX::ButtonMode::NORMAL, + StellarX::ControlShape::ROUND_RECTANGLE + ); + + // 3. 为按钮设置点击事件（使用Lambda表达式） + myButton->setOnClickListener([]() { + MessageBox(nullptr, L"Hello, 星垣！", L"问候", MB_OK | MB_ICONINFORMATION); + }); + + // 4. (可选)设置按钮样式 + myButton->textStyle.nHeight = 20; + myButton->textStyle.color = RGB(0, 0, 128); // 深蓝色文字 + myButton->setButtonBorder(RGB(0, 128, 255)); // 蓝色边框 + + // 5. 将按钮添加到窗口 + mainWindow.addControl(std::move(myButton)); + + // 6. 绘制窗口 + mainWindow.draw(); + + // 7. 进入消息循环，等待用户交互 + mainWindow.runEventLoop(); + + return 0; +} +``` + +5. **编译并运行！** 您将看到一个带有蓝色圆角按钮的窗口，点击它将会弹出消息框。 + +## 📚 核心类型详解 (`CoreTypes.h`) + +星垣框架的所有视觉和行为属性都通过`CoreTypes.h`中定义的精美枚举和结构体来控制。 + +### 枚举类型 (Enums) + +| 枚举类型 | 描述 | 常用值 | +| :----------------- | :----------- | :----------------------------------------------------------- | +| **`ControlShape`** | 控件几何形状 | `RECTANGLE`, `B_RECTANGLE`, `ROUND_RECTANGLE`, `CIRCLE`, `ELLIPSE`等 | +| **`ButtonMode`** | 按钮行为模式 | `NORMAL`（普通）, `TOGGLE`（切换）, `DISABLED`（禁用） | +| **`TextBoxMode`** | 文本框模式 | `INPUT_MODE`（输入）, `READONLY_MODE`（只读） | +| **`FillMode`** | 图形填充模式 | `SOLID`（实心）, `NULL`（空心）, `HATCHED`（图案）等 | +| **`FillStyle`** | 图案填充样式 | `HORIZONTAL`（水平线）, `CROSS`（十字线）等 | +| **`LineStyle`** | 边框线型 | `SOLID`（实线）, `DASH`（虚线）, `DOT`（点线）等 | + +### 结构体 (Structs) + +| 结构体 | 描述 | +| :---------------- | :----------------------------------------------------------- | +| **`ControlText`** | 封装了所有文本样式属性，包括字体、大小、颜色、粗体、斜体、下划线、删除线等。 | + +**使用示例：** +```cpp +// 创建一个复杂的文本样式 +StellarX::ControlText myStyle; +myStyle.nHeight = 25; // 字体高度 +myStyle.lpszFace = _T("微软雅黑"); // 字体 +myStyle.color = RGB(255, 0, 0); // 红色 +myStyle.nWeight = FW_BOLD; // 粗体 +myStyle.bUnderline = true; // 下划线 + +// 应用于控件 +myLabel->textStyle = myStyle; +myButton->textStyle = myStyle; +``` + +## 🧩 控件库大全 + +### 1. 基础控件 + +| 控件 | 头文件 | 描述 | 关键特性 | +| :---------- | :---------- | :------------ | :------------------------------------------------------ | +| **Button** | `Button.h` | 多功能按钮 | 支持多种模式/形状/状态，可设置悬停/点击颜色，自定义回调 | +| **Label** | `Label.h` | 文本标签 | 支持背景透明/不透明，自定义字体样式 | +| **TextBox** | `TextBox.h` | 输入框/显示框 | 支持输入和只读模式，集成EasyX的`InputBox` | + +### 2. 容器控件 + +| 控件 | 头文件 | 描述 | +| :--------- | :--------- | :------------------------------------------------------- | +| **Canvas** | `Canvas.h` | 容器控件，可作为其他控件的父容器，支持自定义边框和背景。 | +| **Window** | `Window.h` | 顶级窗口，所有控件的最终容器，负责消息循环和调度。 | + +### 3. 高级控件 + +| 控件 | 头文件 | 描述 | 关键特性 | +| :-------- | :-------- | :------- | :----------------------------------------------------------- | +| **Table** | `Table.h` | 数据表格 | **框架功能亮点**，支持分页显示、自定义表头和数据、自动计算列宽、翻页按钮。 | + +**表格控件示例：** +```cpp +// 创建一个表格 +auto myTable = std::make_unique(50, 50); + +// 设置表头 +myTable->setHeaders({ "ID", "姓名", "年龄", "职业" }); + +// 添加数据行 +myTable->addDataRow({ "1", "张三", "25", "工程师" }); +myTable->addDataRow({ "2", "李四", "30", "设计师" }); +myTable->addDataRow({ "3", "王五", "28", "产品经理" }); + +// 设置每页显示2行 +myTable->setRowsPerPage(2); + +// 设置表格样式 +myTable->textStyle.nHeight = 16; +myTable->setTableBorder(RGB(50, 50, 50)); +myTable->setTableBackground(RGB(240, 240, 240)); + +// 添加到窗口 +mainWindow.addControl(std::move(myTable)); +``` + +## 🔧 高级主题与最佳实践 + +### 1. 自定义控件 +您可以通过继承`Control`基类来创建自定义控件。只需实现`draw()`和`handleEvent()`两个纯虚函数即可。 + +```cpp +class MyCustomControl : public StellarX::Control { +public: + MyCustomControl(int x, int y) : Control(x, y, 100, 100) {} + void draw() override { + // 您的自定义绘制逻辑 + setfillcolor(RGB(255, 100, 100)); + fillrectangle(x, y, x + width, y + height); + } + void handleEvent(const ExMessage& msg) override { + // 您的自定义事件处理逻辑 + if (msg.message == WM_LBUTTONDOWN && isInControl(msg.x, msg.y)) { + // 处理点击 + } + } +}; +``` + +### 2. 布局管理 +当前版本星垣主要采用**绝对定位**。对于简单布局，您可以通过计算坐标来实现。对于复杂布局，可以考虑： +- 在`Canvas`中嵌套控件，实现相对定位。 +- 自行实现简单的流式布局或网格布局管理器。 + +### 3. 性能优化 +- **脏矩形渲染**: 框架内部已实现，控件状态改变时`dirty=true`，仅在需要时重绘。 +- **图像资源**: 使用`IMAGE`对象加载图片后，可重复使用，避免多次加载。 +- **减少循环内操作**: 在`draw()`和`handleEvent()`中避免进行重型计算。 + +## ⚠️ 重要限制与适用场景 + +**星垣框架的设计目标是轻便、清晰和教学价值，因此它明确** **不适用于** **以下场景：** + +- **高性能游戏或复杂动画**: 渲染基于EasyX的CPU软件渲染，性能有限。 +- **需要高DPI缩放的应用**: 对高DPI显示器的支持有限，界面可能显示不正确。 +- **需要无障碍功能的应用**: 未提供对屏幕阅读器等辅助技术的支持。 +- **跨平台应用**: 深度依赖Windows API和EasyX，无法直接在Linux/macOS上运行。 +- **复杂的商业软件前端**: 缺乏高级控件（如树形图、富文本框、选项卡、高级列表等）和成熟的自动布局管理器。 + +**如果您需要开发上述类型的应用，请考虑使用以下成熟方案：** +- **Qt**: 功能极其强大，跨平台，适合大型商业应用。 +- **wxWidgets**: 原生外观，跨平台。 +- **Dear ImGui**: 即时模式GUI，非常适合工具和调试界面。 +- **Web技术栈 (Electron/CEF)**: 适合需要Web技术的场景。 + +## 📜 许可证 (License) + +本项目采用 **MIT 许可证**。 + +您可以自由地： +- 使用、复制、修改、合并、出版发行、散布、再授权及销售本框架的副本。 +- 将其用于私人或商业项目。 + +唯一要求是： +- 请在您的项目中保留原始的版权声明。 + +详见项目根目录的 [LICENSE](LICENSE) 文件。 + +## 👥 贡献指南 (Contributing) + +我们欢迎任何形式的贡献！如果您想为星垣框架添砖加瓦，请阅读以下指南： + +1. **代码风格**: 请遵循现有的Google C++规范风格（使用空格缩进，大括号换行等）。 +2. **新增功能**: 必须提供**示例代码**，并更新本README文档的相关部分。 +3. **提交PR**: 请确保您的代码在提交前已经过测试，并描述清楚您的更改内容和动机。 +4. **问题反馈**: 如果您发现了Bug或有新的想法，欢迎在GitHub提交Issue。 + +详细贡献指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 + +## 🙏 致谢 (Acknowledgements) + +- 感谢 [EasyX Graphics Library](https://easyx.cn/) 为这个项目提供了简单易用的图形基础，使得用C++教学GUI编程成为可能。 +- 感谢所有追求**简洁、高效、清晰**编码理念的开发者，你们是"星垣"诞生的灵感源泉。 + +--- + +**星辰大海，代码为舟。** + +愿 `星垣 (StellarX)` 能成为您探索GUI世界的一颗可靠基石，无论是用于学习、教学还是创造实用的工具。 + +## 📞 支持与反馈 + +如果您在使用过程中遇到问题或有任何建议： +1. 查看 [示例代码](examples/) 获取使用参考 +2. 查阅 [更新日志](CHANGELOG.md) 了解最新变化 +3. 在GitHub仓库提交Issue反馈问题 + +--- +*星垣框架 - 轻若尘埃，繁星为界* \ No newline at end of file diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a7c16e4 --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,25 @@ +# 贡献者公约行为准则 + +## 我们的承诺 + +为了营造一个开放和受欢迎的环境，我们作为贡献者和维护者承诺：无论年龄、体型、身体健全与否、民族、性征、性别认同与表达、经验水平、教育程度、社会地位、国籍、个人外貌、种族、宗教信仰、性取向，我们的项目和社区对每一个人都不存在歧视。 + +## 我们的标准 + +有助于为我们社区创造积极环境的行为包括但不限于： + +* 对他人的体贴和尊重 +* 尊重不同的观点和经历 +* 优雅地接受建设性批评 +* 关注对社区最有利的事情 +* 对其他社区成员表现出同理心 + +...... + +## 执行 + +虐待、骚扰或其他不可接受行为的实例可通过项目维护团队进行报告。所有投诉都将被认真、迅速地审查和调查，并将得出被认为在情况下必要和适当的回应。 + +...... + +有关此行为准则的常见问题解答，请参阅 https://www.contributor-covenant.org/faq。翻译版本可在 https://www.contributor-covenant.org/translations 获取。 \ No newline at end of file diff --git a/examples/demo.cpp b/examples/demo.cpp new file mode 100644 index 0000000..4c9013f --- /dev/null +++ b/examples/demo.cpp @@ -0,0 +1,40 @@ +/** + * @file demo.cpp + * @brief 一个简单的演示程序，展示 StellarX GUI 框架的基本用法。 + * @description 创建一个带有按钮的窗口，点击按钮会改变其文本。 + */ + +#include +#include + +int main() +{ + // 创建一个窗口 (Windows平台) + Window mainWindow(800, 600, NULL, RGB(240, 240, 240), "StellarX 演示程序"); + + // 创建一个按钮 + auto myButton = std::make_unique