QPainter Class

The QPainter class performs low-level painting on widgets and other paint devices. More…

List of all members, including inherited members

Public Types

Public Functions

Detailed Description

A painter draws shapes and images on a QPaintDevice, such as a QImage or a window, using its pen, brush and clipping:

QImage image(100, 60, QImage::Format_ARGB32_Premultiplied);
image.fill(Qt::white);
QPainter painter(&image);
painter.setPen(QPen(Qt::darkBlue, 2));
painter.setBrush(Qt::yellow);
painter.drawRect(10, 10, 80, 40);

The painter begins when it is constructed with a device, or when begin() is called, and ends in the destructor or at end(). Only one painter can paint on a device at a time.

Paths, Transformations and Antialiasing

Shapes with real coordinates, paths, polygons, arcs, pies and chords are drawn through the transformation of the painter (translate(), scale(), rotate(), shear(), setTransform()), with the cap, join and dash styles of the pen and the gradients of the brush. With the Antialiasing render hint their edges are smooth:

QPainterPath petal;
petal.moveTo(0, 0);
petal.cubicTo(30, -40, 90, -40, 120, 0);
petal.cubicTo(90, 40, 30, 40, 0, 0);

painter.setRenderHint(QPainter::Antialiasing);
painter.translate(size.width() / 2, size.height() / 2);
painter.scale(size.height() / 300, size.height() / 300);
painter.rotate(phase);
for (int i = 0; i < 12; ++i) {
    QRadialGradient shade(QPointF(60, 0), 60);
    shade.setColorAt(0, QColor::fromHsv(i * 30, 160, 255));
    shade.setColorAt(1, QColor::fromHsv(i * 30, 255, 170));
    painter.setPen(QPen(QColor(60, 30, 60), 1.5));
    painter.setBrush(shade);
    painter.drawPath(petal);
    painter.rotate(30);
}
painter.setBrush(QColor(250, 210, 60));
painter.drawEllipse(QPointF(0, 0), 22, 22);

Shapes with integer coordinates, drawn without antialiasing and with no transformation other than a translation by whole pixels, are drawn on whole pixels as before: a rectangle of width 10 with a pen of width 1 covers 11 pixels.

See also QPaintDevice, QPaintEngine, QPen, QBrush and QImage.

Differences from Qt

Member Type Documentation

enum QPainter::CompositionMode

This enum describes how drawn pixels combine with the pixels below them.

enum QPainter::RenderHint

This enum describes optional drawing quality settings. The RenderHints type is a typedef for QFlags<RenderHint>.

typedef QPainter::RenderHints

The RenderHints type is a typedef for QFlags<RenderHint>. It stores an OR combination of RenderHint values.

Member Function Documentation

QPainter::QPainter()

Constructs a painter that is not active.

See also begin().

[explicit] QPainter::QPainter(QPaintDevice *device)

Constructs a painter that paints on device, as begin() does.

QPainter::~QPainter()

Destroys the painter, ending painting if it is active.

bool QPainter::begin(QPaintDevice *device)

Begins painting on device and returns true on success. It fails and returns false if the painter is already active, if device is null, already has a painter, or has no paint engine that can paint on it.

See also end() and isActive().

QRect QPainter::boundingRect(const QRect &rectangle, int flags, const QString &text)

Returns the rectangle that drawText() covers for text in rectangle with the given flags, using the current font.

QRect QPainter::boundingRect(int x, int y, int w, int h, int flags, const QString &text)

This is an overloaded function.

Returns the rectangle that drawText() covers for text in the rectangle at (x, y) of w by h.

const QBrush & QPainter::brush() const

Returns the current brush.

QRegion QPainter::clipRegion() const

Returns the clip region in the current coordinate system, or an empty region if clipping is off.

See also setClipRegion().

QTransform QPainter::combinedTransform() const

Returns the transformation of the coordinate system; there is no window or viewport in Nt.

CompositionMode QPainter::compositionMode() const

Returns the composition mode.

QPaintDevice * QPainter::device() const

Returns the device the painter paints on, or nullptr.

QTransform QPainter::deviceTransform() const

Returns the transformation from the painter's coordinates to device pixels: the transformation of the coordinate system, the redirection of the device, and its device pixel ratio.

void QPainter::drawArc(const QRectF &rectangle, int startAngle, int spanAngle)

Draws the arc of the ellipse that fits in rectangle, from startAngle for spanAngle, both in sixteenths of a degree, counterclockwise from 3 o'clock. The pen draws it; the brush is not used.

