QPainterPath Class

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);

成员函数文档

[noexcept] QPainterPath::QPainterPath()

创建一个空的 QPainterPath 对象。

[explicit] QPainterPath::QPainterPath(const QPointF &startPoint)

创建一个 QPainterPath 对象，并将给定的startPoint 作为其当前位置。

QPainterPath::QPainterPath(const QPainterPath &path)

创建一个 QPainterPath 对象，该对象是给定的path 的副本。

另请参阅 operator=()。

[noexcept, since 6.10] QPainterPath::QPainterPath(QPainterPath &&other)

从 `other` 创建一个新的绘图路径。

被移动的对象other 将被置于默认构造状态。

该函数于 Qt 6.10 中引入。

[noexcept] QPainterPath::~QPainterPath()

销毁此QPainterPath 对象。

void QPainterPath::addEllipse(const QRectF &boundingRectangle)

在指定的boundingRectangle 内创建一个椭圆，并将其作为闭合子路径添加到绘图路径中。

该椭圆由一条顺时针曲线组成，起点和终点均为零度（3点钟位置）。如Arcs and Ellipses 中所述，该曲线是对椭圆的三次贝塞尔近似，并非其精确表示。

另请参阅 arcTo()、QPainter::drawEllipse() 以及Composing a QPainterPath 。

void QPainterPath::addEllipse(const QPointF &center, qreal rx, qreal ry)

创建一个位于center 处、半径分别为rx 和ry 的椭圆，并将其作为闭合子路径添加到绘图路径中。

void QPainterPath::addEllipse(qreal x, qreal y, qreal width, qreal height)

在由其左上角坐标 (x,y)、width 和height 定义的边界矩形内创建一个椭圆，并将其作为闭合子路径添加到绘图路径中。

void QPainterPath::addPath(const QPainterPath &path)

将给定的path 作为闭合子路径添加到此路径中。

另请参阅 connectPath() 和Composing a QPainterPath 。

void QPainterPath::addPolygon(const QPolygonF &polygon)

将给定的polygon 作为（未闭合的）子路径添加到路径中。

请注意，添加多边形后，当前位置即为polygon 中的最后一点。若要绘制一条线段返回起始点，请使用closeSubpath()函数。

另请参阅 lineTo() 和Composing a QPainterPath 。

void QPainterPath::addRect(const QRectF &rectangle)

将给定的rectangle 作为闭合子路径添加到此路径中。

该rectangle 将作为顺时针方向的一组直线被添加。在添加完rectangle 后，绘制路径的当前位置位于矩形的左上角。

另请参阅 addRegion()、lineTo() 和Composing a QPainterPath 。

void QPainterPath::addRect(qreal x, qreal y, qreal width, qreal height)

在坐标 (x,y) 处添加一个矩形，并使用给定的width 和height 作为闭合子路径。

void QPainterPath::addRegion(const QRegion &region)

将给定的region 添加到路径中，方法是将该区域中的每个矩形作为独立的闭合子路径添加进去。

另请参阅 addRect() 和Composing a QPainterPath 。

void QPainterPath::addRoundedRect(const QRectF &rect, qreal xRadius, qreal yRadius, Qt::SizeMode mode = Qt::AbsoluteSize)

将给定的、具有圆角的矩形rect 添加到路径中。

参数xRadius 和yRadius 指定了定义圆角矩形各角的椭圆半径。当mode 为Qt::RelativeSize 时，xRadius 和yRadius 分别以矩形宽度和高度的一半为基准，以百分比形式指定，且值应在 0.0 到 100.0 之间。

另请参阅 addRect()。

void QPainterPath::addRoundedRect(qreal x, qreal y, qreal w, qreal h, qreal xRadius, qreal yRadius, Qt::SizeMode mode = Qt::AbsoluteSize)

将给定的矩形x 、y 、w 、h （带圆角）添加到路径中。

void QPainterPath::addText(const QPointF &point, const QFont &font, const QString &text)

将给定的text 作为由提供的font 生成的闭合子路径集添加到此路径中。这些子路径的位置调整为：文本基线的左端位于指定的point 处。

某些字体可能会产生重叠的子路径，此时需要使用 `Qt::WindingFill ` 填充规则才能正确渲染。

另请参阅 QPainter::drawText()、Composing a QPainterPath 以及setFillRule()。

void QPainterPath::addText(qreal x, qreal y, const QFont &font, const QString &text)

