# TpPen 使用指南:嵌入式 GUI 中的画笔工具，支持渐变和线帽控制

## 1. 引言

在嵌入式 GUI 开发中,绘制线条、边框和形状轮廓是最基础的需求。[TinyPiXOS](https://www.tinypixos.com)平台提供了 `TpPen` 类,作为画笔工具来定义绘图时的线条属性。

`TpPen` 的核心价值在于:  

- **类型安全**: 通过封装避免直接操作底层图形 API
- **易于使用**: 提供直观的 API 接口
- **功能完整**: 支持从基础到高级的所有线条属性控制

![TpPen功能演示](https://developer.qcloudimg.com/http-save/yehe-10160183/5d5e8ddb53a4c065530f5c2274f48e97.png)

## 2. TpPen 核心功能介绍

### 2.1 基础属性设置

#### 画笔颜色

通过 `setColor()` 和 `color()` 方法管理画笔颜色:

```cpp
TpPen pen;
pen.setColor(TpColors(255, 0, 0));  // 设置为红色

// 获取当前颜色
TpColors currentColor = pen.color();
```

颜色通过内部的 `TpBrush` 对象管理。

#### 画笔宽度

通过 `setWidth()` 和 `width()` 方法控制线条粗细:

```cpp
TpPen pen;
pen.setWidth(3);  // 设置为 3 像素宽

// 获取当前宽度
int32_t currentWidth = pen.width();
```

宽度值会被限制为非负数。

#### 画笔样式

通过 `setStyle()` 和 `style()` 方法设置线条样式(实线/虚线等):

```cpp
TpPen pen;
pen.setStyle(Tp::PenStyle::SolidLine);  // 实线
```

默认样式为实线。

### 2.2 高级属性

#### 线帽样式

线帽样式控制线条端点的形状:

```cpp
TpPen pen;
pen.setCapStyle(Tp::RoundCap);   // 圆形线帽
pen.setCapStyle(Tp::ButtCap);    // 平头线帽
pen.setCapStyle(Tp::SquareCap);  // 方形线帽
```

#### 连接点样式

连接点样式控制线条连接处的形状:

```cpp
TpPen pen;
pen.setJoinStyle(Tp::RoundJoin);   // 圆形连接
pen.setJoinStyle(Tp::MiterJoin);   // 尖角连接
pen.setJoinStyle(Tp::BevelJoin);   // 斜角连接
```

#### 虚线偏移

虚线偏移控制虚线图案的起始位置:

```cpp
TpPen pen;
pen.setDashOffset(5.0f);  // 设置偏移量为 5.0

// 获取当前偏移量
float offset = pen.dashOffset();
```

默认偏移量为 0。

### 2.3 渐变填充支持 ⭐

`TpPen` 支持通过 `TpBrush` 设置渐变填充:

```cpp
TpPen pen;
TpBrush gradientBrush;
// 配置渐变画刷...
pen.setBrush(gradientBrush);

// 获取当前画刷
TpBrush currentBrush = pen.brush();
```

这是 `TpPen` 相比传统画笔的独特优势,支持线性渐变和径向渐变。

## 3. 使用方法详解

### 3.1 创建画笔

`TpPen` 提供多种构造方式:

```cpp
// 默认构造 - 黑色,1像素宽,实线
TpPen pen1;

// 指定颜色
TpPen pen2(TpColors(255, 0, 0));  // 红色

// 指定颜色和宽度
TpPen pen3(TpColors(0, 0, 255), 3);  // 蓝色,3像素宽
```

默认画笔属性:
- 宽度: 1 像素
- 颜色: 黑色 RGB(0, 0, 0)
- 样式: 实线
- 线帽: 圆形
- 连接: 圆形

### 3.2 配置画笔属性

```cpp
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` 应用到绘图操作中:

```cpp
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 绘制分隔线

在菜单组件中绘制分隔线:

```cpp
painter->setPen(_RGB(230, 235, 241));
painter->drawHLine(x1, x2, y);
```

### 4.2 绘制控件边框

在复选框中绘制边框:

```cpp
painter->pen().setColor(borderColor);
painter->pen().setWidth(linew);
painter->drawRect(batteryRect, borderRadius);
```

### 4.3 绘制圆形进度条

在圆形进度条中使用画笔:

```cpp
painter->setPen(_RGB(217, 217, 217));
painter->pen().setWidth(progressData->lineWidth);
painter->drawEllipse(circlePoint, circlePoint, radius, radius);
```

### 4.4 绘制直线组件

在 `TpLine` 组件中设置线条属性:

```cpp
paintCanvas->pen().setColor(lineData->color);
paintCanvas->pen().setWidth(lineData->width);
paintCanvas->drawHLine(startX, startX + length, startY);
```

## 5. 高级特性

### 5.1 渐变画笔

渐变画笔通过 `TpBrush` 实现,支持线性渐变和径向渐变:

```cpp
// 创建线性渐变画刷
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` - 尖角,外边缘延伸相交


在嵌入式 GUI 开发中,绘制线条、边框和形状轮廓是最基础的需求。TinyPiXOS平台提供了 TpPen 类,作为画笔工具来定义绘图时的线条属性。

TpPen 使用指南:嵌入式 GUI 中的画笔工具，支持渐变和线帽控制

硬件

前端

客户端

TpPen是嵌入式GUI开发中的高效画笔工具，支持颜色、宽度、样式设置，提供线帽控制、连接点样式等高级功能，并支持渐变填充。适用于绘制线条、边框、进度条等场景，提升嵌入式界面开发效率。

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

TpPen 使用指南:嵌入式 GUI 中的画笔工具，支持渐变和线帽控制-腾讯云开发者社区-腾讯云

TpPen 使用指南:嵌入式 GUI 中的画笔工具，支持渐变和线帽控制

TpPen 使用指南:嵌入式 GUI 中的画笔工具，支持渐变和线帽控制

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