Back to Qt.io
Contact Us Blog Download Qt
本页内容

QCanvasPainter Class

QCanvasPainter 类在QRhi 上执行硬件加速绘制。更多内容...

标题： #include <QCanvasPainter>
CMake： find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)
target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter)
自： Qt 6.11

公共类型

enum class CompositeOperation { SourceOver, SourceAtop, DestinationOut }
(since 6.12) enum class FillRule { NonZero, EvenOdd }
enum class ImageFlag { GenerateMipmaps, RepeatX, RepeatY, Repeat, FlipY, …, Nearest }
flags ImageFlags
enum class LineCap { Butt, Round, Square }
enum class LineJoin { Round, Bevel, Miter }
enum class PathConnection { NotConnected, Connected }
enum class PathWinding { CounterClockWise, ClockWise }
enum class TextAlign { Left, Right, Center, Start, End }
enum class TextBaseline { Top, Hanging, Middle, Alphabetic, Bottom }
enum class TextDirection { LeftToRight, RightToLeft, Inherit, Auto }
enum class WrapMode { NoWrap, Wrap, WordWrap, WrapAnywhere }

公共函数

QCanvasPainter()
~QCanvasPainter()
qsizetype activeImageCount() const
qsizetype activeImageMemoryUsage() const
QCanvasImage addImage(const QImage &image, QCanvasPainter::ImageFlags flags = {})
QCanvasImage addImage(QRhiTexture *texture, QCanvasPainter::ImageFlags flags = {})
QCanvasImage addImage(const QCanvasOffscreenCanvas &canvas, QCanvasPainter::ImageFlags flags = {})
void addPath(const QPainterPath &path)
void addPath(const QCanvasPath &path, const QTransform &transform = QTransform())
void addPath(const QCanvasPath &path, qsizetype start, qsizetype count, const QTransform &transform = QTransform())
void arc(qreal centerX, qreal centerY, qreal radius, qreal a0, qreal a1, QCanvasPainter::PathWinding direction = PathWinding::ClockWise, QCanvasPainter::PathConnection connection = PathConnection::Connected)
void arc(QPointF centerPoint, qreal radius, qreal a0, qreal a1, QCanvasPainter::PathWinding direction = PathWinding::ClockWise, QCanvasPainter::PathConnection connection = PathConnection::Connected)
void arcTo(qreal x1, qreal y1, qreal x2, qreal y2, qreal radius)
void arcTo(QPointF controlPoint1, QPointF controlPoint2, qreal radius)
void beginHoleSubPath()
void beginPath()
void beginSolidSubPath()
void bezierCurveTo(qreal cp1X, qreal cp1Y, qreal cp2X, qreal cp2Y, qreal x, qreal y)
void bezierCurveTo(QPointF controlPoint1, QPointF controlPoint2, QPointF endPoint)
void circle(qreal centerX, qreal centerY, qreal radius)
void circle(QPointF centerPoint, qreal radius)
void cleanupResources()
void clearRect(qreal x, qreal y, qreal width, qreal height)
void clearRect(const QRectF &rect)
void closePath()
QCanvasOffscreenCanvas createCanvas(QSize pixelSize, int sampleCount = 1, QCanvasOffscreenCanvas::Flags flags = {})
void destroyCanvas(QCanvasOffscreenCanvas &canvas)
void drawBoxShadow(const QCanvasBoxShadow &shadow)
void drawImage(const QCanvasImage &image, qreal x, qreal y)
void drawImage(const QCanvasImage &image, const QRectF &destinationRect)
void drawImage(const QCanvasImage &image, const QRectF &sourceRect, const QRectF &destinationRect)
void drawImage(const QCanvasImage &image, qreal x, qreal y, qreal width, qreal height)
void ellipse(qreal centerX, qreal centerY, qreal radiusX, qreal radiusY)
void ellipse(const QRectF &rect)
void ellipse(QPointF centerPoint, qreal radiusX, qreal radiusY)
void fill()
(since 6.12) void fill(QCanvasPainter::FillRule fillRule)
void fill(const QCanvasPath &path, int pathGroup = -1)
(since 6.12) void fill(const QCanvasPath &path, QCanvasPainter::FillRule fillRule, int pathGroup = -1)
void fillRect(qreal x, qreal y, qreal width, qreal height)
void fillRect(const QRectF &rect)
void fillText(const QString &text, qreal x, qreal y, qreal maxWidth = 0)
void fillText(const QString &text, const QRectF &rect)
void fillText(const QString &text, QPointF point, qreal maxWidth = 0)
QTransform getTransform() const
void lineTo(qreal x, qreal y)
void lineTo(QPointF point)
void moveTo(qreal x, qreal y)
void moveTo(QPointF point)
void quadraticCurveTo(qreal cpX, qreal cpY, qreal x, qreal y)
void quadraticCurveTo(QPointF controlPoint, QPointF endPoint)
void rect(qreal x, qreal y, qreal width, qreal height)
void rect(const QRectF &rect)
void removeImage(const QCanvasImage &image)
void removePathGroup(int pathGroup)
void reset()
void resetClipping()
void resetTransform()
void restore()
void rotate(qreal angle)
void roundRect(qreal x, qreal y, qreal width, qreal height, qreal radius)
void roundRect(const QRectF &rect, qreal radius)
void roundRect(const QRectF &rect, qreal radiusTopLeft, qreal radiusTopRight, qreal radiusBottomRight, qreal radiusBottomLeft)
void roundRect(qreal x, qreal y, qreal width, qreal height, qreal radiusTopLeft, qreal radiusTopRight, qreal radiusBottomRight, qreal radiusBottomLeft)
void save()
void scale(qreal scale)
void scale(qreal scaleX, qreal scaleY)
void setAntialias(qreal antialias)
void setClipRect(qreal x, qreal y, qreal width, qreal height)
void setClipRect(const QRectF &rect)
(since 6.12) void setFillRule(QCanvasPainter::FillRule fillRule)
void setFillStyle(QColor color)
void setFillStyle(const QCanvasBrush &brush)
void setFont(const QFont &font)
void setGlobalAlpha(qreal alpha)
void setGlobalBrightness(qreal value)
void setGlobalCompositeOperation(QCanvasPainter::CompositeOperation operation)
void setGlobalContrast(qreal value)
void setGlobalSaturation(qreal value)
void setHighQualityStroking(bool enabled)
void setLineCap(QCanvasPainter::LineCap cap)
void setLineJoin(QCanvasPainter::LineJoin join)
void setLineWidth(qreal width)
void setMiterLimit(qreal limit)
void setPathWinding(QCanvasPainter::PathWinding winding)
void setStrokeStyle(QColor color)
void setStrokeStyle(const QCanvasBrush &brush)
void setTextAlign(QCanvasPainter::TextAlign align)
void setTextAntialias(qreal antialias)
void setTextBaseline(QCanvasPainter::TextBaseline baseline)
void setTextDirection(QCanvasPainter::TextDirection direction)
void setTextLineHeight(qreal height)
void setTextWrapMode(QCanvasPainter::WrapMode wrapMode)
void setTransform(const QTransform &transform)
void setWindingEnforce(bool enabled)
void skew(qreal angleX, qreal angleY = 0.0)
void stroke()
void stroke(const QCanvasPath &path, int pathGroup = -1)
void strokeRect(qreal x, qreal y, qreal width, qreal height)
void strokeRect(const QRectF &rect)
QRectF textBoundingBox(const QString &text, qreal x, qreal y, qreal maxWidth = 0) const
QRectF textBoundingBox(const QString &text, const QRectF &rect) const
QRectF textBoundingBox(const QString &text, QPointF point, qreal maxWidth = 0) const
void transform(const QTransform &transform)
void translate(qreal x, qreal y)
void translate(QPointF point)

详细说明

Qt 画布绘制器 (QCanvasPainter) 提供了一套针对硬件加速（GPU）绘制进行优化的绘制 API。该 API 严格遵循 HTML Canvas 2D 上下文规范，并移植到了 Qt C++ 环境中。它还受到了QPainter 的影响，但 API 设计更为紧凑。

以下是一个使用 QCanvasPainter 创建圆形按钮的简单示例。

一个圆形的黄色按钮，上面标有“CLICK!”字样，并带有柔和的阴影效果
QRectF rect(40, 70, 120, 60);
QRectF shadowRect = rect.translated(2, 4);
// Paint shadow
QCanvasBoxShadow shadow(shadowRect);
shadow.setRadius(30);
shadow.setBlur(15);
shadow.setColor("#60373F26");
p->drawBoxShadow(shadow);
// Paint rounded rect
p->beginPath();
p->roundRect(rect, 30);
p->setFillStyle("#DBEB00");
p->fill();
// Paint text
p->setTextAlign(QCanvasPainter::TextAlign::Center);
p->setTextBaseline(QCanvasPainter::TextBaseline::Middle);
QFont font("Titillium Web", 18);
p->setFont(font);
p->setFillStyle("#373F26");
p->fillText("CLICK!", rect);

以下是绘制简单图形的另一个示例。

在深色网格上，S形曲线呈现从绿色到红色的阴影效果，坐标轴为白色
// Paint grid
QCanvasGridPattern grid(0, 0, 10, 10);
grid.setLineColor("#404040");
grid.setBackgroundColor("#202020");
p->setFillStyle(grid);
p->fillRect(0, 0, width(), height());
// Paint axis
p->setFillStyle(QColorConstants::White);
p->fillRect(0, 0.5 * height() - 1, width(), 2);
p->fillRect(0.5 * width() - 1, 0, 2, height());
// Paint shadowed graph
p->beginPath();
p->moveTo(20, height() * 0.8);
p->bezierCurveTo(width() * 0.2, height() * 0.4,
                 width() * 0.5, height() * 0.8,
                 width() - 20, height() * 0.2);