void QPainter::drawArc(const QRect &rectangle, int startAngle, int spanAngle)

This is an overloaded function.

Draws the arc of the ellipse in rectangle from startAngle for spanAngle sixteenths of a degree.

void QPainter::drawArc(int x, int y, int width, int height, int startAngle, int spanAngle)

This is an overloaded function.

Draws the arc of the ellipse in the rectangle at (x, y) of width by height, from startAngle for spanAngle sixteenths of a degree.

void QPainter::drawChord(const QRectF &rectangle, int startAngle, int spanAngle)

Draws the chord of the ellipse that fits in rectangle, from startAngle for spanAngle, in sixteenths of a degree: the arc closed by a straight line, filled with the brush.

void QPainter::drawChord(const QRect &rectangle, int startAngle, int spanAngle)

This is an overloaded function.

Draws the chord of the ellipse in rectangle from startAngle for spanAngle.

void QPainter::drawChord(int x, int y, int width, int height, int startAngle, int spanAngle)

This is an overloaded function.

Draws the chord of the ellipse in the rectangle at (x, y) of width by height, from startAngle for spanAngle.

void QPainter::drawConvexPolygon(const QPointF *points, int pointCount)

Draws the convex polygon of the pointCount points in points.

void QPainter::drawConvexPolygon(const QPoint *points, int pointCount)

This is an overloaded function.

Draws the convex polygon of the pointCount points in points.

void QPainter::drawConvexPolygon(const QPolygonF &polygon)

This is an overloaded function.

Draws the convex polygon.

void QPainter::drawConvexPolygon(const QPolygon &polygon)

This is an overloaded function.

Draws the convex polygon.

void QPainter::drawEllipse(const QRectF &rect)

This is an overloaded function.

Draws the ellipse that fits in rect, through the transformation.

void QPainter::drawEllipse(const QPointF &center, qreal rx, qreal ry)

This is an overloaded function.

Draws the ellipse at center with the radii rx and ry.

void QPainter::drawEllipse(const QPoint &center, int rx, int ry)

This is an overloaded function.

Draws the ellipse at center with the radii rx and ry.

void QPainter::drawEllipse(const QRect &rect)

Draws the ellipse that fits in rect, outlined with the current pen and filled with the current brush.

void QPainter::drawEllipse(int x, int y, int width, int height)

This is an overloaded function.

Draws the ellipse in the rectangle at (x, y) of width by height.

void QPainter::drawImage(const QPointF &point, const QImage &image)

This is an overloaded function.

Draws image with its top left at point, through the transformation.

void QPainter::drawImage(const QRectF &target, const QImage &image, const QRectF &source = QRectF())

This is an overloaded function.

Draws the part source of image, or all of it if source is null, scaled to fill target. Under a transformation that rotates or shears, the image fills the bounding rectangle of the transformed target.

void QPainter::drawImage(const QPoint &point, const QImage &image)

Draws image with its top left at point.

void QPainter::drawImage(int x, int y, const QImage &image)

This is an overloaded function.

Draws image with its top left at (x, y).

void QPainter::drawImage(const QRect &target, const QImage &image, const QRect &source = QRect())

This is an overloaded function.

Draws the part source of image, scaled to fill target. A null source stands for the whole image. Scaling picks the nearest pixel.

void QPainter::drawImage(const QPoint &point, const QImage &image, const QRect &source)

This is an overloaded function.

Draws the part source of image with its top left at point, without scaling.

void QPainter::drawLine(const QLineF &line)

This is an overloaded function.

Draws line with the current pen, through the transformation.

void QPainter::drawLine(const QPointF &p1, const QPointF &p2)

This is an overloaded function.

Draws a line from p1 to p2.

void QPainter::drawLine(const QLine &line)

Draws line with the current pen.

void QPainter::drawLine(const QPoint &p1, const QPoint &p2)

This is an overloaded function.

Draws a line from p1 to p2.

void QPainter::drawLine(int x1, int y1, int x2, int y2)

This is an overloaded function.

Draws a line from (x1, y1) to (x2, y2).

void QPainter::drawLines(const QLineF *lines, int lineCount)

Draws the lineCount lines in lines.

void QPainter::drawLines(const QLine *lines, int lineCount)

This is an overloaded function.

Draws the lineCount lines in lines.

void QPainter::drawLines(const QList<QLineF> &lines)

This is an overloaded function.

Draws lines.

void QPainter::drawLines(const QList<QLine> &lines)

This is an overloaded function.

Draws lines.

void QPainter::drawPath(const QPainterPath &path)

