QPainterPath露

PyQt5.QtGui.QPainterPath

Description露

The QPainterPath class provides a container for painting operations, enabling graphical shapes to be constructed and reused.

A painter path is an object composed of a number of graphical building blocks, such as rectangles, ellipses, lines, and curves. Building blocks can be joined in closed subpaths, for example as a rectangle or an ellipse. A closed path has coinciding start and end points. Or they can exist independently as unclosed subpaths, such as lines and curves.

A QPainterPath object can be used for filling, outlining, and clipping. To generate fillable outlines for a given painter path, use the QPainterPathStroker class. The main advantage of painter paths over normal drawing operations is that complex shapes only need to be created once; then they can be drawn many times using only calls to the drawPath() function.

QPainterPath provides a collection of functions that can be used to obtain information about the path and its elements. In addition it is possible to reverse the order of the elements using the toReversed() function. There are also several functions to convert this painter path object into a polygon representation.

Composing a QPainterPath露

A QPainterPath object can be constructed as an empty path, with a given start point, or as a copy of another QPainterPath object. Once created, lines and curves can be added to the path using the lineTo(), arcTo(), cubicTo() and quadTo() functions. The lines and curves stretch from the currentPosition() to the position passed as argument.

The currentPosition() of the QPainterPath object is always the end position of the last subpath that was added (or the initial start point). Use the moveTo() function to move the currentPosition() without adding a component. The moveTo() function implicitly starts a new subpath, and closes the previous one. Another way of starting a new subpath is to call the closeSubpath() function which closes the current path by adding a line from the currentPosition() back to the path鈥檚 start position. Note that the new path will have (0, 0) as its initial currentPosition().

QPainterPath class also provides several convenience functions to add closed subpaths to a painter path: addEllipse(), addPath(), addRect(), addRegion() and addText(). The addPolygon() function adds an unclosed subpath. In fact, these functions are all collections of moveTo(), lineTo() and cubicTo() operations.

In addition, a path can be added to the current path using the connectPath() function. But note that this function will connect the last element of the current path to the first element of given one by adding a line.

Below is a code snippet that shows how a QPainterPath object can be used:

image-qpainterpath-construction-png

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

The painter path is initially empty when constructed. We first add a rectangle, which is a closed subpath. Then we add two bezier curves which together form a closed subpath even though they are not closed individually. Finally we draw the entire path. The path is filled using the default fill rule, OddEvenFill. Qt provides two methods for filling paths:

OddEvenFill	WindingFill

See the FillRule documentation for the definition of the rules. A painter path鈥檚 currently set fill rule can be retrieved using the fillRule() function, and altered using the setFillRule() function.

QPainterPath Information露

The QPainterPath class provides a collection of functions that returns information about the path and its elements.

The currentPosition() function returns the end point of the last subpath that was added (or the initial start point). The elementAt() function can be used to retrieve the various subpath elements, the number of elements can be retrieved using the elementCount() function, and the isEmpty() function tells whether this QPainterPath object contains any elements at all.

The controlPointRect() function returns the rectangle containing all the points and control points in this path. This function is significantly faster to compute than the exact boundingRect() which returns the bounding rectangle of this painter path with floating point precision.

Finally, QPainterPath provides the contains() function which can be used to determine whether a given point or rectangle is inside the path, and the intersects() function which determines if any of the points inside a given rectangle also are inside this path.

QPainterPath Conversion露

For compatibility reasons, it might be required to simplify the representation of a painter path: QPainterPath provides the toFillPolygon(), toFillPolygons() and toSubpathPolygons() functions which convert the painter path into a polygon. The toFillPolygon() returns the painter path as one single polygon, while the two latter functions return a list of polygons.

The toFillPolygons() and toSubpathPolygons() functions are provided because it is usually faster to draw several small polygons than to draw one large polygon, even though the total number of points drawn is the same. The difference between the two is the number of polygons they return: The toSubpathPolygons() creates one polygon for each subpath regardless of intersecting subpaths (i.e. overlapping bounding rectangles), while the toFillPolygons() functions creates only one polygon for overlapping subpaths.