p->setAntialias(10);
p->setLineWidth(12);
p->setStrokeStyle("#D0000000");
p->stroke();
p->setAntialias(1);
p->setLineWidth(6);
QCanvasLinearGradient lg(0, 0, 0, height());
lg.setStartColor(QColorConstants::Red);
lg.setEndColor(QColorConstants::Green);
p->setStrokeStyle(lg);
p->stroke();

功能

总体而言，从命名规范的角度来看，QCanvasPainter 遵循 HTML Canvas 2D 上下文规范（https://html.spec.whatwg.org/multipage/canvas.html#2dcontext）。 这使得许多开发者对该 API 感到熟悉，并且能够轻松复用现有的 canvas 代码。但其目标并非与 HTML canvas 实现 100% 兼容。 QCanvasPainter 省略了部分功能，以使其更简洁、在QRhi 硬件加速图形 API 上性能更佳，并更好地满足现代 UI 的需求。正因如此，与 HTML Canvas 2D 上下文相比，QCanvasPainter 还具备一些额外功能。

以下是与 HTML Canvas 相比，目前至少尚不支持的部分功能：

  • 裁剪：所有裁剪均为（经过变换的）矩形，不支持对路径形状进行裁剪。
  • 虚线：描边始终为实线，不支持虚线/点线描边样式。
  • 路径检测：没有 isPointInPath() 或 isPointInStroke() 方法。
  • 文本描边：不支持文本的轮廓描边。
  • 滤镜：不支持 Canvas SVG 滤镜效果。
  • 合成模式：合成模式的数量限制为 3 种，且无需渲染到额外的缓冲区即可支持。
  • 阴影：不支持内置的阴影方法。

另一方面，与 HTML Canvas 相比，QCanvasPainter 提供了一些额外功能，包括：

  • 路径组：QCanvasPainter 允许在静态路径上绘制，并将这些路径作为组进行缓存，以实现 GPU 的最优利用。
  • 可调节的抗锯齿：得益于路径顶点抗锯齿和 SDF 文本渲染，可以自由调整抗锯齿的像素数量，以实现更平滑的绘制效果。
  • 矩形渐变：除了线性、径向和锥形渐变外，QCanvasPainter 还支持圆角矩形渐变。
  • 盒阴影：QCanvasPainter 还支持 CSS box-shadow 类型的画笔。其渲染采用类似于Qt Quick RectangularShadow 的 SDF 方法，因此性能非常出色。
  • 网格图案：QCanvasPainter 支持QCanvasGridPattern 实现动态网格和条纹图案样式。
  • 自定义画笔：QCanvasPainter 还允许使用自定义顶点着色器和片段着色器（QCanvasCustomBrush ）进行填充和描边。这些自定义画笔也可用于文本。
  • 文本换行：QCanvasPainter 支持将文本自动换行为多行，并提供多种换行模式。
  • 颜色效果：除了 globalAlpha 之外，QCanvasPainter 还支持全局亮度、对比度和饱和度。
  • 着色图像：QCanvasPainter 为绘制图像和图像图案增加了着色支持。

QCanvasPainter 与架构无关，既可用于Qt Quick 应用程序，也可用于Qt Widgets 应用程序。实际上，即使不使用上述任何一种，仅通过QWindow 和QRhi 也能使用它。要使用 QCanvasPainter，请根据应用程序的架构，从以下类之一调用它：

描边规则

QCanvasPainter 默认使用NonZero ({Qt::WindingFill}) 填充规则。若要根据路径点方向选择填充方式，请通过调用setWindingEnforce(false) 禁用强制绕行。

一个绿色的向下三角形，其顶部附近有一个较小的未填充的三角形空洞
p->setWindingEnforce(false);
p->beginPath();
// Outer shape, counterclockwise
p->moveTo(20, 20);
p->lineTo(100, 180);
p->lineTo(180, 20);
p->closePath();
// Inner shape, clockwise
p->moveTo(100, 40);
p->lineTo(125, 90);
p->lineTo(75, 90);
p->closePath();
p->fill();
p->stroke();

不过，更常见的情况是依赖绕行强制规则，并通过setPathWinding() 或beginHoleSubPath() 以及beginSolidSubPath() 辅助函数设置首选绕行方式。

一个绿色的圆角方形轮廓，内部有一个圆角孔，孔中包含一条实心条和一个圆点
p->beginPath();
p->roundRect(20, 20, 160, 160, 30);
// Start painting holes
p->beginHoleSubPath();
p->roundRect(40, 40, 120, 120, 10);
// Start painting solid
p->beginSolidSubPath();
p->rect(60, 60, 80, 20);
p->circle(100, 120, 20);
p->fill();
p->stroke();

成员类型文档

enum class QCanvasPainter::CompositeOperation

Qt Canvas Painter 支持 3 种合成操作：

常量值描述
QCanvasPainter::CompositeOperation::SourceOver0默认值。将新图形绘制在现有内容之上。
QCanvasPainter::CompositeOperation::SourceAtop1新图形仅在其与现有内容重叠的区域内绘制。
QCanvasPainter::CompositeOperation::DestinationOut2在不与新图形重叠的位置，将保留现有内容。

另请参阅 setGlobalCompositeOperation()。

[since 6.12] enum class QCanvasPainter::FillRule

此枚举指定路径的填充方式。

常量值描述
QCanvasPainter::FillRule::NonZero0路径采用“非零绕行规则”进行填充。根据该规则，我们通过以下方法判断一个点是否位于图形内部：从该点向图形外部绘制一条水平线，并判断该线在每个交点处的方向是向上还是向下。 通过将每个交点的方向求和来确定环绕数。如果该数值不为零，则该点位于图形内部。在大多数情况下，此填充模式也可视为闭合图形的交集。此模式为默认模式。
QCanvasPainter::FillRule::EvenOdd1路径采用奇偶填充规则进行填充。根据该规则，我们通过以下方法判断一个点是否位于形状内部：从该点向形状外部绘制一条水平线，并统计交点数量。如果交点数量为奇数，则该点位于形状内部。

该枚举类型在 Qt 6.12 中引入。

另请参阅 fill()。

enum class QCanvasPainter::ImageFlag
flags QCanvasPainter::ImageFlags

此枚举指定了与图像相关的标志。请配合addImage() 使用以设置这些标志。

常量值描述
QCanvasPainter::ImageFlag::GenerateMipmaps1 << 0设置此选项可为图像生成Mipmap。当需要对缩小至原始尺寸以下的图像生成更平滑的输出时，应使用Mipmap。
QCanvasPainter::ImageFlag::RepeatX1 << 1与图像图案配合使用，可在 X 坐标方向上重复图像。
QCanvasPainter::ImageFlag::RepeatY1 << 2与图像图案配合使用，可在 Y 坐标方向上重复图像。
QCanvasPainter::ImageFlag::RepeatRepeatX | RepeatY与图像图案配合使用，可在两个坐标轴上重复图像。
QCanvasPainter::ImageFlag::FlipY1 << 3渲染时沿 Y 方向翻转（反转）图像。
QCanvasPainter::ImageFlag::Premultiplied1 << 4图像数据已预乘了透明度（alpha）。
QCanvasPainter::ImageFlag::Nearest1 << 5图像插值方式为“最近邻”而非“线性”

ImageFlags 类型是QFlags<ImageFlag> 的 typedef。它存储 ImageFlag 值的按“或”运算组合。

enum class QCanvasPainter::LineCap

LineCap 用于定义线条末端（线端）的绘制方式。

常量值描述
QCanvasPainter::LineCap::Butt0（默认）方形线端，不覆盖线的终点。
QCanvasPainter::LineCap::Round1圆角线端。
QCanvasPainter::LineCap::Square2方形线端，覆盖线端点并向外延伸半个线宽。

另请参阅 setLineCap()。

enum class QCanvasPainter::LineJoin

LineJoin 用于定义两条相连线段之间的连接线如何绘制。

常量值描述
QCanvasPainter::LineJoin::Round0两条线之间的圆弧被填充。
QCanvasPainter::LineJoin::Bevel1两条线之间的三角形缺口被填充。
QCanvasPainter::LineJoin::Miter2（默认）两条线的外边缘延伸至相交成一角，并填充该区域。

另请参阅 setLineJoin() 和setMiterLimit()。

enum class QCanvasPainter::PathConnection

在某些绘图方法中，PathConnection 用于指定新路径是否应与前一条路径的最后一点连接。

常量值描述
QCanvasPainter::PathConnection::NotConnected0不会从上一个路径的最后一点到当前路径的第一点绘制线条。
QCanvasPainter::PathConnection::Connected1将前一条路径的最后一点与当前路径的第一点连接起来。

另请参阅 arc()。

enum class QCanvasPainter::PathWinding

PathWinding 用于指定路径绘制的方向。该方向用于确定子路径在路径中是实线还是空心。

常量值描述
QCanvasPainter::PathWinding::CounterClockWise0（默认）实心形状采用逆时针绕行。
QCanvasPainter::PathWinding::ClockWise1对于孔，采用顺时针绕行。

另请参阅 setPathWinding()。

enum class QCanvasPainter::TextAlign

TextAlign 用于定义文本的水平对齐方式。

常量值描述
QCanvasPainter::TextAlign::Left0将文本的左侧水平对齐到指定位置。
QCanvasPainter::TextAlign::Right1将文本的右侧水平对齐到指定位置。
QCanvasPainter::TextAlign::Center2将文本中心水平对齐到指定位置。
QCanvasPainter::TextAlign::Start3（默认）文本对齐于行首（对于从左到右的区域设置，为左对齐；对于从右到左的区域设置，为右对齐）。
QCanvasPainter::TextAlign::End4文本对齐于行尾的正常位置（对于从左到右的语言环境，为右对齐；对于从右到左的语言环境，为左对齐）。

另请参阅 setTextAlign()、setTextDirection() 和fillText()。

