圆角矩形 (Geometry Rounded Rectangle)
概述
圆角矩形控件是一个轻量级的 GUI 绘图组件，专门用于在用户界面中绘制带圆角的矩形图形。该控件提供了简洁易用的 API ，支持自定义圆角矩形的尺寸、圆角半径、颜色等属性，能够创建现代风格的 UI 元素。
核心功能
描述 |
API |
|---|---|
创建控件 |
|
设置属性 |
|
设置位置 |
|
设置尺寸 |
|
设置颜色 |
|
设置不透明度 |
|
注册点击事件回调 |
|
旋转变换 |
|
缩放变换 |
|
平移变换 |
|
设置线性渐变 |
|
添加渐变色点 |
|
清除渐变色 |
圆角说明
圆角矩形支持四个角具有相同的圆角半径：
radius = 0: 绘制直角矩形
radius > 0: 绘制圆角矩形，半径值决定圆角弧度
渐变色填充
圆角矩形控件支持线性渐变色填充，可以沿着不同方向实现平滑的颜色过渡效果。
渐变方向
支持 4 种线性渐变方向：
RECT_GRADIENT_HORIZONTAL: 水平渐变（从左到右）
RECT_GRADIENT_VERTICAL: 垂直渐变（从上到下）
RECT_GRADIENT_DIAGONAL_TL_BR: 对角线渐变（从左上到右下）
RECT_GRADIENT_DIAGONAL_TR_BL: 对角线渐变（从右上到左下）
渐变色工作原理
渐变色沿指定方向线性插值
支持最多 8 个颜色停止点（color stops）
颜色停止点的位置用 0.0 ~ 1.0 的归一化值表示
像素颜色通过在相邻颜色停止点之间进行线性插值计算得出
采用有序抖动（Ordered Dithering）算法消除 RGB565 格式的色阶问题
使用步骤
创建圆角矩形控件
调用
gui_rect_set_linear_gradient()设置渐变方向调用
gui_rect_add_gradient_stop()添加颜色停止点（至少需要 2 个）可选：调用
gui_rect_clear_gradient()清除渐变设置
关键要点
颜色插值: 支持 RGBA 颜色空间的线性插值，包括透明度通道
抗色阶: 针对 RGB565 显示屏优化，使用抖动算法消除色阶
性能优化: 对非渐变场景几乎无性能影响
特性亮点
高性能: 采用优化的绘制算法，确保流畅的渲染性能
抗锯齿: 支持边缘抗锯齿，提供平滑的圆角效果
灵活配置: 支持自定义尺寸、圆角半径和颜色
透明度支持: 支持 RGBA 颜色格式，可创建半透明效果
轻量级: 内存占用小，适合嵌入式系统和资源受限环境
动态更新: 支持运行时动态修改位置和样式
矩阵变换: 支持旋转、缩放、平移等矩阵变换操作，实现复杂的几何变换效果
应用场景
圆角矩形控件适用于以下场景：
现代化按钮: 创建具有圆角效果的交互按钮
卡片式布局: 实现卡片式 UI 设计元素
对话框和面板: 绘制圆角对话框、信息面板
图标背景: 作为应用图标或功能图标的背景
进度条容器: 创建圆角进度条的背景容器
列表项: 实现圆角列表项或菜单项
动画元素: 支持位置动态变化的动画效果
变换动画: 利用旋转、缩放、平移实现复杂的动画效果
配置说明
要使用圆角矩形控件，需要在配置文件中启用相应的宏定义：
通过 menuconfig 启用 Kconfig 选项：
cd win32_sim
menuconfig ../Kconfig.gui
选择 Geometry RECT Demo （ CONFIG_REALTEK_BUILD_REAL_LITE_RECT ），保存到 win32_sim/.config。
#define CONFIG_REALTEK_BUILD_REAL_LITE_RECT 1
完整示例
#include "gui_components_init.h"
#include "gui_rect.h"
#include "gui_view.h"
#include "gui_view_instance.h"
#define RECT_VIEW_NAME "rect_round_view"
gui_rounded_rect_t *round_rect = NULL;
void round_rect_timer_cb(void *arg)
{
gui_rect_set_position(arg, 100, 100);
gui_fb_change();
}
void rect_click_demo(void)
{
round_rect = gui_rect_create(gui_obj_get_root(), "round_rect", 0, 0, 200, 200, 10,
gui_rgba(255, 0, 0, 255));
gui_rect_set_style(round_rect, 200, 200, 200, 200, 10, gui_rgba(255, 0, 0, 255));
gui_rect_on_click(round_rect, round_rect_timer_cb, NULL);
}
// Gradient rectangle examples
void example_rect_gradient(void *parent)
{
// Example 1: Horizontal gradient (red to blue)
gui_rounded_rect_t *rect1 = gui_rect_create(parent, "rect_h_gradient",
20, 20, 200, 80, 10,
gui_rgba(255, 0, 0, 255));
gui_rect_set_linear_gradient(rect1, RECT_GRADIENT_HORIZONTAL);
gui_rect_add_gradient_stop(rect1, 0.0f, gui_rgba(255, 0, 0, 255)); // Red
gui_rect_add_gradient_stop(rect1, 1.0f, gui_rgba(0, 0, 255, 255)); // Blue
// Example 2: Vertical gradient (green to yellow)
gui_rounded_rect_t *rect2 = gui_rect_create(parent, "rect_v_gradient",
240, 20, 200, 80, 10,
gui_rgba(0, 255, 0, 255));
gui_rect_set_linear_gradient(rect2, RECT_GRADIENT_VERTICAL);
gui_rect_add_gradient_stop(rect2, 0.0f, gui_rgba(0, 255, 0, 255)); // Green
gui_rect_add_gradient_stop(rect2, 1.0f, gui_rgba(255, 255, 0, 255)); // Yellow
// Example 3: Diagonal gradient (top-left to bottom-right)
gui_rounded_rect_t *rect3 = gui_rect_create(parent, "rect_d1_gradient",
20, 120, 200, 120, 15,
gui_rgba(255, 0, 255, 255));
gui_rect_set_linear_gradient(rect3, RECT_GRADIENT_DIAGONAL_TL_BR);
gui_rect_add_gradient_stop(rect3, 0.0f, gui_rgba(255, 0, 255, 255)); // Magenta
gui_rect_add_gradient_stop(rect3, 0.5f, gui_rgba(255, 255, 255, 255)); // White
gui_rect_add_gradient_stop(rect3, 1.0f, gui_rgba(0, 255, 255, 255)); // Cyan
// Example 4: Diagonal gradient (top-right to bottom-left)
gui_rounded_rect_t *rect4 = gui_rect_create(parent, "rect_d2_gradient",
240, 120, 200, 120, 15,
gui_rgba(255, 128, 0, 255));
gui_rect_set_linear_gradient(rect4, RECT_GRADIENT_DIAGONAL_TR_BL);
gui_rect_add_gradient_stop(rect4, 0.0f, gui_rgba(255, 128, 0, 255)); // Orange
gui_rect_add_gradient_stop(rect4, 1.0f, gui_rgba(128, 0, 255, 255)); // Purple
// Example 5: Multi-color rainbow horizontal gradient
gui_rounded_rect_t *rect5 = gui_rect_create(parent, "rect_rainbow",
20, 260, 420, 60, 20,
gui_rgba(255, 0, 0, 255));
gui_rect_set_linear_gradient(rect5, RECT_GRADIENT_HORIZONTAL);
gui_rect_add_gradient_stop(rect5, 0.00f, gui_rgba(255, 0, 0, 255)); // Red
gui_rect_add_gradient_stop(rect5, 0.17f, gui_rgba(255, 127, 0, 255)); // Orange
gui_rect_add_gradient_stop(rect5, 0.33f, gui_rgba(255, 255, 0, 255)); // Yellow
gui_rect_add_gradient_stop(rect5, 0.50f, gui_rgba(0, 255, 0, 255)); // Green
gui_rect_add_gradient_stop(rect5, 0.67f, gui_rgba(0, 0, 255, 255)); // Blue
gui_rect_add_gradient_stop(rect5, 0.83f, gui_rgba(75, 0, 130, 255)); // Indigo
gui_rect_add_gradient_stop(rect5, 1.00f, gui_rgba(148, 0, 211, 255)); // Violet
// Example 6: Gradient with transparency
gui_rounded_rect_t *rect6 = gui_rect_create(parent, "rect_alpha_gradient",
20, 340, 200, 80, 10,
gui_rgba(0, 128, 255, 255));
gui_rect_set_linear_gradient(rect6, RECT_GRADIENT_HORIZONTAL);
gui_rect_add_gradient_stop(rect6, 0.0f, gui_rgba(0, 128, 255, 255)); // Opaque blue
gui_rect_add_gradient_stop(rect6, 1.0f, gui_rgba(0, 128, 255, 50)); // Transparent blue
}
static void app_rect_round_design(gui_view_t *view)
{
gui_view_switch_on_event(view, "rect_view", SWITCH_OUT_ANIMATION_FADE,
SWITCH_IN_ANIMATION_FADE,
GUI_EVENT_KB_SHORT_PRESSED);
gui_view_set_animate_step(view, 500);
uint8_t alpha = 200;
gui_rect_create(gui_obj_get_root(), "bg", 0, 0, 480, 480, 0, gui_rgba(255, 200, 200,
255));
gui_rect_create(gui_obj_get_root(), "geometry1", 20, 20, 200, 200, 20, gui_rgba(255, 0,
0, alpha));
gui_rect_create(gui_obj_get_root(), "geometry2", 50, 50, 200, 200, 20, gui_rgba(0, 255,
0, alpha));
gui_rect_create(gui_obj_get_root(), "geometry3", 80, 80, 200, 200, 20, gui_rgba(0, 0,
255, alpha));
gui_rect_create(gui_obj_get_root(), "geometry1", 150, 150, 200, 200, 20, gui_rgba(255, 0,
0, alpha));
gui_rect_create(gui_obj_get_root(), "geometry2", 210, 210, 200, 200, 20, gui_rgba(0, 255,
0, alpha));
// rect_click_demo();
// example_rect_gradient(gui_obj_get_root());
}
static int geometry_rect_demo_init(void)
{
gui_view_create(gui_obj_get_root(), RECT_VIEW_NAME, 0, 0, 0, 0);
// Uncomment to show gradient examples
return 0;
}
GUI_VIEW_INSTANCE(RECT_VIEW_NAME, false, app_rect_round_design, 0);
GUI_INIT_APP_EXPORT(geometry_rect_demo_init);
API
Enums
Functions
-
gui_rounded_rect_t *gui_rect_create(void *parent, const char *name, int x, int y, int w, int h, int radius, gui_color_t color)
-
Create a new rect widget.
- 参数:
parent -- Parent widget or NULL for root widget.
name -- Widget name or NULL for default name.
x -- X coordinate relative to widget.
y -- Y coordinate relative to widget.
w -- Rect width.
h -- Rect height.
radius -- Rect radius.
color -- Rect color.
- 返回:
-
Pointer to the created rect widget.
-
void gui_rect_set_style(gui_rounded_rect_t *rect, int x, int y, int w, int h, int radius, gui_color_t color)
-
Set the style of the rect widget.
- 参数:
rect -- Pointer to the rect widget.
x -- X coordinate relative to widget.
y -- Y coordinate relative to widget.
w -- Rect width.
h -- Rect height.
radius -- Rect radius.
color -- Rect color.
-
void gui_rect_set_opacity(gui_rounded_rect_t *rect, uint8_t opacity)
-
Set the opacity of the rect widget.
- 参数:
rect -- Pointer to the rect widget.
opacity -- Opacity value (0-255).
-
void gui_rect_set_position(gui_rounded_rect_t *rect, int x, int y)
-
Set the position of the rect widget.
- 参数:
rect -- Pointer to the rect widget.
x -- X coordinate relative to widget.
y -- Y coordinate relative to widget.
-
void gui_rect_set_size(gui_rounded_rect_t *rect, int w, int h)
-
Set the size of the rect widget.
- 参数:
rect -- Pointer to the rect widget.
w -- Rect width.
h -- Rect height.
-
void gui_rect_set_radius(gui_rounded_rect_t *rect, int radius)
-
Set the radius of the rect widget.
- 参数:
rect -- Pointer to the rect widget.
radius -- Rect radius.
-
void gui_rect_set_color(gui_rounded_rect_t *rect, gui_color_t color)
-
Set the color of the rect widget.
- 参数:
rect -- Pointer to the rect widget.
color -- Rect color.
-
void gui_rect_on_click(gui_rounded_rect_t *rect, void *callback, void *parameter)
-
Register a click event callback for the rect widget.
- 参数:
rect -- Pointer to the rect widget.
callback -- Callback function pointer.
parameter -- Optional parameter to pass to the callback.
-
void gui_rect_on_press(gui_rounded_rect_t *rect, void *callback, void *parameter)
-
Register a press event callback for the rect widget.
- 参数:
rect -- Pointer to the rect widget.
callback -- Callback function pointer.
parameter -- Optional parameter to pass to the callback.
-
void gui_rect_rotate(gui_rounded_rect_t *rect, float degrees)
-
Apply rotation transformation to the rect widget.
- 参数:
rect -- Pointer to the rect widget.
degrees -- Rotation angle in degrees (clockwise).
-
void gui_rect_scale(gui_rounded_rect_t *rect, float scale_x, float scale_y)
-
Apply scale transformation to the rect widget.
- 参数:
rect -- Pointer to the rect widget.
scale_x -- Scale factor in X direction.
scale_y -- Scale factor in Y direction.
-
void gui_rect_translate(gui_rounded_rect_t *rect, float tx, float ty)
-
Apply translation transformation to the rect widget.
- 参数:
rect -- Pointer to the rect widget.
tx -- Translation in X direction (pixels).
ty -- Translation in Y direction (pixels).
-
void gui_rect_set_linear_gradient(gui_rounded_rect_t *rect, gui_rect_gradient_dir_t direction)
-
Set linear gradient for rect widget.
- 参数:
rect -- Pointer to the rect widget.
direction -- Gradient direction (horizontal, vertical, diagonal).
-
void gui_rect_add_gradient_stop(gui_rounded_rect_t *rect, float position, gui_color_t color)
-
Add color stop to rect gradient.
- 参数:
rect -- Pointer to the rect widget.
position -- Position of color stop (0.0 to 1.0).
color -- Color at rect stop.
-
void gui_rect_clear_gradient(gui_rounded_rect_t *rect)
-
Clear gradient and use solid color.
- 参数:
-
rect -- Pointer to the rect widget.
-
void gui_rect_set_dither(gui_rounded_rect_t *rect, bool enable)
-
Enable or disable dithering for gradient.
备注
Dithering reduces color banding but may impact performance.
- 参数:
rect -- Pointer to the rect widget.
enable -- true to enable dithering, false to disable.
-
struct gui_rounded_rect_t
-
Rect widget structure.
Public Members
-
gui_obj_t base
-
Base widget.
-
draw_img_t *circle_00
-
draw_img_t *circle_01
-
draw_img_t *circle_10
-
draw_img_t *circle_11
-
uint8_t *circle_data
-
draw_img_t *rect_0
-
draw_img_t *rect_1
-
draw_img_t *rect_2
-
uint8_t *rect_data
-
uint8_t opacity_value
-
Opacity value.
-
int radius
-
Rect radius.
-
gui_color_t color
-
Rect color.
-
uint8_t checksum
-
Checksum for change detection.
-
float degrees
-
Rotation angle in degrees.
-
float scale_x
-
Scale factor in X direction.
-
float scale_y
-
Scale factor in Y direction.
-
float offset_x
-
Translation offset in X direction.
-
float offset_y
-
Translation offset in Y direction.
-
Gradient *gradient
-
Optional gradient for rect fill.
-
bool use_gradient
-
Flag to enable gradient rendering.
-
bool enable_dither
-
Flag to enable dithering for gradient.
-
gui_rect_gradient_dir_t gradient_dir
-
Gradient direction.
-
gui_matrix_t last_matrix
-
Cached matrix for change detection.
-
gui_obj_t base