TpPen 使用指南：C++开发GUI应用中的画笔工具，支持渐变和线帽控制
1. 引言
C++开发GUI应用中,绘制线条、边框和形状轮廓是最基础的需求。TinyPiXOS平台提供了 TpPen 类,作为画笔工具来定义绘图时的线条属性。
TpPen 的核心价值在于:
- 类型安全: 通过封装避免直接操作底层图形 API
- 易于使用: 提供直观的 API 接口
- 功能完整: 支持从基础到高级的所有线条属性控制
2. TpPen 核心功能介绍
2.1 基础属性设置
画笔颜色
通过 setColor() 和 color() 方法管理画笔颜色:
TpPen pen;
pen.setColor(TpColors(255, 0, 0)); // 设置为红色
// 获取当前颜色
TpColors currentColor = pen.color();
颜色通过内部的 TpBrush 对象管理。
画笔宽度
通过 setWidth() 和 width() 方法控制线条粗细:
TpPen pen;
pen.setWidth(3); // 设置为 3 像素宽
// 获取当前宽度
int32_t currentWidth = pen.width();
宽度值会被限制为非负数。
画笔样式
通过 setStyle() 和 style() 方法设置线条样式(实线/虚线等):
TpPen pen;
pen.setStyle(Tp::PenStyle::SolidLine); // 实线
默认样式为实线。
2.2 高级属性
线帽样式
线帽样式控制线条端点的形状:
TpPen pen;
pen.setCapStyle(Tp::RoundCap); // 圆形线帽
pen.setCapStyle(Tp::ButtCap); // 平头线帽
pen.setCapStyle(Tp::SquareCap); // 方形线帽
连接点样式
连接点样式控制线条连接处的形状:
TpPen pen;
pen.setJoinStyle(Tp::RoundJoin); // 圆形连接
pen.setJoinStyle(Tp::MiterJoin); // 尖角连接
pen.setJoinStyle(Tp::BevelJoin); // 斜角连接
虚线偏移
虚线偏移控制虚线图案的起始位置:
TpPen pen;
pen.setDashOffset(5.0f); // 设置偏移量为 5.0
// 获取当前偏移量
float offset = pen.dashOffset();
默认偏移量为 0。
2.3 渐变填充支持 ⭐
TpPen 支持通过 TpBrush 设置渐变填充:
TpPen pen;
TpBrush gradientBrush;
// 配置渐变画刷...
pen.setBrush(gradientBrush);
// 获取当前画刷
TpBrush currentBrush = pen.brush();
这是 TpPen 相比传统画笔的独特优势,支持线性渐变和径向渐变。
3. 使用方法详解
3.1 创建画笔
TpPen 提供多种构造方式:
// 默认构造 - 黑色,1像素宽,实线
TpPen pen1;
// 指定颜色
TpPen pen2(TpColors(255, 0, 0)); // 红色
// 指定颜色和宽度
TpPen pen3(TpColors(0, 0, 255), 3); // 蓝色,3像素宽
默认画笔属性:
- 宽度: 1 像素
- 颜色: 黑色 RGB(0, 0, 0)
- 样式: 实线
- 线帽: 圆形
- 连接: 圆形
3.2 配置画笔属性
TpPen pen;
// 设置基础属性
pen.setColor(TpColors(128, 128, 128)); // 灰色
pen.setWidth(2); // 2像素宽
pen.setStyle(Tp::PenStyle::SolidLine); // 实线
// 设置高级属性
pen.setCapStyle(Tp::RoundCap); // 圆形线帽
pen.setJoinStyle(Tp::RoundJoin); // 圆形连接
3.3 在绘图中使用
TpPen 通过 TpPainter 应用到绘图操作中:
void MyWidget::onPaintEvent(TpPaintEvent *event)
{
TpPainter *painter = event->painter();
// 方式1: 直接设置颜色
painter->setPen(TpColors(255, 0, 0));
// 方式2: 设置完整的画笔对象
TpPen pen(TpColors(0, 0, 255), 2);
pen.setCapStyle(Tp::RoundCap);
painter->setPen(pen);
// 绘制线条
painter->drawLine(10, 10, 100, 100);
// 获取当前画笔并修改
painter->pen().setWidth(3);
painter->drawLine(10, 50, 100, 50);
}
TpPainter 内部维护当前画笔状态。
4. 实际应用场景
4.1 绘制分隔线
在菜单组件中绘制分隔线:
painter->setPen(_RGB(230, 235, 241));
painter->drawHLine(x1, x2, y);
4.2 绘制控件边框
在复选框中绘制边框:
painter->pen().setColor(borderColor);
painter->pen().setWidth(linew);
painter->drawRect(batteryRect, borderRadius);
4.3 绘制圆形进度条
在圆形进度条中使用画笔:
painter->setPen(_RGB(217, 217, 217));
painter->pen().setWidth(progressData->lineWidth);
painter->drawEllipse(circlePoint, circlePoint, radius, radius);
4.4 绘制直线组件
在 TpLine 组件中设置线条属性:
paintCanvas->pen().setColor(lineData->color);
paintCanvas->pen().setWidth(lineData->width);
paintCanvas->drawHLine(startX, startX + length, startY);
5. 高级特性
5.1 渐变画笔
渐变画笔通过 TpBrush 实现,支持线性渐变和径向渐变:
// 创建线性渐变画刷
TpLinearGradient linearGrad;
linearGrad.setStart(TpPointF(0, 0));
linearGrad.setFinalStop(TpPointF(100, 0));
linearGrad.setColorAt(0.0, TpColors(255, 0, 0));
linearGrad.setColorAt(1.0, TpColors(0, 0, 255));
TpBrush gradientBrush(&linearGrad);
TpPen pen;
pen.setBrush(gradientBrush);
在渲染时,渐变会被解析并应用到线条描边。
5.2 线条样式枚举
Tp::PenStyle 定义了支持的线条样式。当前主要使用 SolidLine 实线样式。
5.3 线帽和连接样式的视觉效果
不同样式在渲染时的映射关系:
线帽样式:
Tp::ButtCap- 平头,线条在端点处截断Tp::RoundCap- 圆形,线条端点为半圆Tp::SquareCap- 方形,线条端点延伸半个线宽
连接样式:
Tp::MiterJoin- 尖角,外边缘延伸相交
关于TinyPiXOS
TinyPiXOS是一款面向嵌入式移动终端设备设计的自主可控、架构轻量且高度可定制化的开源桌面操作系统。系统可应用于工业自动化与机器人控制、智能家居与物联网终端、医疗健康设备交互界面、车载智能座舱系统、特种设备用户交互终端等场景。
- 项目官网：www.tinypixos.com
- Gitee仓库：gitee.com/tinypixos/T…
- Github仓库：github.com/TinyPiXOS/T…