将给定的text 作为由font 生成的闭合子路径集添加到此路径中。这些子路径的位置调整得使得文本基线的左端位于由(x,y)指定的点上。

qreal QPainterPath::angleAtPercent(qreal t) const

返回路径在百分比t 处切线的角度。参数t 的取值必须在0到1之间。

角度的正值表示逆时针方向，负值表示顺时针方向。零度位于3点钟位置。

请注意，与其他百分比方法类似，如果路径中包含曲线，则百分比测量值与路径长度之间并非线性关系。当路径中存在曲线时，百分比参数会被映射到贝塞尔方程的 t 参数上。

void QPainterPath::arcMoveTo(const QRectF &rectangle, qreal angle)

创建一个位于该弧上的点，该弧在坐标系angle 中占据给定的rectangle 。

角度以度为单位指定。顺时针方向的弧线可使用负角度指定。如果rectangle 不是正方形，则angle 为偏心角，且不以矩形中心为基准测量方向，具体说明参见Arcs and Ellipses 。

另请参阅 moveTo()、arcTo() 以及Arcs and Ellipses 。

void QPainterPath::arcMoveTo(qreal x, qreal y, qreal width, qreal height, qreal angle)

在angle 处创建一个位于弧线上的点，该弧线包含坐标QRectF （x 、y 、width 、height ）。

void QPainterPath::arcTo(const QRectF &rectangle, qreal startAngle, qreal sweepLength)

创建一个占据给定rectangle 的弧，起点为指定的startAngle ，并沿逆时针方向延伸sweepLength 度。

角度以度为单位。顺时针弧线可使用负角度指定。如果rectangle 不是正方形，则这些角度为偏心角，并不表示从矩形中心出发的方向，如Arcs and Ellipses 中所述。

请注意，如果弧的起始点与当前位置尚未连接，该函数会将起始点与当前位置连接起来。添加弧后，当前位置即为弧中的最后一点。若要绘制一条线段返回起始点，请使用closeSubpath() 函数。

另请参阅 arcMoveTo()、addEllipse()、QPainter::drawArc()、QPainter::drawPie() 以及Composing a QPainterPath 。

void QPainterPath::arcTo(qreal x, qreal y, qreal width, qreal height, qreal startAngle, qreal sweepLength)

创建一个占据矩形QRectF （x,y,width,height ）的弧，该弧从指定的startAngle 开始，并沿逆时针方向延伸sweepLength 度。

QRectF QPainterPath::boundingRect() const

返回该绘制路径的边界矩形，该矩形以浮点精度表示。

另请参阅 controlPointRect()。

int QPainterPath::capacity() const

返回由QPainterPath 分配的元素个数。

另请参阅 clear() 和reserve()。

void QPainterPath::clear()

清除已存储的路径元素。

这使得路径能够复用之前的内存分配。

另请参阅 reserve() 和capacity()。

void QPainterPath::closeSubpath()

通过绘制一条连接至当前子路径起点的直线来关闭该子路径，并自动开始绘制一条新路径。新路径的当前点为 (0, 0)。

如果子路径不包含任何元素，则该函数不执行任何操作。

另请参阅 moveTo() 和Composing a QPainterPath 。

void QPainterPath::connectPath(const QPainterPath &path)

通过从该路径的最后一个元素到给定路径的第一个元素添加一条线段，将给定的path 与该路径连接起来。

另请参阅 addPath() 和Composing a QPainterPath 。

bool QPainterPath::contains(const QPainterPath &p) const

如果给定的路径p 包含在当前路径中，则返回true 。如果当前路径的任意一条边与p 相交，则返回false 。

路径上的集合运算将把路径视为区域。非闭合路径将被隐式地视为闭合路径。

另请参阅 intersects()。

bool QPainterPath::contains(const QPointF &point) const

如果给定的 `point ` 位于路径内，则返回 `true `；否则返回 `false`。

另请参阅 intersects()。

bool QPainterPath::contains(const QRectF &rectangle) const

如果给定的rectangle 位于路径内，则返回true ；否则返回false 。

QRectF QPainterPath::controlPointRect() const

返回包含该路径中所有点和控制点的矩形。

该函数的计算速度远快于精确的boundingRect() 函数，且返回的矩形总是boundingRect() 返回的矩形的超集。

另请参阅 boundingRect()。

void QPainterPath::cubicTo(const QPointF &c1, const QPointF &c2, const QPointF &endPoint)

在当前位置与给定的endPoint 之间，使用由c1 和c2 指定的控制点，添加一条三次贝塞尔曲线。