enum class QCanvasPainter::TextBaseline

TextBaseline 用于定义文本的垂直对齐方式（基线对齐）。

常量值描述
QCanvasPainter::TextBaseline::Top0将文本顶部垂直对齐到指定位置。
QCanvasPainter::TextBaseline::Hanging1将文本的悬挂基线垂直对齐到指定位置。
QCanvasPainter::TextBaseline::Middle2将文本的中间位置垂直对齐到指定位置。
QCanvasPainter::TextBaseline::Alphabetic3(默认) 将文本的基线垂直对齐到指定位置。
QCanvasPainter::TextBaseline::Bottom4将文本底部垂直对齐到指定位置。

另请参阅 setTextBaseline() 和fillText()。

enum class QCanvasPainter::TextDirection

TextDirection 用于定义文本的水平对齐方式。

常量值描述
QCanvasPainter::TextDirection::LeftToRight0文本方向为从左到右。
QCanvasPainter::TextDirection::RightToLeft1文本方向为从右到左。
QCanvasPainter::TextDirection::Inherit2（默认）文本方向从QGuiApplication layoutDirection 继承。请参阅 https://doc.qt.io/qt-6/qguiapplication.html#layoutDirection-prop。
QCanvasPainter::TextDirection::Auto3文本方向将根据文本字符串自动检测。参见QString::isRightToLeft()。

注意：由于 这需要分析文本，因此速度可能比其他选项慢。

另请参阅 setTextDirection()、setTextAlign() 以及fillText()。

enum class QCanvasPainter::WrapMode

WrapMode 用于定义文本如何换行。

常量值描述
QCanvasPainter::WrapMode::NoWrap0（默认）不会进行换行。如果文本中换行符不足，则 contentWidth 将超过设定的宽度。
QCanvasPainter::WrapMode::Wrap1如果可能，换行将在单词边界处进行；否则，将在行中的适当位置进行，即使是在单词中间。
QCanvasPainter::WrapMode::WordWrap2仅在单词边界处进行换行。如果单词过长，内容宽度将超过设定的宽度。
QCanvasPainter::WrapMode::WrapAnywhere3换行将在行中的任意位置进行，即使是在单词中间也不例外。

另请参阅 setTextWrapMode() 和fillText()。

成员函数文档

QCanvasPainter::QCanvasPainter()

创建一个绘图器。

[noexcept] QCanvasPainter::~QCanvasPainter()

摧毁了这位画家。

qsizetype QCanvasPainter::activeImageCount() const

返回已注册到此QCanvasPainter 上的活跃QCanvasImage 对象的数量。这还包括为gradients 内部生成的图像。

QCanvasImage 通过注册QCanvasOffscreenCanvas 实例或外部管理的纹理所创建的对象，本函数不予考虑。

另请参阅 activeImageMemoryUsage()、addImage( ) 以及removeImage( )。

qsizetype QCanvasPainter::activeImageMemoryUsage() const

返回该绘图器所有活动QCanvasImage 实例所占用的图像（像素）数据内存的近似值（单位为千字节），这些实例由接受QImage 参数的addImage()重载方法创建。该值还包括gradients 方法内部创建的图像数据。

QCanvasPainter 一旦addImage() 返回，该函数便不会保留 CPU 端QImage 数据的副本。因此，该函数的返回结果是对用于纹理的 GPU 内存大小的近似估计。

注意：该值 仅是基于图像格式和尺寸的估计值。Qt 无法获知纹理数据在 GPU 侧的存储方式及内存布局。

通过其他addImage() 重载函数注册的离屏画布和外部管理的纹理，本函数不会将其纳入计算范围。

对于每个有效的QCanvasImage ，均可通过调用sizeInBytes()查询其具体字节大小。即使QCanvasImage 是由QCanvasOffscreenCanvas 或QRhiTexture 创建的，该函数也能返回有效结果，但它不会考虑Mipmap或多采样数据。

另请参阅 activeImageCount()、addImage() 和removeImage()。

QCanvasImage QCanvasPainter::addImage(const QImage &image, QCanvasPainter::ImageFlags flags = {})

添加image ，其中flags 可供绘图器用作纹理。返回QCanvasImage ，其中包含纹理ID及有关该图像的其他信息。返回的QCanvasImage 随后可用于drawImage 和QCanvasImagePattern 。调用此方法后，无需将image QImage 保存在内存中。

使用相同的image 进行调用是一项开销很小的操作，因为预计会命中缓存。

在优化时需注意，仅调用一次 addImage() 可能并不总是足够，这取决于应用程序的设计。 例如，如果底层图形资源丢失（例如，由于将小部件移动到新的顶级，绘图器在后台与新的QRhi 相关联），则必须调用此函数，以便从image 重新创建本机图形纹理。

另请参阅 drawImage() 和removeImage()。

QCanvasImage QCanvasPainter::addImage(QRhiTexture *texture, QCanvasPainter::ImageFlags flags = {})

添加了texture ，其中flags 可供绘图器作为纹理使用。返回的QCanvasImage 可用于drawImage 和QCanvasImagePattern 。

注意： texture 的所有权不会被转移。

这是一个重载函数。

另请参阅 drawImage() 和removeImage()。

QCanvasImage QCanvasPainter::addImage(const QCanvasOffscreenCanvas &canvas, QCanvasPainter::ImageFlags flags = {})

将canvas 注册为flags ，并将其作为图像提供给绘图器。返回的QCanvasImage 可用于调用drawImage 和QCanvasImagePattern 。

注意： canvas 会继续管理底层原生图形资源，这意味着调用removeImage() 不会导致canvas 失效。

这是一个重载函数。

另请参阅 drawImage() 和removeImage()。

void QCanvasPainter::addPath(const QPainterPath &path)

将path 添加到当前路径中。

注意： QCanvasPainter 默认使用NonZero （Qt::WindingFill ）填充规则，而QPainterPath 默认使用Qt::OddEvenFill 。因此，如有需要，请记得切换填充规则，例如使用setFillRule()。

注意：此 方法主要用于兼容QPainter 和QPainterPath 。与直接使用QCanvasPainter 方法绘制路径相比，它并不会提高性能。

void QCanvasPainter::addPath(const QCanvasPath &path, const QTransform &transform = QTransform())

将path 添加到当前路径中，可选地使用transform 来修改路径节点。当未提供transform （或其值为单位矩阵）时，由于该操作会复用路径数据，因此执行速度非常快。

两个完全相同的绿色圆圈，第二个是第一个的平移副本
// m_path is QCanvasPath
if (m_path.isEmpty())
    m_path.circle(60, 60, 40);
p->beginPath();
p->addPath(m_path);
p->addPath(m_path, QTransform::fromTranslate(80, 80));
p->fill();
p->stroke();

void QCanvasPainter::addPath(const QCanvasPath &path, qsizetype start, qsizetype count, const QTransform &transform = QTransform())

将path 添加到当前路径中，从start 处的命令开始，并包含count 个命令。可选地使用transform 来修改路径指针。系统会检查start 和count 之间的范围，以确保不会访问超过QCanvasPath::commandsSize() 个命令。如果路径不应从当前路径位置继续，请先调用moveTo() 函数，例如使用path.positionAt(start - 1) 。

一条正弦波位于其下方复制的一段较短的相同波形之上
// m_path is QCanvasPath
if (m_path.isEmpty()) {
    m_path.moveTo(20, 60);
    for (int i = 1; i < 160; i++) {
        m_path.lineTo(20 + i,
                      60 + 20 * sin(0.1 * i));
    }
}
p->stroke(m_path);
p->beginPath();
p->addPath(m_path, 20, 100,
           QTransform::fromTranslate(0, 80));
p->stroke();

void QCanvasPainter::arc(qreal centerX, qreal centerY, qreal radius, qreal a0, qreal a1, QCanvasPainter::PathWinding direction = PathWinding::ClockWise, QCanvasPainter::PathConnection connection = PathConnection::Connected)

创建一个新的圆形弧形子路径。该弧的圆心位于centerX ，圆周坐标为centerY ，半径为radius ；绘制角度范围为a0 至a1 ，并沿direction （ClockWise 或CounterClockWise ）方向扫掠。当connection 为NotConnected 时，弧不会从前一个路径位置到弧的起始点添加一条连线。角度以弧度为单位指定。

绿色扇形填满了圆的四分之三，留下一个象限为空
p->beginPath();
p->moveTo(100, 100);
p->arc(100, 100, 80, 0, 1.5 * M_PI);
p->closePath();
p->fill();
p->stroke();

注意：虽然 HTML canvas 2D 绘图环境使用 arc() 绘制圆形，但在QCanvasPainter 中，建议使用circle() 或ellipse() 来绘制圆形。

void QCanvasPainter::arc(QPointF centerPoint, qreal radius, qreal a0, qreal a1, QCanvasPainter::PathWinding direction = PathWinding::ClockWise, QCanvasPainter::PathConnection connection = PathConnection::Connected)

创建一个新的圆形弧形子路径。弧的中心位于centerPoint ，半径为radius ；弧从角度a0 画至a1 ，并沿direction （ClockWise 或CounterClockWise ）进行扫掠。当connection 为NotConnected 时，弧不会从前一个路径位置到弧的起始点添加一条连线。角度以弧度为单位。

注意：虽然 HTML canvas 2D 绘图上下文使用 arc() 绘制圆，但在QCanvasPainter 中，建议使用circle() 或ellipse() 来绘制圆。

这是一个重载函数。

void QCanvasPainter::arcTo(qreal x1, qreal y1, qreal x2, qreal y2, qreal radius)

在由最后一个路径点以及两个指定点（x1 、y1 和x2 、y2 ）确定的拐角处，添加一个弧段，其弧长为radius 。如有必要，该弧段会自动通过一条直线与路径的最新点连接。

