From d62d8a90d6bec7ffdcdcc0583e6881da83e05255 Mon Sep 17 00:00:00 2001 From: Ysm-04 <3150131407@qq.com> Date: Sun, 7 Sep 2025 00:19:40 +0800 Subject: [PATCH] initial commit --- .gitignore | 77 +++++++ CHANGELOG.md | 28 +++ CMakeLists.txt | 130 +++++++++++ CONTRIBUTING.md | 93 ++++++++ Doxyfile | 219 +++++++++++++++++++ LICENSE | 21 ++ README.md | 337 +++++++++++++++++++++++++++++ docs/CODE_OF_CONDUCT.md | 25 +++ examples/demo.cpp | 40 ++++ include/StellarX/Button.h | 147 +++++++++++++ include/StellarX/Canvas.h | 46 ++++ include/StellarX/Control.h | 80 +++++++ include/StellarX/CoreTypes.h | 243 +++++++++++++++++++++ include/StellarX/StellarX.h | 37 ++++ include/StellarX/label.h | 35 +++ include/StellarX/table.h | 131 ++++++++++++ include/StellarX/textBox.h | 43 ++++ include/StellarX/window.h | 53 +++++ src/Button.cpp | 344 ++++++++++++++++++++++++++++++ src/Canvas.cpp | 95 +++++++++ src/Control.cpp | 64 ++++++ src/label.cpp | 55 +++++ src/table.cpp | 403 +++++++++++++++++++++++++++++++++++ src/textBox.cpp | 135 ++++++++++++ src/window.cpp | 114 ++++++++++ 25 files changed, 2995 insertions(+) create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 CMakeLists.txt create mode 100644 CONTRIBUTING.md create mode 100644 Doxyfile create mode 100644 LICENSE create mode 100644 README.md create mode 100644 docs/CODE_OF_CONDUCT.md create mode 100644 examples/demo.cpp create mode 100644 include/StellarX/Button.h create mode 100644 include/StellarX/Canvas.h create mode 100644 include/StellarX/Control.h create mode 100644 include/StellarX/CoreTypes.h create mode 100644 include/StellarX/StellarX.h create mode 100644 include/StellarX/label.h create mode 100644 include/StellarX/table.h create mode 100644 include/StellarX/textBox.h create mode 100644 include/StellarX/window.h create mode 100644 src/Button.cpp create mode 100644 src/Canvas.cpp create mode 100644 src/Control.cpp create mode 100644 src/label.cpp create mode 100644 src/table.cpp create mode 100644 src/textBox.cpp create mode 100644 src/window.cpp 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