The toFillPolygon() and toFillPolygons() functions first convert all the subpaths to polygons, then uses a rewinding technique to make sure that overlapping subpaths can be filled using the correct fill rule. Note that rewinding inserts additional lines in the polygon so the outline of the fill polygon does not match the outline of the path.

Examples露

Qt provides the Painter Paths Example and the Vector Deformation example which are located in Qt鈥檚 example directory.

The Painter Paths Example shows how painter paths can be used to build complex shapes for rendering and lets the user experiment with the filling and stroking. The Vector Deformation Example shows how to use QPainterPath to draw text.

Painter Paths Example	Vector Deformation Example

Classes露

Element

Enums露

ElementType

This enum describes the types of elements used to connect vertices in subpaths.

Note that elements added as closed subpaths using the addEllipse(), addPath(), addPolygon(), addRect(), addRegion() and addText() convenience functions, is actually added to the path as a collection of separate elements using the moveTo(), lineTo() and cubicTo() functions.

See also

elementAt(), elementCount().

Member	Value	Description
CurveToDataElement	3	The extra data required to describe a curve in a element.
CurveToElement	2	A curve. See also cubicTo() and quadTo().
LineToElement	1	A line. See also lineTo().
MoveToElement	0	A new subpath. See also moveTo().

Methods露

__init__(): TODO

__init__(Union[QPointF, QPoint]): TODO

__init__(QPainterPath): TODO

__add__(QPainterPath) → QPainterPath: TODO

addEllipse(QRectF): TODO

addEllipse(Union[QPointF, QPoint], float, float): TODO

addEllipse(float, float, float, float): TODO

addPath(QPainterPath): TODO

addPolygon(QPolygonF): TODO

addRect(QRectF): TODO

addRect(float, float, float, float): TODO

addRegion(QRegion): TODO

addRoundedRect(QRectF, float, float, mode: SizeMode = AbsoluteSize)

Adds the given rectangle rect with rounded corners to the path.

The xRadius and yRadius arguments specify the radii of the ellipses defining the corners of the rounded rectangle. When mode is RelativeSize, xRadius and yRadius are specified in percentage of half the rectangle鈥檚 width and height respectively, and should be in the range 0.0 to 100.0.

See also

addRect().

addRoundedRect(float, float, float, float, float, float, mode: SizeMode = AbsoluteSize): TODO

addText(Union[QPointF, QPoint], QFont, str): TODO

addText(float, float, QFont, str): TODO

__and__(QPainterPath) → QPainterPath: TODO

angleAtPercent(float) → float

Returns the angle of the path tangent at the percentage t. The argument t has to be between 0 and 1.

Positive values for the angles mean counter-clockwise while negative values mean the clockwise direction. Zero degrees is at the 3 o鈥檆lock position.

Note that similarly to the other percent methods, the percentage measurement is not linear with regards to the length if curves are present in the path. When curves are present the percentage argument is mapped to the t parameter of the Bezier equations.

arcMoveTo(QRectF, float): TODO

arcMoveTo(float, float, float, float, float): TODO

arcTo(QRectF, float, float): TODO

arcTo(float, float, float, float, float, float): TODO

boundingRect() → QRectF: TODO

capacity() → int: TODO

clear(): TODO

closeSubpath(): TODO

connectPath(QPainterPath): TODO

contains(Union[QPointF, QPoint]) → bool: TODO

contains(QRectF) → bool: TODO

contains(QPainterPath) → bool

Returns true if the given path p is contained within the current path. Returns false if any edges of the current path and p intersect.

Set operations on paths will treat the paths as areas. Non-closed paths will be treated as implicitly closed.

See also

intersects().

controlPointRect() → QRectF: TODO

cubicTo(Union[QPointF, QPoint], Union[QPointF, QPoint], Union[QPointF, QPoint]): TODO

cubicTo(float, float, float, float, float, float): TODO

currentPosition() → QPointF: TODO

elementAt(int) → Element: TODO

elementCount() → int: TODO

__eq__(QPainterPath) → bool: TODO

fillRule() → FillRule: See also

setFillRule().

__iadd__(QPainterPath) → QPainterPath: TODO

__iand__(QPainterPath) → QPainterPath: TODO

intersected(QPainterPath) → QPainterPath: Returns a path which is the intersection of this path鈥檚 fill area and p鈥檚 fill area. Bezier curves may be flattened to line segments due to numerical instability of doing bezier curve intersections.

