# novaGUI

**Repository Path**: zhang-hang3252/novaGUI

## Basic Information

- **Project Name**: novaGUI
- **Description**: novaRTOS的图形化界面模块，支持单色，16位色和32位色。
- **Primary Language**: C
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-03
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenGUI 嵌入式图形界面库

## 项目介绍
OpenGUI 是一个轻量级嵌入式图形界面库，专为资源受限的嵌入式系统设计。具备完整的事件驱动、命中分发和组件系统。

## 架构分层

```
┌─────────────────────────────┐
│   demo / 应用程序            │  不依赖任何平台
├─────────────────────────────┤
│   component (组件层)         │  window, label, button, checkbox
├─────────────────────────────┤
│   draw (绘制层)              │  形状绘制, 字体绘制, 抗锯齿
├─────────────────────────────┤
│   core (核心层)              │  事件系统, 颜色, 手势识别, 配置
├─────────────────────────────┤
│   porting (移植抽象层)       │  display_porting, input_porting
├─────────────────────────────┤
│   hal (硬件抽象层)           │  hal_windows.c / hal_linux.c / ...
└─────────────────────────────┘
```

- **hal/** — 平台后端实现（Windows GDI、Linux framebuffer 等），通过回调注入
- **porting/** — 纯转发层，零平台代码，委托到 HAL
- **core/** — 事件系统、颜色混合、手势状态机
- **draw/** — 形状/字体绘制，含圆角抗锯齿
- **component/** — 窗口、标签、按钮、复选框等控件

## 移植顺序（从最少到完整）

### 第 1 步：移植 HAL 层（必须）
创建 `hal/hal_xxx.c`，实现 `hal_ops_t` 中的全部回调：
```c
typedef struct {
    hal_display_init_fn   display_init;     // 初始化显示
    hal_display_deinit_fn display_deinit;   // 关闭显示
    hal_display_flush_fn  display_flush;    // 帧刷新
    hal_display_draw_fn   display_draw;     // 像素块写入

    hal_input_init_fn     input_init;       // 初始化输入
    hal_input_deinit_fn   input_deinit;     // 关闭输入
    hal_input_get_pos_fn  input_get_pos;    // 获取坐标+按键
    hal_get_ticks_fn      get_ticks;        // 毫秒时间戳

    hal_process_events_fn process_events;   // 消息循环(返回0退出)
} hal_ops_t;
```

然后在 `hal/hal.c` 的 `hal_init()` 中添加平台分支调用注册函数。

### 第 2 步：移植 porting 层（无需修改）
`porting/display_porting.c` 和 `porting/input_porting.c` 已是纯转发实现，不需要移植。

### 第 3 步：移植 core + draw 层（无需修改）
`core/` 和 `draw/` 为平台无关代码。

### 第 4 步：移植组件层（按需选择）

| 优先级 | 文件 | 说明 |
|--------|------|------|
| ★★★ 必须 | `window.c/h` | 窗口容器，管理组件树和事件分发 |
| ★★☆ 推荐 | `label.c/h` | 文本标签显示 |
| ★★☆ 推荐 | `button.c/h` | 按钮，支持圆角、按下反馈 |
| ★☆☆ 可选 | `checkbox.c/h` | 复选框，点击切换选中态 |

若不需要某个组件，从 `core/opengui.h` 中移除对应 `#include` 和 `GUI_TYPE_*` 枚举值，并从 CMakeLists 中移除对应 `.c` 文件。

## 组件 API 速查

### Window（窗口）
```c
gui_window_t* win = window_create(WINDOW_WIDTH, WINDOW_HEIGHT, DEFAULT_WINDOW_COLOR);
window_add_component(win, comp);
window_set_callback(win, callback, user);
```

### Label（标签）
```c
gui_label_t* label = label_create(x, y, w, h, "text");
label_set_text(label, "new text");
label_set_lucency(label, 0);  // 0=不透明, 1=透明
```

### Button（按钮）
```c
gui_button_t* btn = button_create(x, y, w, h, "Click");
button_set_corner_radius(btn, 8);
button_set_callback(btn, callback, user_data);
```

### Checkbox（复选框）
```c
gui_checkbox_t* cb = checkbox_create(x, y, w, h, "Label", 1);
checkbox_set_callback(cb, callback, user);
checkbox_is_checked(cb);
```

### 事件回调类型
```c
// window
void cb(gui_window_t* win, void* user, gui_event_type_t type);
// button
void cb(gui_button_t* btn, void* user, gui_event_type_t type);
// checkbox
void cb(gui_checkbox_t* cb, void* user, uint8_t checked);
```

### 事件类型
`GUI_EVENT_PRESS` | `GUI_EVENT_RELEASE` | `GUI_EVENT_CLICK` | `GUI_EVENT_LONG_PRESS` | `GUI_EVENT_DRAG` | `GUI_EVENT_SWIPE_LEFT/RIGHT/UP/DOWN`

### 绘图函数
`draw_line` | `draw_rect` | `fill_rect` | `draw_circle` | `fill_circle` | `fill_round_rect` | `draw_string`

### 颜色工具
`color_blend(bg, fg, alpha)` — 透明度混合<br>
`draw_set_bg(color)` — 设置抗锯齿背景色

## 构建
```bash
mkdir build && cd build
cmake .. -G "MinGW Makefiles"
cmake --build .
./opengui.exe
```
需要链接 `gdi32` 和 `user32`（Windows），其他平台替换为对应的 HAL 实现。
    
    // 清理资源
    screen_destroy(screen);
    
    return 0;
}
```

## 配置选项

可以通过修改 `core/opengui.h` 文件顶部的宏定义来配置 GUI 库的行为：
- 调整字体大小
- 调整触摸事件阈值
- 启用/禁用某些功能

## 性能优化

### 绘图优化
- 减少不必要的重绘
- 合并多个绘图操作
- 使用适当的图形绘制函数

### 内存优化
- 合理使用组件
- 避免内存泄漏
- 优化缓冲区使用

## 已知限制

- 只支持 ASCII 字符
- 图形绘制功能相对简单
- 组件类型有限
- 不支持复杂的布局系统

## 未来计划

- 支持更多组件类型
- 增加更丰富的绘图功能
- 实现简单的布局系统
- 支持更多字体和字符集

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

## 许可证