绘画系统(06)：【类】QPaintPath[官翻]

1. QPainterPath

QPainterPath类提供了用于绘画操作的容器，从而可以构造和重用图形形状。

1.2 公共类型

类型
class	Element
enum	ElementType { MoveToElement, LineToElement, CurveToElement, CurveToDataElement }

1.3 公共函数

类名	说明
QPainterPath(…)	构造函数,多重
~QPainterPath()	析构函数
void addEllipse(…)	创建一个椭圆,多重,例
void addPath(…)	将给定路径添加为该路径作为封闭子路径。
void addPolygon(…)	添加多边形路径,例
void addRect(…)	添加一个矩形,多重,例
void addRegion(…)	将给定区域添加到路径
void addRoundedRect(…)	添加一个圆角矩形,多重,例
void addText(…)	添加文本,多重,例
qreal angleAtPercent(qreal t) const	返回以百分比t表示的路径切线的角度
void arcMoveTo(…)	创建一个弧线移动
void arcTo(…)	创建一个占据给定矩形的圆弧
QRectF boundingRect() const	返回此绘图器路径的边界矩形
int capacity() const	返回QPainterPath分配的元素数量。
void clear()	清空
void closeSubpath()	关闭当前子路径
void connectPath(…)	将给定路径连接到当前路径
bool contains(…) const	查询是否包含…,多重
QRectF controlPointRect() const	返回包含此路径中所有点和控制点的矩形
void cubicTo(…)	贝塞尔曲线,多重,例
QPointF currentPosition() const	返回当前路径的当前点
QPainterPath::Element elementAt(int index) const	返回画家路径中给定索引处的元素
int elementCount() const	返回画家路径中路径元素的数量。
Qt::FillRule fillRule() const	返回画家路径的当前设置的填充规则。
QPainterPath intersected(…) const	返回一个路径的交集
bool intersects(…) const	查询是否相交,多重
bool isEmpty() const	查询是否为空
qreal length() const	当前路径的长度
void lineTo(…)	从当前位置到给定的端点添加一条直线
void moveTo(…)	将当前点移动到给定点
qreal percentAtLength(qreal len) const	返回指定长度len处整个路径的百分比。
QPointF pointAtPercent(qreal t) const	返回当前路径的百分比t处的点。 参数t必须在0到1之间。
void quadTo(…)	添加一条二次贝塞尔曲线,多重
void reserve(int size)	保留给定数量的元素
void setElementPositionAt(…)	为index的元素的坐标设置为x和y。
void setFillRule(Qt::FillRule fillRule)	将路径的填充规则设置为给定的fillRule
QPainterPath simplified() const	返回此路径的简化版本。
qreal slopeAtPercent(qreal t) const	以百分比t返回路径的斜率
QPainterPath subtracted(…) const	返回一个减去p的填充区域。
void swap(QPainterPath &other)	交换画家路径
QPolygonF toFillPolygon(…) const	返回QTransform矩阵转换后的多边形
QList< QPolygonF > toFillPolygons(…) const	返回QTransform矩阵转换后的多边形列表
QPainterPath toReversed() const	返回路径的反向副本。
QList< QPolygonF > toSubpathPolygons(…) const	返回QTransform矩阵转换后的多边形列表
void translate(…)	转换路径中的所有元素,多重
QPainterPath translated(qreal dx, qreal dy) const	返回转换后的路径,多重
QPainterPath united(const QPainterPath &p) const	返回并集路径
运算符重载…	略

1.4. 详述

画家路径是由许多图形构造块(例如矩形，椭圆形，直线和曲线 )组成的对象。可以将构建块连接到闭合的子路径中，例如以矩形或椭圆形。封闭的路径具有一致的起点和终点。或者它们可以作为未封闭的子路径(例如直线和曲线 )独立存在。

QPainterPath对象可用于填充，勾画轮廓和裁剪。要为给定的绘制路径生成可填充的轮廓，请使用QPainterPathStroker类。与常规绘图操作相比，画家路径的主要优势在于，复杂的形状只需要创建一次即可。那么仅使用对QPainter :: drawPath( )函数的调用就可以绘制多次。

QPainterPath提供了一组函数，这些函数可用于获取有关路径及其元素的信息。另外，可以使用toReversed( )函数反转元素的顺序。还有一些函数可以将此绘制器路径对象转换为多边形表示。

1.4.2 组成一个QPainterPath

QPainterPath对象可以构造为具有给定起点的空路径，也可以构造为另一个QPainterPath对象的副本。创建之后，可以使用lineTo( )，arcTo( )，cubicTo( )和quadTo( )函数将直线和曲线添加到路径。直线和曲线从currentPosition( )延伸到作为参数传递的位置。