Fills path with the current brush and strokes it with the current pen, through the transformation. With the Antialiasing render hint, edges are smooth.

See also fillPath(), strokePath() and setRenderHint().

void QPainter::drawPie(const QRectF &rectangle, int startAngle, int spanAngle)

Draws the pie of the ellipse that fits in rectangle, from startAngle for spanAngle, in sixteenths of a degree: the arc and the lines to the center, filled with the brush.

void QPainter::drawPie(const QRect &rectangle, int startAngle, int spanAngle)

This is an overloaded function.

Draws the pie of the ellipse in rectangle from startAngle for spanAngle.

void QPainter::drawPie(int x, int y, int width, int height, int startAngle, int spanAngle)

This is an overloaded function.

Draws the pie of the ellipse in the rectangle at (x, y) of width by height, from startAngle for spanAngle.

void QPainter::drawPixmap(const QPointF &point, const QPixmap &pixmap)

This is an overloaded function.

Draws pixmap with its top left at point.

void QPainter::drawPixmap(const QRectF &target, const QPixmap &pixmap, const QRectF &source)

This is an overloaded function.

Draws the part source of pixmap scaled to fill target.

void QPainter::drawPixmap(const QPoint &point, const QPixmap &pixmap)

Draws pixmap with its top left corner at point.

void QPainter::drawPixmap(int x, int y, const QPixmap &pixmap)

This is an overloaded function.

Draws pixmap with its top left corner at x, y.

void QPainter::drawPixmap(const QRect &target, const QPixmap &pixmap, const QRect &source = QRect())

This is an overloaded function.

Draws the part source of pixmap, or all of it if source is null, scaled to fill target.

void QPainter::drawPixmap(int x, int y, int width, int height, const QPixmap &pixmap)

This is an overloaded function.

Draws pixmap scaled to the rectangle at x, y of width by height.

void QPainter::drawPoint(const QPointF &point)

This is an overloaded function.

Draws point as a dot the width of the pen: round with Qt::RoundCap, square otherwise.

void QPainter::drawPoint(const QPoint &point)

Draws point with the current pen.

void QPainter::drawPoint(int x, int y)

This is an overloaded function.

Draws the point (x, y).

void QPainter::drawPoints(const QPointF *points, int pointCount)

Draws the pointCount points in points.

void QPainter::drawPoints(const QPoint *points, int pointCount)

This is an overloaded function.

Draws the pointCount points in points.

void QPainter::drawPoints(const QPolygonF &points)

This is an overloaded function.

Draws points.

void QPainter::drawPoints(const QPolygon &points)

This is an overloaded function.

Draws points.

void QPainter::drawPolygon(const QPointF *points, int pointCount, Qt::FillRule fillRule = Qt::OddEvenFill)

Draws the polygon of the pointCount points in points, closed, filled with the brush by fillRule and outlined with the pen.

void QPainter::drawPolygon(const QPoint *points, int pointCount, Qt::FillRule fillRule = Qt::OddEvenFill)

This is an overloaded function.

Draws the polygon of the pointCount points in points, filled by fillRule.

void QPainter::drawPolygon(const QPolygonF &points, Qt::FillRule fillRule = Qt::OddEvenFill)

This is an overloaded function.

Draws the polygon points, filled by fillRule.

void QPainter::drawPolygon(const QPolygon &points, Qt::FillRule fillRule = Qt::OddEvenFill)

This is an overloaded function.

Draws the polygon points, filled by fillRule.

void QPainter::drawPolyline(const QPointF *points, int pointCount)

Draws the open line through the pointCount points in points.

void QPainter::drawPolyline(const QPoint *points, int pointCount)

This is an overloaded function.

Draws the open line through the pointCount points in points.

void QPainter::drawPolyline(const QPolygonF &polyline)

This is an overloaded function.

Draws polyline.

void QPainter::drawPolyline(const QPolygon &polyline)

This is an overloaded function.

Draws polyline.

void QPainter::drawRect(const QRectF &rect)

This is an overloaded function.

Draws rect, filled with the brush and outlined with the pen, through the transformation.

void QPainter::drawRect(const QRect &rect)

Draws rect, outlined with the current pen and filled with the current brush. With a pen of width 1 the outline covers one pixel more to the right and below than the width and height of rect.

void QPainter::drawRect(int x, int y, int width, int height)

This is an overloaded function.

Draws the rectangle at (x, y) of width by height.

void QPainter::drawRects(const QRectF *rects, int rectCount)

Draws the rectCount rectangles in rects.