添加曲线后，当前位置将更新为曲线的终点。

另请参阅 quadTo() 和Composing a QPainterPath 。

void QPainterPath::cubicTo(qreal c1X, qreal c1Y, qreal c2X, qreal c2Y, qreal endPointX, qreal endPointY)

在当前位置与终点 (endPointX,endPointY) 之间添加一条三次贝塞尔曲线，其控制点由 (c1X,c1Y) 和 (c2X,c2Y) 指定。

QPointF QPainterPath::currentPosition() const

返回路径的当前位置。

QPainterPath::Element QPainterPath::elementAt(int index) const

返回画家路径中位于指定index 处的元素。

另请参阅 ElementType 、elementCount() 和isEmpty()。

int QPainterPath::elementCount() const

返回绘图路径中的路径元素个数。

另请参阅 ElementType 、elementAt() 和isEmpty()。

Qt::FillRule QPainterPath::fillRule() const

返回绘图路径当前设置的填充规则。

另请参阅 setFillRule()。

QPainterPath QPainterPath::intersected(const QPainterPath &p) const

返回一条路径，该路径是本路径填充区域与p 的填充区域的交集。由于贝塞尔曲线相交运算存在数值不稳定性，贝塞尔曲线可能会被简化为线段。

bool QPainterPath::intersects(const QPainterPath &p) const

如果当前路径与给定路径p 在任何一点相交，则返回true 。此外，如果当前路径包含p 的任何部分，或者被其包含，则返回true 。

路径上的集合运算将把路径视为区域。非闭合路径将被隐式地视为闭合路径。

另请参阅 contains()。

bool QPainterPath::intersects(const QRectF &rectangle) const

如果给定的rectangle 中的任何一点与路径相交，则返回true ；否则返回false 。

如果构成矩形的任意一条边与路径的某一部分相交，或者矩形的任意一部分与路径所包围的任意区域重叠，则视为存在相交。该函数会参考当前的fillRule 来确定哪些区域被视为路径内部。

另请参阅 contains()。

[since 6.10] bool QPainterPath::isCachingEnabled() const

如果启用了缓存，则返回 true；否则返回 false。

该函数自 Qt 6.10 起引入。

另请参阅 setCachingEnabled()。

bool QPainterPath::isEmpty() const

如果该路径中没有元素，或者唯一的元素是MoveToElement ，则返回true ；否则返回false 。

另请参阅 elementCount()。

qreal QPainterPath::length() const

返回当前路径的长度。

void QPainterPath::lineTo(const QPointF &endPoint)

从当前位置到指定的endPoint 添加一条直线。绘制完成后，当前位置将更新为该直线的终点。

另请参阅 addPolygon()、addRect() 和Composing a QPainterPath 。

void QPainterPath::lineTo(qreal x, qreal y)

从当前位置到点 (x,y) 绘制一条直线。

void QPainterPath::moveTo(const QPointF &point)

将当前点移动到指定的point ，同时隐式地开始一个新的子路径并关闭前一个子路径。

另请参阅 closeSubpath() 和Composing a QPainterPath 。

void QPainterPath::moveTo(qreal x, qreal y)

将当前位置移动到 (x,y)，并开始一个新的子路径，同时隐式关闭之前的路径。

qreal QPainterPath::percentAtLength(qreal len) const

返回指定长度len 占整个路径的百分比。

请注意，与其他百分比方法类似，如果路径中包含曲线，则百分比的测量值与长度之间并非线性关系。当路径中包含曲线时，百分比参数会被映射到贝塞尔方程的 t 参数上。

QPointF QPainterPath::pointAtPercent(qreal t) const

返回当前路径中位于百分比位置t 的点。参数t 必须在 0 到 1 之间。

请注意，与其他百分比方法类似，如果路径中包含曲线，则百分比测量值与路径长度之间并非线性关系。当路径中包含曲线时，百分比参数会被映射到贝塞尔方程的 t 参数上。

void QPainterPath::quadTo(const QPointF &c, const QPointF &endPoint)

在当前位置与给定的endPoint 之间添加一条二次贝塞尔曲线，其控制点由c 指定。

添加曲线后，当前点将更新为曲线的端点。

另请参阅 cubicTo() 和Composing a QPainterPath 。

void QPainterPath::quadTo(qreal cx, qreal cy, qreal endPointX, qreal endPointY)

在当前点与端点 (endPointX,endPointY) 之间添加一条二次贝塞尔曲线，其控制点由 (cx,cy) 指定。

