# 项目目录结构

本文介绍 EmbeddedGUI 项目的目录组织方式，帮助你快速定位代码和资源文件。

## 顶层目录总览

```
EmbeddedGUI/
|-- src/                    # 核心库源代码
|-- example/                # 示例应用
|-- porting/                # 平台移植层
|-- scripts/                # 构建工具和辅助脚本
|-- doc/                    # Sphinx 文档源码
|-- web/                    # WebAssembly 在线演示站点静态文件
|-- tools/                  # 内置开发工具 (w64devkit 等)
|-- build_cmake/            # CMake 构建目录（按需生成）
|-- output/                 # 编译产物输出目录（按需生成）
|-- Makefile                # 顶层 Makefile (配置 APP/PORT 等参数)
|-- CMakeLists.txt          # CMake 构建配置
|-- setup.bat               # Windows 环境入口脚本（转发到 setup_env.py）
|-- setup.sh                # Linux / macOS 环境入口脚本
|-- requirements.txt        # Python 依赖列表
|-- VERSION                 # 版本号文件
|-- LICENSE                 # MIT 许可证
`-- README.md               # 项目说明
```

## src/ -- 核心库源代码

这是 EGUI 框架的核心实现，所有模块均以 `egui_` 为前缀命名。

```
src/
|-- egui.h                  # 统一头文件，包含所有模块
|-- build.mk                # 源码构建模块定义
|-- config/                 # 编译期配置系统
|-- core/                   # 核心框架
|-- canvas/                 # 画布绘制引擎
|-- widget/                 # UI 控件
|-- anim/                   # 动画系统
|-- font/                   # 字体渲染
|-- image/                  # 图片处理
|-- mask/                   # 遮罩支持
|-- style/                  # 样式系统
|-- shadow/                 # 阴影效果
|-- background/             # 背景绘制
|-- app/                    # 应用框架 (Activity/Dialog/Toast)
|-- resource/               # 内置资源
|-- utils/                  # 工具函数
`-- test/                   # 测试代码
```

### core/ -- 核心框架

核心模块提供了 EGUI 框架的运行基础:

| 文件 | 说明 |
|------|------|
| `egui_core.c/h` | 框架主循环，驱动渲染和事件处理 |
| `egui_pfb_manager.c/h` | PFB (局部帧缓冲) 管理器 |
| `egui_timer.c/h` | 定时器系统 |
| `egui_input.c/h` | 输入事件处理 |
| `egui_motion_event.c/h` | 触摸/运动事件 |
| `egui_key_event.c/h` | 按键事件 |
| `egui_touch_driver.c/h` | 触摸驱动接口 |
| `egui_display_driver.c/h` | 显示驱动接口 |
| `egui_region.c/h` | 区域计算 (脏矩形) |
| `egui_scroller.c/h` | 滚动物理引擎 |
| `egui_velocity_tracker.c/h` | 速度追踪器 (惯性滑动) |
| `egui_focus.c/h` | 焦点管理 |
| `egui_rotation.c/h` | 屏幕旋转支持 |
| `egui_oop.h` | OOP 辅助宏 (类型转换) |
| `egui_typedef.h` | 基础类型定义 |
| `egui_api.c/h` | 通用 API 函数 |

### canvas/ -- 画布绘制引擎

画布相关实现位于 `src/canvas/`，包含 `egui_canvas.c/h`、`egui_canvas_line.c`、`egui_canvas_line_hq.c`、`egui_canvas_circle_hq.c`、`egui_canvas_gradient.c/h`、`egui_canvas_bezier.c`、`egui_canvas_polygon.c`、`egui_canvas_triangle.c`、`egui_canvas_ellipse.c` 和 `egui_canvas_transform.c` 等文件，用于基础图元、抗锯齿、渐变与变换渲染。

### config/ -- 配置系统

配置模块提供编译期默认配置与功能分组默认值：

| 文件 | 说明 |
|------|------|
| `egui_config.h` | 配置入口，汇总各类默认配置头 |
| `egui_config_default.h` | 主屏基础默认配置 |
| `egui_config_multi_default.h` | 多屏默认配置 |
| `egui_config_canvas_default.h` | Canvas 默认配置 |
| `egui_config_fast_path_default.h` | 快路径默认配置 |
| `egui_config_widget_default.h` | 控件默认配置 |
| `egui_config_theme_default.h` | 主题默认配置 |
| `egui_config_debug_default.h` | 调试默认配置 |

### widget/ -- UI 控件

包含 60+ UI 控件的实现，每个控件由一对 `.c/.h` 文件组成。主要控件分类:

**基础控件**: label (标签), button (按钮), image (图片), image_button (图片按钮)

**输入控件**: switch (开关), checkbox (复选框), radio_button (单选按钮), slider (滑块), arc_slider (弧形滑块), toggle_button (切换按钮), combobox (下拉框), roller (滚轮选择), number_picker (数字选择器), spinner (旋转选择), textblock (文本块)

**布局控件**: linearlayout (线性布局), gridlayout (网格布局), scroll (滚动视图), viewpage (分页视图), tileview (瓦片视图), list (列表)

**进度控件**: progress_bar (进度条), circular_progress_bar (圆形进度条), activity_ring (活动环)

**图表控件**: chart_line (折线图), chart_bar (柱状图), chart_pie (饼图), chart_scatter (散点图)

**时钟控件**: analog_clock (模拟时钟), digital_clock (数字时钟), stopwatch (秒表), mini_calendar (迷你日历)

**其他控件**: card (卡片), divider (分割线), page_indicator (页面指示器), notification_badge (通知徽章), led (LED 指示灯), gauge (仪表盘), compass (罗盘), heart_rate (心率), scale (刻度), button_matrix (按钮矩阵), table (表格), animated_image (动画图片), spangroup (富文本), window (窗口), menu (菜单), line (线条), keyboard (键盘), mp4 (视频)

### anim/ -- 动画系统

提供类 Android 的动画框架:

| 文件 | 说明 |
|------|------|
| `egui_animation.c/h` | 动画基类 |
| `egui_animation_translate.c/h` | 平移动画 |
| `egui_animation_alpha.c/h` | 透明度动画 |
| `egui_animation_scale_size.c/h` | 缩放动画 |
| `egui_animation_resize.c/h` | 尺寸变化动画 |
| `egui_animation_color.c/h` | 颜色渐变动画 |
| `egui_animation_set.c/h` | 动画组合 (顺序/并行) |
| `egui_interpolator.c/h` | 插值器基类 |

支持 9 种插值器: linear (线性), accelerate (加速), decelerate (减速), accelerate_decelerate (先加速后减速), anticipate (回弹启动), overshoot (过冲), anticipate_overshoot (回弹过冲), bounce (弹跳), cycle (循环)。

### font/ -- 字体渲染

支持点阵字体和标准字体渲染，提供 UTF-8 编码支持。

### image/ -- 图片处理

图片解码和渲染，支持带 Alpha 通道的图片。

### mask/ -- 遮罩支持

提供圆形遮罩、圆角矩形遮罩、渐变遮罩和图片遮罩，用于实现圆角图片、异形裁剪等效果。

### style/ -- 样式系统

样式与主题相关实现位于 `src/style/`，包含 `egui_style.c/h`、`egui_style_transition.c/h`、`egui_theme.c/h`、`egui_theme_dark.c` 和 `egui_theme_light.c`。

### utils/ -- 工具函数

| 文件 | 说明 |
|------|------|
| `egui_fixmath.c/h` | 定点数运算 (三角函数、平方根等) |
| `egui_dlist.h` | 双向链表 |
| `egui_slist.h` | 单向链表 |
| `egui_utils.c/h` | 通用工具函数 |
| `simple_ringbuffer/` | 环形缓冲区实现 |

## example/ -- 示例应用

每个示例位于独立子目录中，通常包含 `uicode_disp0.c` (UI 代码)、`uicode_disp0.h`、`build.mk` (构建配置) 和可选的 `resource/` (资源文件) 目录。

| 示例 | 说明 |
|------|------|
| `HelloSimple` | 最简单的入门示例 (标签 + 按钮) |
| `HelloBasic` | 基础控件演示集合，当前包含 62 个子应用 |
| `HelloVirtual` | Virtual / ListView / GridView / Stage 示例集合，当前包含 19 个子应用 |
| `HelloCustomWidgets` | 已迁移到独立仓库 `EmbeddedGUI_Widgets` |
| `HelloActivity` | Activity 生命周期和页面管理 |
| `HelloAPP` | 基于 `egui_page_base_t` 的多页面应用示例 |
| `HelloCanvas` | 画布绘图 API 演示 |
| `HelloChart` | 图表控件演示 |
| `HelloDirty` | 脏区刷新局部重绘演示 |
| `HelloEasyPage` | 简易分页应用 |
| `HelloGradient` | 渐变效果演示 |
| `HelloLayer` | Layer 机制演示 |
| `HelloMultiDisplay` | 主屏和副屏同为 240x320，演示多屏 Activity 切换与副屏独立输入 |
| `HelloMultiDisplayHetero` | 主屏 240x320，副屏 128x64，演示异构副屏状态面板和跨屏状态联动 |
| `HelloPFB` | PFB 机制演示 |
| `HelloPerformance` | 性能测试基准 |
| `HelloResourceManager` | 资源管理器示例 |
| `HelloShowcase` | 综合展示示例 |
| `HelloSizeAnalysis` | 体积分析 probe / 配置模板集合 |
| `HelloStyleDemo` | 样式和主题演示 |
| `HelloSVGSpec` | SVG 规范对比基座 |
| `HelloTest` | 功能测试 |
| `HelloUnitTest` | 单元测试 |
| `HelloViewPageAndScroll` | 分页和滚动组合 |