void QPainter::drawRects(const QRect *rects, int rectCount)

This is an overloaded function.

Draws the rectCount rectangles in rects.

void QPainter::drawRects(const QList<QRectF> &rects)

This is an overloaded function.

Draws rects.

void QPainter::drawRects(const QList<QRect> &rects)

This is an overloaded function.

Draws rects.

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

Draws rect with corners rounded by xRadius and yRadius, in units or, with mode Qt::RelativeSize, in percent of half the width and height.

void QPainter::drawRoundedRect(int x, int y, int w, int h, qreal xRadius, qreal yRadius, Qt::SizeMode mode = Qt::AbsoluteSize)

This is an overloaded function.

Draws the rectangle at (x, y) of w by h with corners rounded by xRadius and yRadius in the given mode.

void QPainter::drawRoundedRect(const QRect &rect, qreal xRadius, qreal yRadius, Qt::SizeMode mode = Qt::AbsoluteSize)

This is an overloaded function.

Draws rect with corners rounded by xRadius and yRadius in the given mode.

void QPainter::drawText(const QPointF &position, const QString &text)

This is an overloaded function.

Draws text with the left end of its baseline at position, mapped by the transformation. The glyphs are drawn upright at the size of the font: the transformation moves the text but does not rotate or scale it.

void QPainter::drawText(const QRectF &rectangle, int flags, const QString &text, QRectF *boundingRect = nullptr)

This is an overloaded function.

Draws text in rectangle with flags, as the QRect version does. If boundingRect is not nullptr, it receives the rectangle that the text covers.

void QPainter::drawText(const QPoint &position, const QString &text)

Draws text with the current font and pen. position is the left end of the baseline of the first line. Each new line in text starts a line below the one before.

See also setFont() and QFontMetrics.

void QPainter::drawText(int x, int y, const QString &text)

This is an overloaded function.

Draws text with the left end of the baseline at (x, y).

void QPainter::drawText(const QRect &rectangle, int flags, const QString &text, QRect *boundingRect = nullptr)

This is an overloaded function.

Draws text in rectangle. The flags are Qt::AlignmentFlag values (left, right, centered, top, bottom) and Qt::TextFlag values (word wrap, single line, no clipping). Text is clipped to the rectangle unless Qt::TextDontClip is set. If boundingRect is not nullptr, it receives the rectangle that the text covers.

See also QFontMetrics::boundingRect().

void QPainter::drawText(int x, int y, int width, int height, int flags, const QString &text, QRect *boundingRect = nullptr)

This is an overloaded function.

Draws text in the rectangle at (x, y) of width by height.

bool QPainter::end()

Ends painting and returns true if the painter was active.

See also begin().

void QPainter::eraseRect(const QRect &rect)

Erases rect: it becomes transparent, or black on an image without alpha.

void QPainter::eraseRect(const QRectF &rect)

This is an overloaded function.

Erases rect: it becomes transparent, or black on an image without alpha.

void QPainter::fillPath(const QPainterPath &path, const QBrush &brush)

Fills path with brush, without an outline.

void QPainter::fillRect(const QRect &rect, const QBrush &brush)

Fills rect with brush, leaving the pen and the current brush alone.

void QPainter::fillRect(const QRect &rect, const QColor &color)

This is an overloaded function.

Fills rect with the solid color.

void QPainter::fillRect(const QRect &rect, Qt::GlobalColor color)

This is an overloaded function.

Fills rect with the solid color.

void QPainter::fillRect(const QRect &rect, Qt::BrushStyle style)

This is an overloaded function.

Fills rect with a black brush of the given style; nothing is drawn for Qt::NoBrush.

void QPainter::fillRect(int x, int y, int width, int height, const QBrush &brush)

This is an overloaded function.

Fills the rectangle at (x, y) of width by height with brush.

void QPainter::fillRect(int x, int y, int width, int height, const QColor &color)

This is an overloaded function.

Fills the rectangle at (x, y) of width by height with color.

void QPainter::fillRect(int x, int y, int width, int height, Qt::GlobalColor color)

This is an overloaded function.

Fills the rectangle at (x, y) of width by height with color.

void QPainter::fillRect(int x, int y, int width, int height, Qt::BrushStyle style)

This is an overloaded function.

Fills the rectangle at (x, y) of width by height with a black brush of the given style.

void QPainter::fillRect(const QRectF &rect, const QBrush &brush)

This is an overloaded function.

Fills rect with brush, leaving the pen and the current brush alone.

void QPainter::fillRect(const QRectF &rect, const QColor &color)