void QPainterPath::reserve(int size)

在QPainterPath 的内部存储器中预留指定数量的元素。

尝试为至少size 个元素分配内存。

另请参阅 clear()、capacity() 和QList::reserve()。

[since 6.10] void QPainterPath::setCachingEnabled(bool enabled)

根据enabled 的值启用或禁用长度缓存。

启用缓存可加快涉及路径长度和百分比值的成员函数的重复调用，例如length()、percentAtLength()、pointAtPercent() 等，但需消耗额外的内存来存储中间计算结果。默认情况下，该功能处于禁用状态。

禁用缓存将释放所有已分配的缓存内存。

该函数于 Qt 6.10 中引入。

另请参阅 isCachingEnabled(),length(),percentAtLength(),pointAtPercent() 以及trimmed()。

void QPainterPath::setElementPositionAt(int index, qreal x, qreal y)

将索引为index 的元素的x和y坐标分别设置为x 和y 。

void QPainterPath::setFillRule(Qt::FillRule fillRule)

将绘图路径的填充规则设置为给定的fillRule 。Qt 提供了两种填充路径的方法：

另请参阅 fillRule()。

QPainterPath QPainterPath::simplified() const

返回该路径的简化版本。这意味着将所有相交的子路径合并，并返回一条不包含相交边线的路径。连续的平行线也将被合并。简化后的路径始终使用默认的填充规则：Qt::OddEvenFill 。由于贝塞尔曲线相交运算存在数值不稳定性，贝塞尔曲线可能会被简化为线段。

qreal QPainterPath::slopeAtPercent(qreal t) const

返回路径在百分比位置t 处的斜率。参数t 必须在0到1之间。

请注意，与其他百分比方法类似，如果路径中包含曲线，则百分比测量值与长度之间并非线性关系。当路径中存在曲线时，百分比参数将被映射到贝塞尔方程的 t 参数上。

QPainterPath QPainterPath::subtracted(const QPainterPath &p) const

返回一条路径，该路径等于p 的填充区域减去本路径的填充区域。

路径上的集合运算将把路径视为区域。非闭合路径将被隐式地视为闭合路径。由于贝塞尔曲线相交运算存在数值不稳定性，贝塞尔曲线可能会被简化为线段。

[noexcept] void QPainterPath::swap(QPainterPath &other)

将此绘图路径与other 进行交换。此操作速度极快，且绝不会失败。

QPolygonF QPainterPath::toFillPolygon(const QTransform &matrix = QTransform()) const

使用QTransform 方法（matrix ）将路径转换为多边形，并返回该多边形。

该多边形的创建过程是：首先将所有子路径转换为多边形，然后使用回卷技术，以确保重叠的子路径能够按照正确的填充规则进行填充。

请注意，回卷操作会在多边形中插入额外的线条，因此填充多边形的轮廓与路径的轮廓并不一致。

另请参阅 toSubpathPolygons()、toFillPolygons() 和QPainterPath Conversion 。

QList<QPolygonF> QPainterPath::toFillPolygons(const QTransform &matrix = QTransform()) const

使用QTransform matrix 将路径转换为多边形列表，并返回该列表。

该函数与toFillPolygon()函数的不同之处在于，它会创建多个多边形。之所以提供该函数，是因为通常绘制多个小多边形比绘制一个大多边形更快，尽管绘制的点总数相同。

toFillPolygons() 函数与toSubpathPolygons() 函数的不同之处在于，它仅为具有重叠边界矩形的子路径创建一个多边形。

与toFillPolygon()函数类似，该函数采用回卷技术，以确保重叠的子路径能够按照正确的填充规则进行填充。请注意，回卷操作会在多边形中插入额外的线条，因此填充多边形的轮廓与路径的轮廓并不一致。

另请参阅 toSubpathPolygons()、toFillPolygon() 和QPainterPath Conversion 。

QPainterPath QPainterPath::toReversed() const

创建并返回路径的反向副本。

被反转的是元素的顺序：如果通过按指定顺序调用moveTo()、lineTo() 和cubicTo() 函数来组合一个QPainterPath ，则其反向副本是通过调用cubicTo()、lineTo() 和moveTo() 函数来组合的。

QList<QPolygonF> QPainterPath::toSubpathPolygons(const QTransform &matrix = QTransform()) const

使用QTransform matrix 将路径转换为多边形列表，并返回该列表。

