Skip to content

cpp

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

cpp

README.md

📦 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% 完成！