intersects(QRectF) → bool: TODO

intersects(QPainterPath) → bool

Returns true if the current path intersects at any point the given path p. Also returns true if the current path contains or is contained by any part of p.

Set operations on paths will treat the paths as areas. Non-closed paths will be treated as implicitly closed.

See also

contains().

__ior__(QPainterPath) → QPainterPath: TODO

isEmpty() → bool: TODO

__isub__(QPainterPath) → QPainterPath: TODO

length() → float: Returns the length of the current path.

lineTo(Union[QPointF, QPoint]): TODO

lineTo(float, float): TODO

moveTo(Union[QPointF, QPoint]): TODO

moveTo(float, float): TODO

__mul__(QTransform) → QPainterPath: TODO

__ne__(QPainterPath) → bool: TODO

__or__(QPainterPath) → QPainterPath: TODO

percentAtLength(float) → float

Returns percentage of the whole path at the specified length len.

Note that similarly to other percent methods, the percentage measurement is not linear with regards to the length, if curves are present in the path. When curves are present the percentage argument is mapped to the t parameter of the Bezier equations.

pointAtPercent(float) → QPointF

Returns the point at at the percentage t of the current path. The argument t has to be between 0 and 1.

Note that similarly to other percent methods, the percentage measurement is not linear with regards to the length, if curves are present in the path. When curves are present the percentage argument is mapped to the t parameter of the Bezier equations.

quadTo(Union[QPointF, QPoint], Union[QPointF, QPoint]): TODO

quadTo(float, float, float, float): TODO

reserve(int): TODO

setElementPositionAt(int, float, float): TODO

setFillRule(FillRule): See also

fillRule().

simplified() → QPainterPath: Returns a simplified version of this path. This implies merging all subpaths that intersect, and returning a path containing no intersecting edges. Consecutive parallel lines will also be merged. The simplified path will always use the default fill rule, OddEvenFill. Bezier curves may be flattened to line segments due to numerical instability of doing bezier curve intersections.

slopeAtPercent(float) → float

Returns the slope of the path at the percentage t. The argument t has to be between 0 and 1.

Note that similarly to other percent methods, the percentage measurement is not linear with regards to the length, if curves are present in the path. When curves are present the percentage argument is mapped to the t parameter of the Bezier equations.

__sub__(QPainterPath) → QPainterPath: TODO

subtracted(QPainterPath) → QPainterPath

Returns a path which is p鈥檚 fill area subtracted from this path鈥檚 fill area.

Set operations on paths will treat the paths as areas. Non-closed paths will be treated as implicitly closed. Bezier curves may be flattened to line segments due to numerical instability of doing bezier curve intersections.

swap(QPainterPath): TODO

toFillPolygon() → QPolygonF: TODO

toFillPolygon(QTransform) → QPolygonF

Converts the path into a polygon using the QTransform matrix, and returns the polygon.

The polygon is created by first converting all subpaths to polygons, then using a rewinding technique to make sure that overlapping subpaths can be filled using the correct fill rule.

Note that rewinding inserts addition lines in the polygon so the outline of the fill polygon does not match the outline of the path.

See also

toSubpathPolygons(), toFillPolygons(), QPainterPath Conversion.

toFillPolygons() → List[QPolygonF]: TODO

toFillPolygons(QTransform) → List[QPolygonF]: TODO

toReversed() → QPainterPath: TODO

toSubpathPolygons() → List[QPolygonF]: TODO

toSubpathPolygons(QTransform) → List[QPolygonF]: TODO

translate(Union[QPointF, QPoint]): TODO

translate(float, float): Translates all elements in the path by (dx, dy).

See also

translated().

translated(Union[QPointF, QPoint]) → QPainterPath: TODO

translated(float, float) → QPainterPath: Returns a copy of the path that is translated by (dx, dy).

See also

translate().

united(QPainterPath) → QPainterPath

Returns a path which is the union of this path鈥檚 fill area and p鈥檚 fill area.

Set operations on paths will treat the paths as areas. Non-closed paths will be treated as implicitly closed. Bezier curves may be flattened to line segments due to numerical instability of doing bezier curve intersections.

See also

intersected(), subtracted().