📦 CPP Examples - C++ 组件示例

目录说明：本目录包含用 C++ 编写的最小化组件示例
最后更新：2025-10-11

🎯 设计目标

最小化：每个组件只展示一个核心功能
模块化：组件之间互不依赖，可独立运行
教学性：代码清晰，注释详细，适合学习
可复用：组件可作为更复杂应用的构建块

📚 组件列表

🎨 基础图形组件

1. Triangle（三角形）- 优先级 ⭐⭐⭐

状态：✅ 已完成
路径：examples/cpp/triangle/
功能：

渲染一个彩色旋转三角形
演示顶点缓冲和动态变换
展示顶点颜色插值
支持键盘交互（空格暂停/继续，R重置）
提供基础着色器供其他组件共享使用

学习要点：

Vulkan 图形管线配置
顶点缓冲创建和更新
旋转变换矩阵
输入事件处理
GLSL 着色器编写和编译

2. Rectangle（矩形）- 优先级 ⭐⭐⭐

状态：✅ 已完成
路径：examples/cpp/rectangle/
功能：

多矩形渲染（5个不同矩形）
脉冲动画（缩放+颜色变化）
圆周运动（4个角矩形旋转）
网格背景绘制
动画暂停/重置控制

学习要点：

矩形 API 使用
正弦波动画
圆周运动数学
多对象管理
时间驱动动画

3. Text（文本）- 优先级 ⭐⭐⭐

状态：✅ 已完成
路径：examples/cpp/text/
功能：

多种字体大小（8px-28px）
8 种颜色预设
动画效果（脉冲、彩虹、滚动）
多行文本渲染
简单位图字体渲染

说明：

✅ 使用简单位图字体系统
✅ 支持基本字符（数字、字母、符号）

学习要点：

文本渲染 API
颜色管理
简单动画效果
布局技巧

4. Circle（圆形）- 优先级 ⭐

状态：✅ 已完成
路径：examples/cpp/circle/
功能：

多种尺寸圆形（半径 5~25）
丰富颜色预设
动画效果（脉冲、透明度、彩虹）
圆周运动（轨道动画）
同心圆结构
波纹扩散效果
图案设计（花瓣）

学习要点：

圆形 API 使用
三角函数应用
极坐标变换
颜色和透明度控制

5. Line（线段）- 优先级 ⭐

状态：✅ 已完成
路径：examples/cpp/line/
功能：

多种宽度线段（1~8 像素）
任意角度绘制（放射线段）
丰富颜色和动态彩虹色
旋转动画和时钟效果
网格绘制
波形曲线（正弦波）
星形图案

学习要点：

线段 API 使用
极坐标到直角坐标转换
参数方程（波形）
几何图案设计

📊 进度显示组件

6. ProgressBar（进度条）- 优先级 ⭐⭐⭐

状态：✅ 已完成
路径：examples/cpp/progressbar/
功能：

可视化进度显示
平滑动画过渡
多种控制模式（手动/自动循环/自动一次）
实时进度百分比显示
支持键盘交互（M切换模式，R重置，箭头控制）

学习要点：

矩形分层渲染
线性插值动画
值的映射（0-1 到百分比）
状态机模式切换

🖱️ 交互组件

7. Switch（开关）- 优先级 ⭐⭐⭐

状态：✅ 已完成
路径：examples/cpp/switch/
功能：

可点击的开关组件
开/关状态切换
平滑动画过渡
鼠标悬停提示
支持键盘交互（空格切换，ESC退出）

学习要点：

鼠标输入处理
状态管理和动画
圆角矩形绘制（圆形+矩形组合）
颜色插值

8. Button（按钮）- 优先级 ⭐⭐⭐

状态：✅ 已完成
路径：examples/cpp/button/
功能：

可点击的按钮组件
三种状态：普通、悬停、按下
平滑颜色过渡动画
点击计数和窗口标题更新
状态指示器（小圆点和进度条）

学习要点：

鼠标输入处理
状态机管理（NORMAL/HOVER/PRESSED）
颜色插值动画
事件回调（onClick）
窗口标题动态更新