QPainterPath对象的currentPosition( )始终是最后添加的子路径(或初始起点 )的结束位置。使用moveTo( )函数移动currentPosition( )而不添加组件。 moveTo( )函数隐式启动一个新的子路径，并关闭前一个子路径。启动新子路径的另一种方法是调用closeSubpath( )函数，该函数通过从currentPosition( )回到路径的起始位置添加一条线来关闭当前路径。请注意，新路径的初始currentPosition( )将具有(0，0 )。

QPainterPath类还提供了几个方便的功能，可将封闭的子路径添加到绘制器路径：addEllipse( )，addPath( )，addRect( )，addRegion( )和addText( )。 addPolygon( )函数添加未封闭的子路径。实际上，这些函数都是moveTo( )，lineTo( )和cubicTo( )操作的集合。

另外，可以使用connectPath( )函数将路径添加到当前路径。但是请注意，此函数将通过添加一行将当前路径的最后一个元素连接到给定元素的第一个元素。

以下是显示如何使用QPainterPath对象的代码段：

QPainterPath path;
path.addRect(20, 20, 60, 60);

path.moveTo(0, 0);
path.cubicTo(99, 0,  50, 50,  99, 99);
path.cubicTo(0, 99,  50, 50,  0, 0);

QPainter painter(this);
painter.fillRect(0, 0, 100, 100, Qt::white);
painter.setPen(QPen(QColor(79, 106, 25), 1, Qt::SolidLine,
                    Qt::FlatCap, Qt::MiterJoin));
painter.setBrush(QColor(122, 163, 39));

painter.drawPath(path);

构造时，画家路径最初是空的。 我们首先添加一个矩形，它是一个封闭的子路径。 然后，我们添加两条贝塞尔曲线，即使它们没有单独闭合，它们也共同形成闭合子路径。 最后，我们绘制了整个路径。 使用默认的填充规则Qt :: OddEvenFill填充路径。 Qt提供了两种填充路径的方法：

Qt::OddEvenFill	Qt::WindingFill

有关规则的定义，请参见 Qt::FillRule文档。 可以使用fillRule( ) 函数检索画家路径的当前设置的填充规则，并使用setFillRule() 函数对其进行更改。

1.4.3 QPainterPath信息

QPainterPath类提供了一个函数集合，这些函数返回有关路径及其元素的信息。

currentPosition() 函数返回添加的最后一个子路径的终点（或初始起点）。可以使用elementAt() 函数来检索各种子路径元素，可以使用elementCount() 函数来检索元素数量，而isEmpty() 函数可以告诉此QPainterPath对象是否完全包含任何元素。
controlPointRect() 函数返回包含此路径中所有点和控制点的矩形。该函数的计算速度比精确的boundingRect() 更快，后者需要以浮点精度返回此绘制路径的边界矩形。

最后，QPainterPath提供了contains() 函数，可用于确定给定点或矩形是否在路径内，而intersects() 函数可确定给定矩形内的点是否也在该路径内。

1.4.4 QPainterPath转换

出于兼容性原因，可能需要简化绘制路径的表示形式：QPainterPath提供了toFillPolygon() ，toFillPolygons() 和toSubpathPolygons() 函数，这些函数将绘制路径转换为多边形。 toFillPolygon() 以一个单一多边形的形式返回绘制器路径，而后两个函数返回一个多边形列表。

之所以提供toFillPolygons() 和toSubpathPolygons() 函数，是因为尽管绘制的点总数相同，但绘制多个小多边形通常比绘制一个大多边形要快。两者之间的区别在于它们返回的多边形数量：toSubpathPolygons() 为每个子路径创建一个多边形，而不管相交的子路径（即重叠的边界矩形）如何，而toFillPolygons() 函数仅为重叠的子路径创建一个多边形。

toFillPolygon() 和toFillPolygons() 函数首先将所有子路径转换为多边形，然后使用倒带技术来确保可以使用正确的填充规则来填充重叠的子路径。请注意，倒带会在多边形中插入其他线条，因此填充多边形的轮廓与路径的轮廓不匹配。

1.4.5 Examples

Qt提供了位于Qt的示例目录中的Painter Paths示例和Vector Deformation示例。

Painter Paths示例显示了如何使用Painter路径来构建复杂的形状以进行渲染，并允许用户尝试填充和描边。 矢量变形示例显示了如何使用QPainterPath绘制文本。

Painter Paths Example	Vector Deformation Example