其中 `HelloBasic`、`HelloVirtual` 和 `HelloSizeAnalysis` 都通过 `APP_SUB` 选择不同子目录；`HelloCustomWidgets` 已迁移到独立仓库 `EmbeddedGUI_Widgets`。

## porting/ -- 平台移植层

每个平台对应一个子目录，实现平台相关的显示驱动、触摸驱动和定时器:

| 平台 | 说明 |
|------|------|
| `pc/` | PC 模拟器 (基于 SDL2，支持 Windows/Linux/macOS) |
| `stm32g0/` | STM32G0 系列 MCU (ARM Cortex-M0+) |
| `qemu/` | QEMU ARM 虚拟化环境 (自动化测试和性能基准) |
| `emscripten/` | WebAssembly 编译 (浏览器在线演示) |
| `designer/` | UI Designer 专用移植 |
| `pc_test/` | PC 测试专用移植 |

## scripts/ -- 构建工具和辅助脚本

| 脚本 | 说明 |
|------|------|
| `code_compile_check.py` | 完整编译检查 (CI 使用，含示例 icon font 检查) |
| `code_runtime_check.py` | 运行时验证 (截图对比) |
| `code_format.py` | 代码格式化 |
| `release_check.py` | 发布前多步骤一键检查，也支持 `--scope multi-display` 本地快速回归 |
| `setup_env.py` | 跨平台环境配置主脚本，负责 Python 依赖、工具链检查和 FFmpeg 准备 |
| `checks/` | 专项检查脚本（icon font、dirty animation、parity、render workflow、touch 语义） |
| `platform/` | 平台/工程维护脚本（如 `keil_project_sync.py`） |
| `web/` | Emscripten/WASM 构建脚本（如 `wasm_build_demos.py`、`emcc_wrapper.py`） |
| `recording/` | 录制与 GIF 导出辅助脚本 |
| `perf_analysis/main.py` | 性能测试统一入口 |
| `size_analysis/main.py` | ELF 二进制大小分析统一入口 |
| `tools/` | 本地工具与资源生成工具（如 w64devkit、ffmpeg） |

## doc/ -- 文档

基于 Sphinx 构建的项目文档:

```
doc/source/
|-- index.rst               # 文档首页
|-- getting_started/        # 快速入门 (本系列文档)
|-- architecture/           # 架构说明
|-- widgets/                # 控件参考
|-- animation/              # 动画系统
|-- app/                    # Activity / Dialog / Toast / 页面框架
|-- debug/                  # 调试与渲染验证
|-- performance/            # 性能优化与基准
|-- porting/                # 移植指南
|-- resource/               # 资源管理
|-- size/                   # 体积分析与配置模板
|-- appendix/               # FAQ / Changelog / API 索引
|-- ui_designer/            # UI Designer 入口页（演示 GIF + 跳转）
|-- images/                 # 文档配图
`-- conf.py                 # Sphinx 配置
```

## web/ -- WebAssembly 在线演示

通过 Emscripten 将 EGUI 示例编译为 WebAssembly，可在浏览器中直接体验:

```
web/
|-- index.html              # 演示首页（HelloShowcase）
|-- basic.html              # HelloBasic 聚合页
|-- examples.html           # 独立示例聚合页
|-- widgets repo            # HelloCustomWidgets 已迁移到独立仓库 `EmbeddedGUI_Widgets`
|-- doc-render.js           # README 渲染逻辑
|-- i18n.js                 # 中英文本切换
|-- lib/                    # JavaScript 依赖库
|-- style.css               # 页面样式
`-- demos/                  # 运行 `scripts/web/wasm_build_demos.py` 后生成的 demo 包和 `demos.json`
```

## 下一步

- [构建系统详解](build_system.md): 深入了解 Makefile 和 build.mk 的工作原理
- [第一个应用](first_app.md): 从代码层面理解 EGUI 应用结构