一条呈钩状的路径，顶部为水平段，中间是一个大圆弧，末端有一个小卷曲
p->beginPath();
p->moveTo(20, 20);
p->arcTo(240, 20, 20, 220, 50);
p->arcTo(20, 220, 20, 20, 30);
p->stroke();

void QCanvasPainter::arcTo(QPointF controlPoint1, QPointF controlPoint2, qreal radius)

在由最后一个路径点以及两个指定点（controlPoint1 和controlPoint2 ）所定义的拐角处，添加一段弧，其弧长为radius 。如有必要，该弧会自动通过一条直线与路径的最新点相连。

这是一个重载函数。

void QCanvasPainter::beginHoleSubPath()

开始一个孔子路径。这相当于setPathWinding(QCanvasPainter::PathWinding::ClockWise))

一个绿色圆圈，中间有一个方形孔洞，孔洞内有一个较小的实心绿色圆圈
p->beginPath();
p->circle(100, 100, 80);
p->beginHoleSubPath();
p->rect(60, 60, 80, 80);
p->beginSolidSubPath();
p->circle(100, 100, 20);
p->fill();
p->stroke();

另请参阅 beginSolidSubPath()。

void QCanvasPainter::beginPath()

在清除当前路径的同时，开始绘制新路径。

void QCanvasPainter::beginSolidSubPath()

开始一个完整的子路径。这等同于setPathWinding(QCanvasPainter::PathWinding::CounterClockWise))

另请参阅 beginHoleSubPath()。

void QCanvasPainter::bezierCurveTo(qreal cp1X, qreal cp1Y, qreal cp2X, qreal cp2Y, qreal x, qreal y)

从路径的最后一个点出发，通过两个控制点（cp1X 、cp1Y 和cp2X 、cp2Y ），到指定点（x 、y ），添加一个三次贝塞尔曲线段。

平滑的S形立方贝塞尔曲线
p->beginPath();
p->moveTo(20, 20);
p->bezierCurveTo(150, 50, 50, 250, 180, 120);
p->stroke();

void QCanvasPainter::bezierCurveTo(QPointF controlPoint1, QPointF controlPoint2, QPointF endPoint)

从路径的末端点出发，经过两个控制点（controlPoint1 和controlPoint2 ），连接至指定点endPoint ，绘制一段三次贝塞尔曲线。

这是一个重载函数。

void QCanvasPainter::circle(qreal centerX, qreal centerY, qreal radius)

创建一个新的圆形子路径，其中心位于 (centerX,centerY)，半径为radius 。

带深青绿色外框的绿色圆圈
p->beginPath();
p->circle(100, 100, 80);
p->fill();
p->stroke();

void QCanvasPainter::circle(QPointF centerPoint, qreal radius)

创建一个以centerPoint 为圆心、半径为radius 的新圆形子路径。

这是一个重载函数。

void QCanvasPainter::cleanupResources()

该函数会从缓存中移除未使用的纹理。

此外，调用此函数时，其他缓存和资源池可能会被缩减，以尽量减少内存占用。这可能会导致后续的绘制调用开销增加。

void QCanvasPainter::clearRect(qreal x, qreal y, qreal width, qreal height)

通过将由x 、y 、width 、height 指定的矩形区域填充为透明黑色，来清除该区域内的像素。由于清除操作无需进行混合，因此其执行速度可能快于fillRect()。

一个绿色圆圈，顶部被抹去了一个竖向的长方形缺口
p->beginPath();
p->circle(100, 100, 80);
p->fill();
p->stroke();
p->clearRect(60, 0, 80, 120);

void QCanvasPainter::clearRect(const QRectF &rect)

通过将rect 指定的矩形区域填充为透明黑色，来清除该矩形区域内的像素。这是一个重载方法，使用了QRectF 。

这是一个重载函数。

void QCanvasPainter::closePath()

用一条线段闭合当前子路径。这相当于将lineTo([起点])作为最后一个路径元素。

QCanvasOffscreenCanvas QCanvasPainter::createCanvas(QSize pixelSize, int sampleCount = 1, QCanvasOffscreenCanvas::Flags flags = {})

返回一个新的离屏画布，其pixelSize 、sampleCount 和flags 参数均按给定值设置。

画布的大小以像素为单位指定。此后，pixelSize 、sampleCount 和flags 属性均为不可变的。若要获取具有不同大小、采样数或标志的画布，请创建一个新的画布。

若要使用绘制命令针对离屏画布，在使用底层 API 时请调用相应的QCanvasRhiPaintDriver::beginPaint() 重载方法；若使用便捷控件或Qt Quick 项类，则请调用QCanvasPainterWidget::beginCanvasPainting() 或QCanvasPainterItemRenderer::beginCanvasPainting()。

通常在向画布绘制时，画布内容会被清空。若要禁用此行为，请在flags 中传入PreserveContents 。

若要请求对画布进行多采样渲染（多采样抗锯齿，MSAA），请将采样数设置为大于 1 的值，例如 4 或 8。但在启用多采样时，不支持在渲染过程之间保留画布内容，此时PreserveContents 标志将无法生效。

注意： 离屏画布由一个 独立于主渲染目标的纹理作为后端，且对其渲染时始终采用缩放因子（设备像素比）为1。例如，若要创建一个与QCanvasPainterWidget 的实际渲染尺寸相匹配的画布，请将size() * devicePixelRatio() 作为pixelSize 传递，因为控件的size() 仅表示不包含缩放因子的逻辑尺寸。

void QCanvasPainter::destroyCanvas(QCanvasOffscreenCanvas &canvas)

销毁支持 `canvas` 的资源。此时，`canvas ` 将变为 `null canvas `。

绘图器在被销毁时会自动执行此操作。因此，仅当需要立即释放相关资源时，才需要调用此函数。

void QCanvasPainter::drawBoxShadow(const QCanvasBoxShadow &shadow)

绘制一个shadow 的框。阴影将根据shadow 中定义的位置、大小、颜色、模糊等参数进行绘制。调用本方法之前无需先调用beginPath()。

注意：若要 直观地查看 drawBoxShadow() 覆盖的区域，请设置QCPAINTER_DEBUG_SHADOW_RECT 环境变量。

绿色圆角方形，在各侧投射出柔和的灰色盒形阴影
QRectF rect(40, 40, 120, 120);
QRectF shadowRect = rect.translated(-2, 4);
QCanvasBoxShadow shadow(shadowRect);
shadow.setBlur(30);
p->drawBoxShadow(shadow);
p->beginPath();
p->roundRect(rect, 30);
p->setFillStyle("#2CDE85");
p->fill();

另请参阅 QCanvasBoxShadow 。

void QCanvasPainter::drawImage(const QCanvasImage &image, qreal x, qreal y)

将image 以默认大小绘制到x 中，y 。

以默认大小绘制的绿色 Qt 徽标
static QImage logo(":/qt_logo.png");
QCanvasImage image = p->addImage(logo);
p->drawImage(image, 36, 36);

另请参阅 addImage()。

void QCanvasPainter::drawImage(const QCanvasImage &image, const QRectF &destinationRect)

将image 绘制为destinationRect 的位置和大小。

这是一个重载函数。

另请参阅 addImage()。

void QCanvasPainter::drawImage(const QCanvasImage &image, const QRectF &sourceRect, const QRectF &destinationRect)

将image 绘制到destinationRect 的位置和大小，源区域为sourceRect 。

从Qt徽标的源区域中裁剪出的放大版字母Q
static QImage logo(":/qt_logo.png");
QCanvasImage image = p->addImage(logo);
QRectF sourceRect(20, 30, 54, 76);
QRectF destinationRect(0, 0, 200, 200);
p->drawImage(image, sourceRect, destinationRect);

这是一个重载函数。

另请参阅 addImage()。

void QCanvasPainter::drawImage(const QCanvasImage &image, qreal x, qreal y, qreal width, qreal height)

将image 绘制到x ，坐标为y ，在给定的width 和height 处。

将绿色 Qt 徽标拉长以适应自定义的宽度和高度
static QImage logo(":/qt_logo.png");
QCanvasImage image = p->addImage(logo);
p->drawImage(image, 50, 0, 100, 200);

这是一个重载函数。

另请参阅 addImage()。

void QCanvasPainter::ellipse(qreal centerX, qreal centerY, qreal radiusX, qreal radiusY)

创建一个新的椭圆形子路径，其中心位于 (centerX,centerY)，半径分别为radiusX 和radiusY 。

一个宽阔的绿色椭圆形，外围有一圈深青绿色的轮廓线
p->beginPath();
p->ellipse(100, 100, 80, 60);
p->fill();
p->stroke();

void QCanvasPainter::ellipse(const QRectF &rect)

在rect 中创建一个新的椭圆形子路径。该椭圆将覆盖rect 区域。

一个高长的椭圆形轮廓嵌在填充为绿色的矩形内
QRectF rect(40, 20, 120, 160);
p->fillRect(rect);
p->beginPath();
p->ellipse(rect);
p->stroke();

这是一个重载函数。

void QCanvasPainter::ellipse(QPointF centerPoint, qreal radiusX, qreal radiusY)

创建一个新的椭圆形子路径，其中心位于centerPoint ，半径为radiusX ，长度为radiusY 。

这是一个重载函数。

void QCanvasPainter::fill()

使用当前的填充样式和填充规则填充当前路径。

两条绿色条形和一个绿色圆圈融合成一个复合形状
p->beginPath();
p->rect(20, 20, 40, 160);
p->rect(140, 20, 40, 160);
p->circle(100, 100, 60);
p->fill();

另请参阅 setFillStyle() 和setFillRule()。

[since 6.12] void QCanvasPainter::fill(QCanvasPainter::FillRule fillRule)

使用当前填充样式和填充规则fillRule 填充当前路径。

这是一个重载函数。

该函数在 Qt 6.12 中引入。

另请参阅 setFillStyle() 和setFillRule()。