9. Checkbox（复选框）- 优先级 ⭐⭐⭐

状态：✅ 已完成
路径：examples/cpp/checkbox/
功能：

双状态管理（选中/未选中）
鼠标点击切换状态
勾选标记（✓）绘制
悬停高亮效果
多复选框支持
键盘控制（空格切换）

学习要点：

双状态逻辑
旋转矩形绘制技术
点击检测算法
多对象状态管理

10. Radio（单选框）- 优先级 ⭐⭐⭐

状态：✅ 已完成
路径：examples/cpp/radio/
功能：

互斥选择（同组只能选一个）
圆形外观设计
分组管理（支持多个独立组）
鼠标点击切换选择
悬停高亮效果
键盘快捷选择
实时预览功能

学习要点：

互斥选择逻辑
圆形碰撞检测
指针共享状态
分组数据管理

11. Slider（滑动条）- 优先级 ⭐⭐

状态：✅ 已完成
路径：examples/cpp/slider/
功能：

鼠标拖动滑块
点击滑轨跳转
数值映射（归一化）
范围控制（自定义最小值/最大值）
多滑块支持
实时数值显示
实时预览

学习要点：

鼠标拖动状态管理
归一化值映射
复合碰撞检测
数据驱动设计

12. Input（输入框）- 优先级 ⭐⭐⭐

状态：✅ 已完成
路径：examples/cpp/input/
功能：

文本输入（字母、数字、符号）
光标闪烁显示
焦点管理（点击聚焦/失焦）
退格删除
占位符提示
多输入框支持
Tab 键切换焦点
字符长度限制

学习要点：

C 字符串操作
键盘输入处理
焦点状态管理
光标动画

13. Label（标签）- 优先级 ⭐⭐⭐

状态：✅ 已完成
路径：examples/cpp/label/
功能：

静态文本显示
三种对齐方式（左/中/右）
多种字体大小（8px - 28px+）
自定义颜色和背景
多标签同时显示
简单布局定位

学习要点：

文本渲染 API
对齐算法实现
颜色和背景管理
文本宽度估算

14. Tooltip（提示框）- 优先级 ⭐⭐

状态：✅ 已完成
路径：examples/cpp/tooltip/
功能：

鼠标悬停检测
延迟显示（0.5秒）
淡入淡出动画
智能定位（跟随鼠标/固定位置）
边界检测
圆角背景
进度指示

学习要点：

鼠标交互和坐标转换
状态机管理
动画插值算法
透明度合成

15. Dropdown（下拉菜单）- 优先级 ⭐⭐⭐

状态：✅ 已完成 🎉
路径：examples/cpp/dropdown/
功能：

点击展开/收起
选项列表显示
鼠标悬停高亮
点击选择
键盘导航（上下箭头、回车）
选中指示标记
互斥展开
点击外部自动关闭

学习要点：

展开/收起动画
列表渲染和裁剪
复杂事件处理
键盘和鼠标集成

🛠️ 开发指南

组件模板

// my_component.cpp
#include "runtime_api.h"

class MyComponent : public BitHCI::IComponent {
private:
    BitHCI::IRenderer* renderer = nullptr;
    BitHCI::IInput* input = nullptr;
    BitHCI::IWindow* window = nullptr;
    
public:
    void onInit(BitHCI::IWindow* window, 
                BitHCI::IRenderer* renderer, 
                BitHCI::IInput* input,
                BitHCI::IResourceManager* resources) override {
        this->window = window;
        this->renderer = renderer;
        this->input = input;
        
        // 初始化代码
    }
    
    void onUpdate(float deltaTime) override {
        // 更新逻辑
    }
    
    void onRender() override {
        // 渲染代码
    }
    
    void onDestroy() override {
        // 清理资源
    }
};

// 导出组件
BITHCI_COMPONENT(MyComponent)

CMakeLists.txt 模板

cmake_minimum_required(VERSION 3.24)
project(my_component)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 包含 Native API
include_directories(${CMAKE_SOURCE_DIR}/../../../native/include)