This is an overloaded function.

Fills rect with color.

void QPainter::fillRect(const QRectF &rect, Qt::GlobalColor color)

This is an overloaded function.

Fills rect with color.

const QFont & QPainter::font() const

Returns the current font.

See also setFont().

bool QPainter::hasClipping() const

Returns true if clipping is on.

See also setClipping().

bool QPainter::isActive() const

Returns true if the painter is painting.

qreal QPainter::opacity() const

Returns the opacity.

QPaintEngine * QPainter::paintEngine() const

Returns the paint engine that the painter uses, or nullptr.

const QPen & QPainter::pen() const

Returns the current pen.

RenderHints QPainter::renderHints() const

Returns the render hints that are on.

void QPainter::resetTransform()

Makes the transformation the identity.

void QPainter::restore()

Restores the state that save() stored last. Does nothing if nothing was saved.

See also save().

void QPainter::rotate(qreal angle)

Rotates the coordinate system clockwise by angle degrees.

void QPainter::save()

Saves the state of the painter (pen, brush, opacity, font, translation, clipping and composition mode) on a stack.

See also restore().

void QPainter::scale(qreal sx, qreal sy)

Scales the coordinate system by sx horizontally and sy vertically.

void QPainter::setBrush(const QBrush &brush)

Sets the brush to brush.

See also brush() and setPen().

void QPainter::setBrush(Qt::BrushStyle style)

This is an overloaded function.

Sets a black brush with the given style.

void QPainter::setClipping(bool enable)

Turns clipping on or off according to enable.

See also hasClipping().

void QPainter::setClipRect(const QRect &rect)

Sets the clip to rect, given in the current coordinate system, and turns clipping on.

See also setClipRegion() and setClipping().

void QPainter::setClipRect(int x, int y, int width, int height)

This is an overloaded function.

Sets the clip to the rectangle at (x, y) that is width by height pixels.

void QPainter::setClipRegion(const QRegion &region)

Sets the clip to region, given in the current coordinate system, and turns clipping on. An empty region clips everything.

See also setClipRect() and clipRegion().

void QPainter::setCompositionMode(CompositionMode mode)

Sets the composition mode to mode.

See also compositionMode().

void QPainter::setFont(const QFont &font)

Sets the font used by drawText() to font.

See also font().

void QPainter::setOpacity(qreal opacity)

Sets the opacity of everything drawn afterwards to opacity, from 0.0 (transparent) to 1.0 (opaque). Values outside the range are clamped.

See also opacity().

void QPainter::setPen(const QPen &pen)

Sets the pen to pen.

See also pen() and setBrush().

void QPainter::setPen(const QColor &color)

This is an overloaded function.

Sets a solid pen of one pixel with the given color.

void QPainter::setPen(Qt::PenStyle style)

This is an overloaded function.

Sets a black pen with the given style.

void QPainter::setRenderHint(RenderHint hint, bool on = true)

Sets hint on if on is true and off otherwise. The hints are stored and have no effect.

See also renderHints().

void QPainter::setRenderHints(RenderHints hints, bool on = true)

Sets the render hints in hints on if on is true and off otherwise.

See also setRenderHint().

void QPainter::setTransform(const QTransform &transform, bool combine = false)

Sets the transformation of the coordinate system to transform, or to transform followed by the current one if combine is true.

void QPainter::setWorldMatrixEnabled(bool enabled)

Uses the transformation if enabled is true, the default, and ignores it otherwise.

void QPainter::setWorldTransform(const QTransform &matrix, bool combine = false)

Sets the transformation to matrix, combined with the current one if combine is true, as setTransform() does.

void QPainter::shear(qreal sh, qreal sv)

Shears the coordinate system by sh horizontally and sv vertically.

void QPainter::strokePath(const QPainterPath &path, const QPen &pen)

Draws the outline of path with pen, without filling it.

const QTransform & QPainter::transform() const

Returns the transformation of the coordinate system.

void QPainter::translate(const QPoint &offset)

Moves the origin of the coordinate system by offset.

See also translation() and resetTransform().

void QPainter::translate(const QPointF &offset)

This is an overloaded function.

Moves the origin of the coordinate system by offset.

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

This is an overloaded function.

Moves the origin by dx and dy.

QPoint QPainter::translation() const

Returns the translation of the transformation, rounded to whole pixels.

bool QPainter::worldMatrixEnabled() const

Returns true if the transformation is used; otherwise returns false.

const QTransform & QPainter::worldTransform() const

Returns the transformation of the coordinate system.