该函数会为每个子路径创建一个多边形，无论子路径之间是否相交（即边界矩形是否重叠）。若要确保此类重叠的子路径能够被正确填充，请改用toFillPolygons()函数。

另请参阅 toFillPolygons()、toFillPolygon() 和QPainterPath Conversion 。

void QPainterPath::translate(qreal dx, qreal dy)

将路径中的所有元素按 (dx,dy) 进行平移。

另请参阅 translated()。

void QPainterPath::translate(const QPointF &offset)

将路径中的所有元素按给定的offset 进行平移。

另请参阅 translated()。

QPainterPath QPainterPath::translated(qreal dx, qreal dy) const

返回由 (dx,dy) 转换后的路径的副本。

另请参阅 translate()。

QPainterPath QPainterPath::translated(const QPointF &offset) const

返回由给定的offset 转换后的路径的副本。

另请参阅 translate()。

[since 6.10] QPainterPath QPainterPath::trimmed(qreal fromFraction, qreal toFraction, qreal offset = 0) const

返回路径中位于长度分数fromFraction 和toFraction 之间的部分。这些分数的有效范围从 0（表示路径的起始点）到 1（表示路径的终点）。与百分比t值不同，这些分数是与路径长度成线性关系的。

offset 的值将被加到分数值上。如果这导致 [0, 1] 范围发生溢出或下溢，这些值将进行循环折返，生成的路径也会随之循环折返。偏移量的有效范围在 -1 到 1 之间。

通过 {启用缓存}{setCachingEnabled()} 可以优化对该函数的重复调用。

该函数自 Qt 6.10 起引入。

另请参阅 length()、percentAtLength() 和setCachingEnabled()。

QPainterPath QPainterPath::united(const QPainterPath &p) const

返回一条路径，该路径是本路径的填充区域与p 的填充区域的并集。

路径上的集合运算会将路径视为区域。非闭合路径将被隐式地视为闭合路径。由于贝塞尔曲线相交运算存在数值不稳定性，贝塞尔曲线可能会被简化为线段。

另请参阅 intersected() 和subtracted()。

bool QPainterPath::operator!=(const QPainterPath &path) const

如果此绘制器路径与给定的path 不一致，则返回true 。

请注意，路径比较可能涉及逐元素比较，对于复杂路径而言，这可能会导致速度变慢。

另请参阅 operator==()。

QPainterPath QPainterPath::operator&(const QPainterPath &other) const

返回该路径与other 路径的交集。

另请参阅 intersected()、operator&=()、united() 以及operator|()。

QPainterPath &QPainterPath::operator&=(const QPainterPath &other)

将此路径与other 进行交叉查询，并返回对此路径的引用。

另请参阅 intersected()、operator&() 和operator|=()。

QPainterPath QPainterPath::operator+(const QPainterPath &other) const

返回该路径与other 路径的并集。该函数等同于运算符|()。

另请参阅 united()、operator+=() 和operator-()。

QPainterPath &QPainterPath::operator+=(const QPainterPath &other)

将此路径与other 合并，并返回对此路径的引用。这等同于运算符 |=()。

另请参阅 united()、operator+() 和operator-=()。

QPainterPath QPainterPath::operator-(const QPainterPath &other) const

从该路径的副本中减去other 路径，并返回该副本。

另请参阅 subtracted()、operator-=() 和operator+()。

QPainterPath &QPainterPath::operator-=(const QPainterPath &other)

从该路径中减去other ，并返回该路径的引用。

另请参阅 subtracted()、operator-() 和operator+=()。

[noexcept] QPainterPath &QPainterPath::operator=(QPainterPath &&other)

将other 通过“Move-assigns”操作赋值给此QPainterPath 实例。

QPainterPath &QPainterPath::operator=(const QPainterPath &path)

将给定的path 分配给此绘制路径。

另请参阅 QPainterPath()。

bool QPainterPath::operator==(const QPainterPath &path) const

如果该绘图路径（painterpath）与给定的路径（path ）相等，则返回true 。

请注意，路径比较可能涉及逐元素比较，对于复杂路径而言，这可能会导致性能较低。

另请参阅 operator!=()。

QPainterPath QPainterPath::operator|(const QPainterPath &other) const

返回该路径与other 路径的并集。

另请参阅 united()、operator|=()、intersected() 以及operator&()。

QPainterPath &QPainterPath::operator|=(const QPainterPath &other)

将此路径与other 合并，并返回对此路径的引用。

另请参阅 united()、operator|() 和operator&=()。