void QCanvasPainter::fill(const QCanvasPath &path, int pathGroup = -1)

使用当前的填充样式和填充规则填充path ，并将其归入pathGroup 。当路径包含更多命令且大部分为静态时，通过QCanvasPath 进行绘制是最佳选择。

当pathGroup 的值为-1 时，路径不会在GPU端被缓存。这是默认行为。若要请求缓存路径数据，请传入一个不小于0 的值。有关路径缓存组的更多信息，请参阅QCanvasPath 文档。

无需在此方法之前调用beginPath()。

一堆宽度各异的实心水平条，排列成沙漏的轮廓
// m_path is QCanvasPath
if (m_path.isEmpty()) {
    for (int i = 0; i < 16; i++) {
        qreal w = 100 + 60 * sin(i);
        m_path.rect(100 - w * 0.5,
                    22 + i * 10,
                    w, 6);
    }
}
p->fill(m_path);

这是一个重载函数。

另请参阅 setFillStyle()、setFillRule() 以及removePathGroup()。

[since 6.12] void QCanvasPainter::fill(const QCanvasPath &path, QCanvasPainter::FillRule fillRule, int pathGroup = -1)

使用当前的填充样式和填充规则填充path fillRule

这是一个重载函数。

该函数在 Qt 6.12 中引入。

void QCanvasPainter::fillRect(qreal x, qreal y, qreal width, qreal height)

在指定位置（x 、y ）绘制一个填充矩形，其大小为width 、height 。

注意：此方法 仅为方便起见。若需填充多个矩形，建议使用rect()。

实心绿色填充正方形
p->fillRect(20, 20, 160, 160);
// The above code does same as:
//  p->beginPath();
//  p->rect(20, 20, 160, 160);
//  p->fill();

void QCanvasPainter::fillRect(const QRectF &rect)

在rect 中绘制一个填充矩形。这是一个使用QRectF 的重载方法。

注意：此方法 仅为方便起见而提供。当需要填充多个矩形时，请优先使用rect()。

这是一个重载函数。

void QCanvasPainter::fillText(const QString &text, qreal x, qreal y, qreal maxWidth = 0)

在指定位置（x ，y ）绘制字符串text ，并使用当前的textAlign和textBaseline。若要使文本换行成多行，请使用setTextWrapMode()将文本换行模式设置为默认值NoWrap 以外的其他选项。可选参数maxWidth 的默认值为0 。这意味着，例如当设置为WordWrap 时，文本将按单词进行换行。 将maxWidth 参数设置为所需的行宽（单位为像素）。

p->setTextAlign(QCanvasPainter::TextAlign::Center);
p->setTextBaseline(QCanvasPainter::TextBaseline::Middle);
QString text("Qt Canvas Painter");
p->fillText(text, 100, 30);
p->setTextWrapMode(QCanvasPainter::WrapMode::WordWrap);
p->fillText(text, 100, 90);
p->fillText(text, 100, 160, 120);