# 创建组件库
add_library(my_component SHARED
    my_component.cpp
)

# 链接 Native 运行时（如需要）
# target_link_libraries(my_component PRIVATE bitui_native_api)

目录结构

component_name/
├── README.md               # 组件文档
├── component_name.cpp      # 实现文件
├── component_name.h        # 头文件（可选）
├── CMakeLists.txt          # 构建配置
├── assets/                 # 组件资源（必需）
│   └── shaders/           # 着色器定义（必需）
│       ├── triangle.vert  # 顶点着色器
│       ├── triangle.frag  # 片段着色器
│       ├── compile_shaders.bat  # 编译脚本
│       ├── README.md      # 着色器说明（推荐）
│       └── spv/           # 编译产物
│           ├── triangle_vert.spv
│           └── triangle_frag.spv
├── build/                  # 构建目录（自动生成）
└── screenshot.png          # 效果截图（可选）

关于 assets/ 目录：

📁 当前阶段（基础开发）：每个组件都需要显式定义着色器
🎓 目的：学习和理解 Vulkan 渲染管线的完整流程
🔧 包含内容：
- shaders/*.vert - 顶点着色器源码
- shaders/*.frag - 片段着色器源码
- shaders/compile_shaders.bat - SPIR-V 编译脚本
- shaders/spv/*.spv - 编译后的着色器
💡 未来优化：成熟后可抽取通用着色器到 Native 运行时

🚀 快速开始

1. 创建新组件

# 进入 cpp 目录
cd examples/cpp

# 创建组件目录
mkdir triangle
cd triangle

# 创建文件
touch triangle.cpp
touch CMakeLists.txt
touch README.md

2. 编写代码

参考上面的模板，实现组件功能。

3. 编译着色器

# 进入着色器目录
cd assets/shaders

# 编译 GLSL 到 SPIR-V
compile_shaders.bat

# 验证生成的 .spv 文件
ls spv/

说明：compile_shaders.bat 使用 glslc（Vulkan SDK 自带）编译着色器

4. 构建组件

# 返回组件根目录
cd ../..

# 创建构建目录
mkdir build
cd build

# 配置 CMake
cmake ..

# 构建
cmake --build .

5. 运行组件

# 使用 Native 容器运行
cd ../../../native

# 运行 Triangle 组件
.\build\Release\bitui_native.exe .\build\Release\triangle.dll

# 或运行 Switch 组件
.\build\Release\bitui_native.exe .\build\Release\switch.dll

注意：需要先将编译好的 DLL 复制到 native/build/Release/ 目录下。

📝 开发规范

代码风格

使用 C++20 标准特性
遵循 RAII 原则
使用智能指针管理资源
添加清晰的注释

命名规范

类名：PascalCase（TriangleComponent）
函数名：camelCase（onUpdate）
变量名：camelCase（deltaTime）
常量名：UPPER_CASE（MAX_VERTICES）

文档规范

每个组件必须包含：

README.md：组件说明
- 功能描述：组件做什么
- 使用方法：如何构建和运行
- 学习要点：技术重点
- 效果截图：运行效果
assets/shaders/README.md（推荐）：着色器说明
- 着色器功能
- 顶点格式
- 编译方法

着色器规范

基础开发阶段，每个组件都需要：

✅ 顶点着色器（.vert）- 处理顶点变换
✅ 片段着色器（.frag）- 处理像素着色
✅ 编译脚本（compile_shaders.bat）- 自动化编译
✅ SPIR-V 产物（spv/*.spv）- 编译后的着色器

通用着色器模板（如 triangle.vert/frag）可在组件间复用

🎓 学习路径

新手路径（推荐）

1. Triangle    → 学习基础渲染和动画 ✅
2. Rectangle   → 学习矩形 API 和动画数学 ✅
3. ProgressBar → 学习状态机和模式切换 ✅
4. Switch      → 学习鼠标交互和状态管理 ✅
5. Button      → 学习事件回调和 UI 反馈 ✅
6. Text        → 学习纹理映射（规划中）

进阶路径

1. Triangle    → 基础图形 ✅
2. Rectangle   → 矩形动画 ✅
3. ProgressBar → 进度显示 ✅
4. Switch      → 开关交互 ✅
5. Button      → 按钮组件 ✅
6. Slider      → 拖动交互（规划中）
7. 自定义组件  → 综合应用

当前可用组件

组件	状态	难度	功能亮点
Triangle	✅	⭐	旋转动画、颜色插值、键盘控制
Rectangle	✅	⭐	脉冲动画、圆周运动、网格背景
Circle	✅	⭐	多尺寸、动画、轨道运动、波纹
Text	✅	⭐	多字体、颜色、动画、简单位图字体
Line	✅	⭐	多宽度、放射线段、时钟、波形
ProgressBar	✅	⭐⭐	多种模式、进度动画、状态机
Switch	✅	⭐⭐	鼠标交互、平滑动画、状态管理
Button	✅	⭐⭐	状态检测、颜色过渡、事件回调
Checkbox	✅	⭐⭐	双状态管理、勾选标记、多对象
Radio	✅	⭐⭐	互斥选择、圆形绘制、分组管理
Slider	✅	⭐⭐	拖动交互、数值映射、范围控制
Input	✅	⭐⭐⭐	文本输入、光标管理、焦点控制
Label	✅	⭐	文本对齐、字体大小、颜色背景
Tooltip	✅	⭐⭐	悬停提示、淡入淡出、智能定位
Dropdown	✅	⭐⭐⭐	展开收起、选项列表、键盘导航

🔗 相关资源

📊 开发统计

指标	数值
已完成组件	🎉 15 / 15 (100%) 🎉
总代码行数	~3921 行
平均组件大小	~261 行
测试覆盖	100% (15/15)

🎉 100% 完成里程碑

恭喜！所有 15 个组件已全部完成！

从简单到复杂，从基础图形到完整交互，我们构建了一个功能齐全的 UI 组件库：

✅ 5 个基础图形组件
✅ 1 个进度显示组件
✅ 9 个交互组件

这是一个完整的学习之旅，涵盖了：

图形渲染基础
动画和插值
鼠标和键盘交互
状态管理
事件处理
UI/UX 设计模式

下一步：

🚀 开始构建真实应用
📚 深入学习高级特性
🎨 自定义组件样式
🔧 优化性能
📦 打包和分发

维护者：Bit Project 团队
最后更新：2025-10-12
状态：🎉 100% 完成！

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

📦 CPP Examples - C++ 组件示例

🎯 设计目标

📚 组件列表

🎨 基础图形组件

1. Triangle（三角形）- 优先级 ⭐⭐⭐

2. Rectangle（矩形）- 优先级 ⭐⭐⭐

3. Text（文本）- 优先级 ⭐⭐⭐

4. Circle（圆形）- 优先级 ⭐

5. Line（线段）- 优先级 ⭐

📊 进度显示组件

6. ProgressBar（进度条）- 优先级 ⭐⭐⭐

🖱️ 交互组件

7. Switch（开关）- 优先级 ⭐⭐⭐

8. Button（按钮）- 优先级 ⭐⭐⭐

9. Checkbox（复选框）- 优先级 ⭐⭐⭐

10. Radio（单选框）- 优先级 ⭐⭐⭐

11. Slider（滑动条）- 优先级 ⭐⭐

12. Input（输入框）- 优先级 ⭐⭐⭐

13. Label（标签）- 优先级 ⭐⭐⭐

14. Tooltip（提示框）- 优先级 ⭐⭐

15. Dropdown（下拉菜单）- 优先级 ⭐⭐⭐

🛠️ 开发指南

组件模板

CMakeLists.txt 模板

目录结构

🚀 快速开始

1. 创建新组件

2. 编写代码

3. 编译着色器

4. 构建组件

5. 运行组件

📝 开发规范

代码风格

命名规范

文档规范

着色器规范

🎓 学习路径

新手路径（推荐）

进阶路径

当前可用组件

🔗 相关资源

📊 开发统计

🎉 100% 完成里程碑