另请参阅 setTextAlign()、setTextBaseline(）和setTextWrapMode()。

void QCanvasPainter::fillText(const QString &text, const QRectF &rect)

使用当前的 textAlign 和 textBaseline，在rect 内绘制text 字符串。rect 参数的宽度将作为 maxWidth 使用。

这是一个使用 `QRectF` 的重载方法。使用此方法绘制文本时，通常将文本基线设置为 `TextBaseline::Top ` 或 `TextBaseline::Middle ` 会非常有用。

p->setTextAlign(QCanvasPainter::TextAlign::Center);
p->setTextBaseline(QCanvasPainter::TextBaseline::Middle);
QString text("Qt Canvas Painter");
QRectF rect1(10, 20, 180, 50);
p->strokeRect(rect1);
p->fillText(text, rect1);
p->setTextWrapMode(QCanvasPainter::WrapMode::WordWrap);
QRectF rect2(60, 90, 80, 90);
p->strokeRect(rect2);
p->fillText(text, rect2);

这是一个重载函数。

另请参阅 setTextAlign()、setTextBaseline() 和setTextWrapMode()。

void QCanvasPainter::fillText(const QString &text, QPointF point, qreal maxWidth = 0)

在指定的point 处绘制text 字符串，并采用当前的textAlign和textBaseline设置。若要使文本折行显示，请使用setTextWrapMode()将文本换行模式设置为默认值NoWrap 以外的其他选项。可选参数maxWidth 的默认值为0 。这意味着，例如当设置为WordWrap 时，文本将按单词进行换行。 将maxWidth 参数设置为所需的行宽（单位为像素）。

这是一个使用QPointF 的重载方法。

这是一个重载函数。

另请参阅 setTextAlign()、setTextBaseline() 以及setTextWrapMode()。

QTransform QCanvasPainter::getTransform() const

返回当前的变换。

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

从路径的最后一点到点 (x,y) 添加一条线段。

两条直线段在一点相交，形成一个拐角
p->beginPath();
p->moveTo(20, 20);
p->lineTo(140, 180);
p->lineTo(180, 120);
p->stroke();

void QCanvasPainter::lineTo(QPointF point)

从路径的末端点到point 添加一条线段。

这是一个重载函数。

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

以 (x,y) 作为起始点，开始一条新的子路径。

void QCanvasPainter::moveTo(QPointF point)

以point 为起始点，开始一个新的子路径。

这是一个重载函数。

void QCanvasPainter::quadraticCurveTo(qreal cpX, qreal cpY, qreal x, qreal y)

从路径的最后一个点出发，经由一个控制点（cpX ，cpY ）到指定点（x ，y ），添加一段二次贝塞尔曲线。

由两条二次曲线构成的尖头绿叶形状
p->beginPath();
p->moveTo(20, 20);
p->quadraticCurveTo(150, 50, 180, 180);
p->quadraticCurveTo(20, 220, 20, 20);
p->fill();
p->stroke();

void QCanvasPainter::quadraticCurveTo(QPointF controlPoint, QPointF endPoint)

从路径的最后一个点出发，通过controlPoint ，添加一条二次贝塞尔曲线段，连接至指定的endPoint 。

这是一个重载函数。

void QCanvasPainter::rect(qreal x, qreal y, qreal width, qreal height)

在坐标x 、y 处创建一个新的矩形子路径，其尺寸为width 、height 。

填充为绿色的正方形，外围有深青绿色的轮廓线
p->beginPath();
p->rect(20, 20, 160, 160);
p->fill();
p->stroke();

void QCanvasPainter::rect(const QRectF &rect)

在坐标rect 处创建一个新的矩形子路径。这是一个重载的方法，使用QRectF 实现。

这是一个重载函数。

void QCanvasPainter::removeImage(const QCanvasImage &image)

释放与image 关联的资源，并将图像从绘图器中移除。

注意： 通常无需调用此函数 ，因为纹理等资源会在画笔类的析构函数中自动释放。当因图像数量过多且其中部分已不再使用而需要减少内存占用时，此函数便十分有用。

注意：已移除的 图像将无法再用于绘制操作。

注意： 使用底层 3D API 创建的纹理等资源 可能不会立即被释放。此类操作可能会被推迟到后续帧中，通常是在当前 `QCanvasPainter ` 提交了当前活动的绘制调用集后重新开始绘制时。

另请参阅 addImage()。

void QCanvasPainter::removePathGroup(int pathGroup)

从绘图器缓存中移除pathGroup 。此后，若对pathGroup 调用fill()或stroke()，将重新生成路径并将其写入组缓存。

注意： 通常无需调用此方法 ，因为路径会在绘图器的析构函数中被移除。仅当不再需要pathGroup 时，或者例如路径中的命令数量远少于以往且需要缩小缓冲区大小时，才应使用此方法来减少内存占用。

另请参阅 fill() 和stroke()。

void QCanvasPainter::reset()

将当前绘图器的状态重置为默认值。

这包括描边和填充样式及相关属性、变换矩阵、裁剪区域、文本相关设置、合成属性、绘制状态堆栈以及抗锯齿设置。

注意：此 方法与 HTML Canvas 2D 上下文的 reset() 方法不同，它不会在视觉上清除画布缓冲区。

注意： setWindingEnforce() 和setHighQualityStroking() 的值不会改变。

一个旋转后的绿色圆角矩形位于一个实心黑色正方形上方，以及一个在重置后绘制的带轮廓的正方形上方
// Adjust the paint state
p->setStrokeStyle("#00414A");
p->setFillStyle("#2CDE85");
p->setLineWidth(10);
QRectF rect(20, 40, 160, 50);
p->translate(rect.center());
p->rotate(qDegreesToRadians(-25));
p->translate(-rect.center());
p->beginPath();
p->roundRect(rect, 20);
p->fill();
p->stroke();
// Reset to default paint state
p->reset();
p->fillRect(20, 140, 60, 40);
p->strokeRect(120, 140, 60, 40);

另请参阅 save() 和restore()。

void QCanvasPainter::resetClipping()

重置并禁用剪裁功能。

另请参阅 setClipRect()。

void QCanvasPainter::resetTransform()

将当前变换重置为单位矩阵。

void QCanvasPainter::restore()

弹出并恢复当前的渲染状态。因此，之前保存的状态将被恢复。如果尚未调用save() 且状态栈为空，调用此方法将不执行任何操作。

另请参阅 save()。

void QCanvasPainter::rotate(qreal angle)

将当前坐标系顺时针旋转angle 。

角度以弧度为单位。请使用qDegreesToRadians()将度转换为弧度。

一个绿色圆角矩形，旋转了45度，上面带有“Cute!”字样，该字样沿矩形边缘旋转
QRectF rect(20, 70, 160, 60);
p->translate(rect.center());
p->rotate(-M_PI / 4);
p->translate(-rect.center());
p->beginPath();
p->roundRect(rect, 10);
p->fill();
p->stroke();
p->setFillStyle(QColorConstants::Black);
p->fillText("Cute!", rect);

void QCanvasPainter::roundRect(qreal x, qreal y, qreal width, qreal height, qreal radius)

在坐标x 、y 处创建一个新的圆角矩形子路径，其尺寸为width 、height 。圆角半径为radius 。

绿色圆角方形，外围有深青绿色轮廓线
p->beginPath();
p->roundRect(20, 20, 160, 160, 30);
p->fill();
p->stroke();

void QCanvasPainter::roundRect(const QRectF &rect, qreal radius)

在rect 处创建一个新的圆角矩形子路径，其顶点坐标为radius 。这是一个重载方法，使用QRectF 实现。

这是一个重载函数。

void QCanvasPainter::roundRect(const QRectF &rect, qreal radiusTopLeft, qreal radiusTopRight, qreal radiusBottomRight, qreal radiusBottomLeft)

在坐标rect 处创建一个新的圆角矩形子路径。每个角的圆角半径可以不同，可使用radiusTopLeft 、radiusTopRight 、radiusBottomRight 、radiusBottomLeft 。

这是一个重载函数。

void QCanvasPainter::roundRect(qreal x, qreal y, qreal width, qreal height, qreal radiusTopLeft, qreal radiusTopRight, qreal radiusBottomRight, qreal radiusBottomLeft)

在坐标x 、y 处创建一个新的圆角矩形子路径，其尺寸为width 、height 。各角的圆角程度可以各不相同，具体参数为radiusTopLeft 、radiusTopRight 、radiusBottomRight 、radiusBottomLeft 。

一个绿色正方形，左上角呈锐角，其余三个角均为圆角，且圆角半径各不相同
p->beginPath();
p->roundRect(20, 20, 160, 160,
             0, 40, 20, 80);
p->fill();
p->stroke();

这是一个重载函数。

void QCanvasPainter::save()

将当前渲染状态压入并保存到状态栈中。必须使用对应的restore()方法来恢复该状态。

两个矩形轮廓，中间夹着一个略微旋转的矩形
p->strokeRect(20, 20, 160, 40);
// Save and adjust the paint state
p->save();
p->setStrokeStyle(QColorConstants::Black);
p->setLineWidth(3);
p->rotate(0.1);
p->strokeRect(20, 80, 180, 20);
// Restore the saved paint state
p->restore();
p->strokeRect(20, 140, 160, 40);

另请参阅 restore()。

void QCanvasPainter::scale(qreal scale)

将当前坐标系按scale 的比例进行缩放。x和y坐标均按相同比例进行缩放。

通过反复缩放，嵌套的正方形轮廓向中心收缩
QRectF rect(20, 20, 160, 160);
for (int i = 0; i < 20; i++) {
    p->beginPath();
    p->roundRect(rect, 10);
    p->stroke();
    p->translate(rect.center());
    p->scale(0.8);
    p->translate(-rect.center());
}

void QCanvasPainter::scale(qreal scaleX, qreal scaleY)

将当前坐标系按scaleX 和scaleY 进行缩放。

这是一个重载函数。

void QCanvasPainter::setAntialias(qreal antialias)

将当前的抗锯齿程度设置为antialias 像素。抗锯齿程度越高，绘制效果越平滑。此设置仅影响填充和描边绘制，不影响图像或文本。默认值为1.0 ，最大值为10.0 。

抗锯齿效果可针对每个路径单独调整，因此可以在每次描边/填充之前进行设置。若要禁用抗锯齿并降低渲染开销，请将抗锯齿值设为0 。

随着抗锯齿程度的提高，一堆波浪线逐渐变得更加柔和、模糊
p->setLineWidth(6);
for (int i = 1; i < 10 ; i++) {
    int y = i * 20;
    p->setAntialias(i);
    p->beginPath();
    p->moveTo(20, y);
    p->bezierCurveTo(80, y + 20, 120,
                     y - 20, 180, y);
    p->stroke();
}

另请参阅 setTextAntialias()。

void QCanvasPainter::setClipRect(qreal x, qreal y, qreal width, qreal height)

将当前剪切矩形设置为 (x,y,width,height)。剪切矩形会根据当前变换进行变换。

注意：裁剪 会带来一定的性能开销，因此应仅在必要时使用。

绿色四分之一圆和文字“Clip me”，被裁剪到一个正方形区域内
QRectF viewArea(20, 20, 160, 160);
p->setClipRect(viewArea);
p->beginPath();
p->circle(40, 40, 110);
p->fill();
p->setFillStyle(Qt::black);
p->fillText("Clip me...", 40, 100);
p->strokeRect(viewArea);

另请参阅 resetClipping()。

void QCanvasPainter::setClipRect(const QRectF &rect)

将当前剪切矩形设置为rect 。剪切矩形将根据当前变换进行变换。

注意：裁剪 会带来一定的性能开销，仅应在必要时使用。

这是一个重载函数。

另请参阅 resetClipping()。

[since 6.12] void QCanvasPainter::setFillRule(QCanvasPainter::FillRule fillRule)

将路径填充规则设置为fillRule 。该值将应用于规则设置后所有对fill()的调用。默认填充规则为QCanvasPainter::FillRule::NonZero

两颗相互重叠的绿色五角星，一颗实心，另一颗中心呈空心状
auto paintStar = [p]() {
    p->beginPath();
    p->moveTo(120, 60);
    for (int i = 1; i < 6; ++i) {
        p->lineTo(60 + 60 * cos(0.8 * i * M_PI),
                  60 + 60 * sin(0.8 * i * M_PI));
    }
    p->fill();
    p->stroke();
};
p->setFillRule(QCanvasPainter::FillRule::NonZero);
paintStar();
p->translate(75, 75);
p->setFillRule(QCanvasPainter::FillRule::EvenOdd);
paintStar();

该函数于 Qt 6.12 中引入。

void QCanvasPainter::setFillStyle(QColor color)

将填充样式设置为纯色color 。默认填充样式为纯黑色（0, 0, 0, 1）。

黑色、深青绿色和绿色的同心填充正方形
p->setFillStyle(QColorConstants::Black);
p->fillRect(20, 20, 160, 160);
p->setFillStyle(QColor(0, 65, 74));
p->fillRect(40, 40, 120, 120);
p->setFillStyle("#2CDE85");
p->fillRect(60, 60, 80, 80);

void QCanvasPainter::setFillStyle(const QCanvasBrush &brush)

将填充样式设置为brush 。默认填充样式为纯黑色（0, 0, 0, 1）。

一个绿色正方形，内部填充径向渐变，边缘逐渐过渡为深青绿色
QCanvasRadialGradient g2(140, 40, 0, 300);
g2.setStartColor(QColor(44, 222, 133));
g2.setEndColor(QColor(0, 65, 74));
p->setFillStyle(g2);
p->fillRect(20, 20, 160, 160);
g2.setCenterPosition(100, 100);
p->setFillStyle(g2);
p->fillRect(40, 40, 120, 120);

这是一个重载函数。

void QCanvasPainter::setFont(const QFont &font)

将font 设置为当前活动字体。

void QCanvasPainter::setGlobalAlpha(qreal alpha)

将全局透明度（alpha）值设置为alpha 。该透明度值将应用于所有渲染的图形。原本已透明的路径也会按比例变得更加透明。透明度值应在0.0（完全透明）和1.0（完全不透明）之间。默认情况下，透明度值为1.0 。

四个 Qt 徽标位于绿色瓷砖上，并沿网格逐渐变淡直至完全透明
static QImage logo(":/qt_logo2.png");
QCanvasImage image = p->addImage(logo);
p->setFillStyle("#d9f720");
for (int i = 0; i < 4; i++) {
    qreal x = 100 * (i % 2);
    qreal y = 100 * (i / 2);
    QRectF rect(x, y, 100, 100);
    p->setGlobalAlpha(1.0 - i * 0.3);
    p->fillRect(rect);
    p->drawImage(image, rect);
}

void QCanvasPainter::setGlobalBrightness(qreal value)

将全局亮度设置为value 。该亮度将应用于所有渲染的图形。值为0时，绘制结果将为纯黑色。该值也可以大于1.0，以提高亮度。默认情况下，亮度为1.0 。

网格上排列着四个 Qt 徽标，它们位于绿色瓷砖上，颜色从明亮逐渐变暗，直至接近黑色
static QImage logo(":/qt_logo2.png");
QCanvasImage image = p->addImage(logo);
p->setFillStyle("#d9f720");
for (int i = 0; i < 4; i++) {
    qreal x = 100 * (i % 2);
    qreal y = 100 * (i / 2);
    QRectF rect(x, y, 100, 100);
    p->setGlobalBrightness(1.5 - i * 0.45);
    p->fillRect(rect);
    p->drawImage(image, rect);
}

void QCanvasPainter::setGlobalCompositeOperation(QCanvasPainter::CompositeOperation operation)

将全局合成操作模式设置为operation 。此模式适用于所有绘制操作。默认模式为QCanvasPainter::CompositeOperation::SourceOver 。

注意：为了 正常工作，合成模式需要启用alphaBlending ，并且画布必须使用透明背景。

QList<QCanvasPainter::CompositeOperation> modes = {
    QCanvasPainter::CompositeOperation::SourceOver,
    QCanvasPainter::CompositeOperation::SourceAtop,
    QCanvasPainter::CompositeOperation::DestinationOut
};
for (int i = 0; i < modes.size(); i++) {
    // First item - SourceOver mode
    p->setGlobalCompositeOperation(QCanvasPainter::CompositeOperation::SourceOver);
    qreal y = 5 + i * 65;
    p->setFillStyle("#D9F720");
    p->fillRect(20, y, 140, 40);
    // Second item - Different modes
    p->setGlobalCompositeOperation(modes[i]);
    p->beginPath();
    p->ellipse(130, y + 30, 60, 25);
    p->setStrokeStyle("#00414A");
    p->setFillStyle("#2CDE85");
    p->fill();
    p->stroke();
}

void QCanvasPainter::setGlobalContrast(qreal value)

将全局对比度设置为value 。此对比度将应用于所有渲染的图形。值为0时，渲染结果将完全呈灰色（0.5, 0.5, 0.5）。该值也可以大于1.0，以提高对比度。默认情况下，对比度为1.0 。

四枚 Qt 徽标印在绿色瓷砖上，颜色从高对比度到褪色的灰色不等
static QImage logo(":/qt_logo2.png");
QCanvasImage image = p->addImage(logo);
p->setFillStyle("#d9f720");
for (int i = 0; i < 4; i++) {
    qreal x = 100 * (i % 2);
    qreal y = 100 * (i / 2);
    QRectF rect(x, y, 100, 100);
    p->setGlobalContrast(1.5 - i * 0.45);
    p->fillRect(rect);
    p->drawImage(image, rect);
}

void QCanvasPainter::setGlobalSaturation(qreal value)

将全局饱和度设置为value 。此饱和度将应用于所有渲染的图形。值为0时将禁用饱和度，导致绘制效果完全为灰度。该值也可以大于1.0，以提高饱和度。默认情况下，饱和度为1.0 。

四个 Qt 徽标位于绿色瓷砖上，在网格中从鲜艳的色彩逐渐过渡为灰度
static QImage logo(":/qt_logo2.png");
QCanvasImage image = p->addImage(logo);
p->setFillStyle("#d9f720");
for (int i = 0; i < 4; i++) {
    qreal x = 100 * (i % 2);
    qreal y = 100 * (i / 2);
    QRectF rect(x, y, 100, 100);
    p->setGlobalSaturation(1.5 - i * 0.5);
    p->fillRect(rect);
    p->drawImage(image, rect);
}

void QCanvasPainter::setHighQualityStroking(bool enabled)

将高质量描边设置为enabled 。在某些不常见的场景下（例如描边重叠且不具备完全不透明度时），将其设置为true 可获得更准确的渲染效果。启用此选项会增加渲染开销。默认值为false 。

// Increase the line width and reduce opacity to get
// the stroking flaws visible.
p->setLineWidth(20);
p->setGlobalAlpha(0.5);
if (m_path.isEmpty()) {
    m_path.moveTo(30, 30);
    m_path.lineTo(40, 30);
    m_path.lineTo(80, 170);
    m_path.lineTo(80, 30);
    m_path.lineTo(70, 30);
}
p->setHighQualityStroking(true);
p->stroke(m_path);
p->setHighQualityStroking(false);
p->translate(90, 0);
p->stroke(m_path);

void QCanvasPainter::setLineCap(QCanvasPainter::LineCap cap)

将笔画的线尾设置为cap 。默认的线端为QCanvasPainter::LineCap::Butt 。

三条水平线，分别展示了平头、方头和圆头线端
QCanvasPath path;
path.moveTo(40, 60);
path.lineTo(160, 60);
p->setLineCap(QCanvasPainter::LineCap::Butt);
p->stroke(path, -1);
p->setLineCap(QCanvasPainter::LineCap::Square);
p->translate(0, 40);
p->stroke(path, -1);
p->setLineCap(QCanvasPainter::LineCap::Round);
p->translate(0, 40);
p->stroke(path, -1);

void QCanvasPainter::setLineJoin(QCanvasPainter::LineJoin join)

将笔画的线段连接方式设置为join 。默认的线段连接方式为QCanvasPainter::LineJoin::Miter 。

三条锯齿形路径，分别展示了斜接、斜切和圆角接合
QCanvasPath path;
path.moveTo(40, 20);
path.lineTo(100, 80);
path.lineTo(160, 40);
path.lineTo(160, 70);
p->setLineJoin(QCanvasPainter::LineJoin::Miter);
p->stroke(path, -1);
p->setLineJoin(QCanvasPainter::LineJoin::Bevel);
p->translate(0, 50);
p->stroke(path, -1);
p->setLineJoin(QCanvasPainter::LineJoin::Round);
p->translate(0, 50);
p->stroke(path, -1);

另请参阅 setMiterLimit()。

void QCanvasPainter::setLineWidth(qreal width)

将笔画的线宽设置为width 像素。默认线宽为1.0 。当启用抗锯齿时，小于1像素的线宽会自动降低不透明度，从而生成平滑的输出效果。

一堆用逐渐增粗的线宽绘制的波浪形曲线
for (int i = 1; i < 10 ; i++) {
    int y = i * 20;
    p->setLineWidth(0.5 * i);
    p->beginPath();
    p->moveTo(20, y);
    p->bezierCurveTo(80, y + 20, 120,
                     y - 20, 180, y);
    p->stroke();
}

另请参阅 stroke()。

void QCanvasPainter::setMiterLimit(qreal limit)

将斜切限制设置为limit 。斜切限制用于控制何时对锐角进行倒角。当角的长度超过此限制时，两条线之间将应用QCanvasPainter::LineJoin::Bevel 。此设置仅在采用QCanvasPainter::LineJoin::Miter 线段连接方式时生效。默认限制为10.0 。

QCanvasPath path;
path.moveTo(20, 40);
path.lineTo(30, 130);
path.lineTo(40, 40);
path.lineTo(55, 80);

p->setLineJoin(QCanvasPainter::LineJoin::Miter);
p->setMiterLimit(20);
p->stroke(path);

p->setMiterLimit(8);
p->translate(65, 0);
p->stroke(path);

p->setMiterLimit(2);
p->translate(65, 0);
p->stroke(path);

另请参阅 setLineJoin()。

void QCanvasPainter::setPathWinding(QCanvasPainter::PathWinding winding)

将当前子路径winding 设置为CounterClockWise （默认）或ClockWise 。CounterClockWise 绘制实心子路径，而ClockWise 绘制孔洞。

绿色圆角方形，上面有一个小圆圈，还有一个矩形被冲压成孔
p->beginPath();
p->roundRect(20, 20, 160, 160, 40);
p->setPathWinding(QCanvasPainter::PathWinding::ClockWise);
p->circle(140, 60, 20);
p->rect(60, 120, 80, 30);
p->fill();
p->stroke();

另请参阅 beginHoleSubPath() 和beginSolidSubPath()。

void QCanvasPainter::setStrokeStyle(QColor color)

将描边样式设置为实线color 。默认描边样式为黑色实线（0, 0, 0, 1）。

三个嵌套的方形轮廓，颜色分别为黑色、深青绿色和绿色
p->setStrokeStyle(QColorConstants::Black);
p->strokeRect(20, 20, 160, 160);
p->setStrokeStyle(QColor(0, 65, 74));
p->strokeRect(40, 40, 120, 120);
p->setStrokeStyle("#2CDE85");
p->strokeRect(60, 60, 80, 80);

void QCanvasPainter::setStrokeStyle(const QCanvasBrush &brush)

将描边样式设置为brush 。默认描边样式为实心黑色（0, 0, 0, 1）。

两个嵌套的方形轮廓，分别带有从绿色到黑色以及从绿色到黄色的对角线渐变
QCanvasLinearGradient g1(180, 20, 20, 180);
g1.setStartColor(QColor(44, 222, 133));
g1.setEndColor(Qt::black);
p->setStrokeStyle(g1);
p->strokeRect(20, 20, 160, 160);
g1.setEndColor(Qt::yellow);
p->setStrokeStyle(g1);
p->strokeRect(40, 40, 120, 120);

这是一个重载函数。

void QCanvasPainter::setTextAlign(QCanvasPainter::TextAlign align)

将文本的水平对齐方式设置为align 。默认对齐方式为QCanvasPainter::TextAlign::Start 。

标签“左”、“中”、“右”、“起始”和“结束”围绕一条垂直参考线排列
QFont font("Titillium Web", 22);
p->setFont(font);
p->fillRect(100, 0, 1, 200);
p->setTextAlign(QCanvasPainter::TextAlign::Left);
p->fillText("Left", 100, 40);
p->setTextAlign(QCanvasPainter::TextAlign::Center);
p->fillText("Center", 100, 70);
p->setTextAlign(QCanvasPainter::TextAlign::Right);
p->fillText("Right", 100, 100);
p->setTextAlign(QCanvasPainter::TextAlign::Start);
p->fillText("Start", 100, 130);
p->setTextAlign(QCanvasPainter::TextAlign::End);
p->fillText("End", 100, 160);

另请参阅 setTextBaseline()。

void QCanvasPainter::setTextAntialias(qreal antialias)

设置当前文本的抗锯齿强度。数值antialias 是常规抗锯齿效果的倍数，这意味着0.0 将禁用抗锯齿，而2.0则将其效果加倍。默认值为1.0。

注意：由于 所采用的文本抗锯齿技术（SDF），最大抗锯齿程度相当有限，且在字体尺寸较小时，其影响较小。

标有“抗锯齿 1.0 至 4.0”的线条逐渐变得越来越柔和、越来越模糊
QFont font("Titillium Web", 20);
p->setFont(font);
p->setTextAntialias(1.0);
p->fillText("Antialiasing: 1.0", 100, 25);
p->setTextAntialias(2.0);
p->fillText("Antialiasing: 2.0", 100, 75);
p->setTextAntialias(3.0);
p->fillText("Antialiasing: 3.0", 100, 125);
p->setTextAntialias(4.0);
p->fillText("Antialiasing: 4.0", 100, 175);

void QCanvasPainter::setTextBaseline(QCanvasPainter::TextBaseline baseline)

将文本的垂直对齐方式（基线）设置为baseline 。默认对齐方式为QCanvasPainter::TextBaseline::Alphabetic 。

标签“底部”、“中间”、“顶部”、“按字母顺序”和“悬挂”对齐于水平基线
QFont font("Titillium Web", 16);
p->setFont(font);
p->fillRect(0, 60, 200, 1);
p->fillRect(0, 140, 200, 1);
p->setTextBaseline(QCanvasPainter::TextBaseline::Bottom);
p->fillText("Bottom", 40, 60);
p->setTextBaseline(QCanvasPainter::TextBaseline::Middle);
p->fillText("Middle", 100, 60);
p->setTextBaseline(QCanvasPainter::TextBaseline::Top);
p->fillText("Top", 160, 60);
p->setTextBaseline(QCanvasPainter::TextBaseline::Alphabetic);
p->fillText("Alphabetic", 50, 140);
p->setTextBaseline(QCanvasPainter::TextBaseline::Hanging);
p->fillText("Hanging", 150, 140);

另请参阅 setTextAlign()。

void QCanvasPainter::setTextDirection(QCanvasPainter::TextDirection direction)

将文本方向设置为direction 。默认方向为QCanvasPainter::TextDirection::Inherit 。

p->setTextAlign(QCanvasPainter::TextAlign::Center);
p->setTextBaseline(QCanvasPainter::TextBaseline::Middle);
QFont font("Titillium Web", 32);
p->setFont(font);
p->setFillStyle(QColorConstants::Black);
p->fillText("Hi!", 100, 50);
p->setTextDirection(QCanvasPainter::TextDirection::RightToLeft);
p->fillText("Hi!", 100, 150);

void QCanvasPainter::setTextLineHeight(qreal height)

将换行文本的行高调整值（以像素为单位）设置为height 。默认行高为0 。

三个框中各有一行文本，分别显示行高为 -10、0 和 10 像素
QRectF r1(40, 5, 120, 60);
QRectF r2(40, 70, 120, 60);
QRectF r3(40, 135, 120, 60);
p->strokeRect(r1);
p->strokeRect(r2);
p->strokeRect(r3);
p->setTextLineHeight(-10);
p->fillText("Text with line height: -10", r1);
p->setTextLineHeight(0);
p->fillText("Text with line height: 0", r2);
p->setTextLineHeight(10);
p->fillText("Text with line height: 10", r3);

void QCanvasPainter::setTextWrapMode(QCanvasPainter::WrapMode wrapMode)

将文本换行模式设置为wrapMode 。默认换行模式为QCanvasPainter::WrapMode::NoWrap 。

同一条字符串在“不换行”、“自动换行”和“任意换行”这三个复选框中的显示效果
QRectF r1(50, 5, 100, 60);
QRectF r2(50, 70, 100, 60);
QRectF r3(50, 135, 100, 60);
p->strokeRect(r1);
p->strokeRect(r2);
p->strokeRect(r3);
QString s("This is a long string.");
p->setTextWrapMode(QCanvasPainter::WrapMode::NoWrap);
p->fillText(s, r1);
p->setTextWrapMode(QCanvasPainter::WrapMode::Wrap);
p->fillText(s, r2);
p->setTextWrapMode(QCanvasPainter::WrapMode::WrapAnywhere);
p->fillText(s, r3);

void QCanvasPainter::setTransform(const QTransform &transform)

重置当前的变换，并改用transform 。

一个较小的绿色圆角正方形位于一个较大、经过旋转和缩放的圆角正方形上方
p->beginPath();
p->roundRect(80, 20, 40, 40, 10);
p->fill();
p->stroke();
QTransform t;
t.translate(100, 20);
t.rotate(45);
t.scale(2.0, 2.0);
p->setTransform(t);
p->beginPath();
p->roundRect(20, 20, 40, 40, 10);
p->fill();
p->stroke();

另请参阅 transform()。

void QCanvasPainter::setWindingEnforce(bool enabled)

将路径缠绕强制规则设置为enabled 。若将其设置为false ，则禁用路径缠绕强制规则，使其与setPathWinding()中设定的规则一致。禁用该功能可实现诸如通过按顺时针顺序添加点来在路径中创建孔洞等操作。禁用该功能还可提升性能。默认值为true 。

p->setWindingEnforce(false);
p->beginPath();
// Outer shape, counterclockwise
p->moveTo(20, 20);
p->lineTo(100, 180);
p->lineTo(180, 20);
p->closePath();
// Inner shape, clockwise
p->moveTo(100, 40);
p->lineTo(125, 90);
p->lineTo(75, 90);
p->closePath();
p->fill();
p->stroke();

void QCanvasPainter::skew(qreal angleX, qreal angleY = 0.0)

将当前坐标系沿 X 轴以angleX 进行平移，沿 Y 轴以angleY 进行平移。角度以弧度为单位。

一个绿色的圆角矩形，上面写着“Cute!”，被拉伸成一个平行四边形
QRectF rect(40, 70, 120, 60);
p->translate(rect.center());
p->skew(-0.6);
p->translate(-rect.center());
p->beginPath();
p->roundRect(rect, 10);
p->fill();
p->stroke();
p->setFillStyle(QColorConstants::Black);
p->fillText("Cute!", rect);

void QCanvasPainter::stroke()

使用当前的笔画样式绘制当前路径。

两条垂直条形轮廓，中间重叠着一个圆形轮廓
p->beginPath();
p->rect(20, 20, 40, 160);
p->rect(140, 20, 40, 160);
p->circle(100, 100, 60);
p->stroke();

另请参阅 setStrokeStyle()。

void QCanvasPainter::stroke(const QCanvasPath &path, int pathGroup = -1)

使用当前的描边样式对path 进行描边，并将其归入pathGroup 。当路径包含较多命令且基本保持静态时，通过QCanvasPath 进行描边是最佳选择。

当 `pathGroup ` 为 `-1` 时，路径的渲染相关数据将不会被缓存。这是默认行为。若要请求缓存路径数据，请传入一个大于或等于 `0` 的值。有关使用路径缓存组的更多信息，请参阅QCanvasPath 文档。

无需在此方法之前调用beginPath()。

一排高度各异的窄长垂直条形轮廓
// m_path is QCanvasPath
if (m_path.isEmpty()) {
    for (int i = 0; i < 16; i++) {
        int h = 100 + 60 * sin(i);
        m_path.rect(22 + i * 10,
                    180 - h,
                    6, h);
    }
}
p->stroke(m_path);

这是一个重载函数。

另请参阅 setStrokeStyle() 和removePathGroup()。

void QCanvasPainter::strokeRect(qreal x, qreal y, qreal width, qreal height)

在指定位置（x 、y ）绘制一个带描边的矩形，其大小为width 、height 。

注意：此功能 仅为方便起见。当需要绘制多个矩形时，建议使用rect()。

深青绿色方形轮廓
p->strokeRect(20, 20, 160, 160);
// The above code does same as:
// p->beginPath();
// p->rect(20, 20, 160, 160);
// p->stroke();

void QCanvasPainter::strokeRect(const QRectF &rect)

在rect 中绘制一个带描边的矩形。这是一个使用QRectF 的重载方法。

注意：此方法 仅为方便起见而提供。当需要绘制多个矩形时，建议使用rect()。

这是一个重载函数。

QRectF QCanvasPainter::textBoundingBox(const QString &text, qreal x, qreal y, qreal maxWidth = 0) const

测量text 字符串在(x,y)处的边界框。

若要测量多行文本，请使用 `setTextWrapMode()` 将文本换行模式设置为默认值 `NoWrap` 以外的其他选项。同时，将可选参数 `maxWidth ` 设置为首选的行宽（单位为像素）。

返回QRectF ，其值为[xmin, ymin, width, height]。测量值以本地坐标系为基准返回。

使用 Qt 生成的文本，一行显示，并折行显示为两行，每行均位于其测量的边界框内
QString s("Built with Qt");
QPointF pos1(20, 20);
QRectF box1 = p->textBoundingBox(s, pos1);
p->strokeRect(box1);
p->fillText(s, pos1);
p->setTextWrapMode(QCanvasPainter::WrapMode::WordWrap);
p->setTextAlign(QCanvasPainter::TextAlign::Center);
QPointF pos2(100, 80);
QRectF box2 = p->textBoundingBox(s, pos2, 100);
p->strokeRect(box2);
p->fillText(s, pos2, 100);

QRectF QCanvasPainter::textBoundingBox(const QString &text, const QRectF &rect) const

测量位于rect 的text 字符串的边界框。返回QRectF ，其中包含 [xmin, ymin, width, height] 这四个值。测量值以本地坐标系为基准返回。

这是一个重载函数。

QRectF QCanvasPainter::textBoundingBox(const QString &text, QPointF point, qreal maxWidth = 0) const

测量位于point 处的text 字符串的边界框。

若要测量多行文本，请使用setTextWrapMode() 将文本换行模式设置为与默认值NoWrap 不同的选项。同时，将可选参数maxWidth 设置为首选的行宽（单位为像素）。

返回QRectF ，其值为 [xmin, ymin, width, height]。测量值以本地坐标系为基准返回。

这是一个重载函数。

void QCanvasPainter::transform(const QTransform &transform)

将当前坐标系乘以指定的transform 。

十根绿色的圆形条形，通过围绕中心反复旋转，排列成一个环形
QTransform t;
t.translate(100, 100);
t.rotate(36);
t.translate(-100, -100);
for (int i = 0; i < 10; i++) {
    p->transform(t);
    p->beginPath();
    p->roundRect(80, 15, 40, 20, 10);
    p->fill();
    p->stroke();
}

另请参阅 setTransform()。

void QCanvasPainter::translate(qreal x, qreal y)

将当前坐标系按x 和y 进行变换。

两个完全相同的绿色圆角矩形，下方的那个向下平移了一段距离
auto paintRect = [p]() {
    p->beginPath();
    p->roundRect(20, 20, 160, 60, 10);
    p->fill();
    p->stroke();
};
paintRect();
p->translate(0, 100);
paintRect();

void QCanvasPainter::translate(QPointF point)

将当前坐标系沿point 方向平移。

这是一个重载函数。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.