JUCE  v5.1.1-3-g1a0b28c73
JUCE API
Path Class Reference

A path is a sequence of lines and curves that may either form a closed shape or be open-ended. More...

#include <juce_Path.h>

Collaboration diagram for Path:

Classes

class  Iterator
 Iterates the lines and curves that a path contains. More...
 
struct  PathBounds
 

Public Member Functions

 Path ()
 Creates an empty path. More...
 
 Path (const Path &)
 Creates a copy of another path. More...
 
 Path (Path &&) noexcept
 Move constructor. More...
 
 ~Path ()
 Destructor. More...
 
void addArc (float x, float y, float width, float height, float fromRadians, float toRadians, bool startAsNewSubPath=false)
 Adds an elliptical arc to the current path. More...
 
void addArrow (const Line< float > &line, float lineThickness, float arrowheadWidth, float arrowheadLength)
 Adds a line with an arrowhead on the end. More...
 
void addBubble (const Rectangle< float > &bodyArea, const Rectangle< float > &maximumArea, const Point< float > arrowTipPosition, const float cornerSize, const float arrowBaseWidth)
 Adds a speech-bubble shape to the path. More...
 
void addCentredArc (float centreX, float centreY, float radiusX, float radiusY, float rotationOfEllipse, float fromRadians, float toRadians, bool startAsNewSubPath=false)
 Adds an arc which is centred at a given point, and can have a rotation specified. More...
 
void addEllipse (float x, float y, float width, float height)
 Adds an ellipse to the path. More...
 
void addEllipse (Rectangle< float > area)
 Adds an ellipse to the path. More...
 
void addLineSegment (const Line< float > &line, float lineThickness)
 Adds a line with a specified thickness. More...
 
void addPath (const Path &pathToAppend)
 Adds another path to this one. More...
 
void addPath (const Path &pathToAppend, const AffineTransform &transformToApply)
 Adds another path to this one, transforming it on the way in. More...
 
void addPieSegment (float x, float y, float width, float height, float fromRadians, float toRadians, float innerCircleProportionalSize)
 Adds a "pie-chart" shape to the path. More...
 
void addPieSegment (Rectangle< float > segmentBounds, float fromRadians, float toRadians, float innerCircleProportionalSize)
 Adds a "pie-chart" shape to the path. More...
 
void addPolygon (const Point< float > centre, int numberOfSides, float radius, float startAngle=0.0f)
 Adds a polygon shape to the path. More...
 
void addQuadrilateral (float x1, float y1, float x2, float y2, float x3, float y3, float x4, float y4)
 Adds a quadrilateral to the path. More...
 
void addRectangle (float x, float y, float width, float height)
 Adds a rectangle to the path. More...
 
template<typename ValueType >
void addRectangle (const Rectangle< ValueType > &rectangle)
 Adds a rectangle to the path. More...
 
void addRoundedRectangle (float x, float y, float width, float height, float cornerSize)
 Adds a rectangle with rounded corners to the path. More...
 
void addRoundedRectangle (float x, float y, float width, float height, float cornerSizeX, float cornerSizeY)
 Adds a rectangle with rounded corners to the path. More...
 
void addRoundedRectangle (float x, float y, float width, float height, float cornerSizeX, float cornerSizeY, bool curveTopLeft, bool curveTopRight, bool curveBottomLeft, bool curveBottomRight)
 Adds a rectangle with rounded corners to the path. More...
 
template<typename ValueType >
void addRoundedRectangle (const Rectangle< ValueType > &rectangle, float cornerSizeX, float cornerSizeY)
 Adds a rectangle with rounded corners to the path. More...
 
template<typename ValueType >
void addRoundedRectangle (const Rectangle< ValueType > &rectangle, float cornerSize)
 Adds a rectangle with rounded corners to the path. More...
 
void addStar (const Point< float > centre, int numberOfPoints, float innerRadius, float outerRadius, float startAngle=0.0f)
 Adds a star shape to the path. More...
 
void addTriangle (float x1, float y1, float x2, float y2, float x3, float y3)
 Adds a triangle to the path. More...
 
void addTriangle (Point< float > point1, Point< float > point2, Point< float > point3)
 Adds a triangle to the path. More...
 
void applyTransform (const AffineTransform &transform) noexcept
 Applies a 2D transform to all the vertices in the path. More...
 
void clear () noexcept
 Removes all lines and curves, resetting the path completely. More...
 
void closeSubPath ()
 Closes a the current sub-path with a line back to its start-point. More...
 
bool contains (float x, float y, float tolerance=defaultToleranceForTesting) const
 Checks whether a point lies within the path. More...
 
bool contains (const Point< float > point, float tolerance=defaultToleranceForTesting) const
 Checks whether a point lies within the path. More...
 
Path createPathWithRoundedCorners (float cornerRadius) const
 Creates a version of this path where all sharp corners have been replaced by curves. More...
 
void cubicTo (float controlPoint1X, float controlPoint1Y, float controlPoint2X, float controlPoint2Y, float endPointX, float endPointY)
 Adds a cubic bezier curve from the shape's last position to a new position. More...
 
void cubicTo (const Point< float > controlPoint1, const Point< float > controlPoint2, const Point< float > endPoint)
 Adds a cubic bezier curve from the shape's last position to a new position. More...
 
Rectangle< float > getBounds () const noexcept
 Returns the smallest rectangle that contains all points within the path. More...
 
Rectangle< float > getBoundsTransformed (const AffineTransform &transform) const noexcept
 Returns the smallest rectangle that contains all points within the path after it's been transformed with the given tranasform matrix. More...
 
Line< float > getClippedLine (Line< float > line, bool keepSectionOutsidePath) const
 Cuts off parts of a line to keep the parts that are either inside or outside this path. More...
 
Point< float > getCurrentPosition () const
 Returns the last point that was added to the path by one of the drawing methods. More...
 
float getLength (const AffineTransform &transform=AffineTransform(), float tolerance=defaultToleranceForMeasurement) const
 Returns the length of the path. More...
 
float getNearestPoint (Point< float > targetPoint, Point< float > &pointOnPath, const AffineTransform &transform=AffineTransform(), float tolerance=defaultToleranceForMeasurement) const
 Finds the point along the path which is nearest to a given position. More...
 
Point< float > getPointAlongPath (float distanceFromStart, const AffineTransform &transform=AffineTransform(), float tolerance=defaultToleranceForMeasurement) const
 Returns a point that is the specified distance along the path. More...
 
AffineTransform getTransformToScaleToFit (float x, float y, float width, float height, bool preserveProportions, Justification justificationType=Justification::centred) const
 Returns a transform that can be used to rescale the path to fit into a given space. More...
 
AffineTransform getTransformToScaleToFit (const Rectangle< float > &area, bool preserveProportions, Justification justificationType=Justification::centred) const
 Returns a transform that can be used to rescale the path to fit into a given space. More...
 
bool intersectsLine (Line< float > line, float tolerance=defaultToleranceForTesting)
 Checks whether a line crosses the path. More...
 
bool isEmpty () const noexcept
 Returns true if the path doesn't contain any lines or curves. More...
 
bool isUsingNonZeroWinding () const
 Returns the flag that indicates whether the path should use a non-zero winding rule. More...
 
void lineTo (float endX, float endY)
 Adds a line from the shape's last position to a new end-point. More...
 
void lineTo (const Point< float > end)
 Adds a line from the shape's last position to a new end-point. More...
 
void loadPathFromData (const void *data, size_t numberOfBytes)
 Loads a stored path from a block of data. More...
 
void loadPathFromStream (InputStream &source)
 Loads a stored path from a data stream. More...
 
bool operator!= (const Path &) const noexcept
 
Pathoperator= (const Path &)
 Copies this path from another one. More...
 
Pathoperator= (Path &&) noexcept
 Move assignment operator. More...
 
bool operator== (const Path &) const noexcept
 
void preallocateSpace (int numExtraCoordsToMakeSpaceFor)
 Preallocates enough space for adding the given number of coordinates to the path. More...
 
void quadraticTo (float controlPointX, float controlPointY, float endPointX, float endPointY)
 Adds a quadratic bezier curve from the shape's last position to a new position. More...
 
void quadraticTo (const Point< float > controlPoint, const Point< float > endPoint)
 Adds a quadratic bezier curve from the shape's last position to a new position. More...
 
void restoreFromString (StringRef stringVersion)
 Restores this path from a string that was created with the toString() method. More...
 
void scaleToFit (float x, float y, float width, float height, bool preserveProportions) noexcept
 Rescales this path to make it fit neatly into a given space. More...
 
void setUsingNonZeroWinding (bool isNonZeroWinding) noexcept
 Changes the winding-rule to be used when filling the path. More...
 
void startNewSubPath (float startX, float startY)
 Begins a new subpath with a given starting position. More...
 
void startNewSubPath (const Point< float > start)
 Begins a new subpath with a given starting position. More...
 
void swapWithPath (Path &) noexcept
 Swaps the contents of this path with another one. More...
 
String toString () const
 Creates a string containing a textual representation of this path. More...
 
void writePathToStream (OutputStream &destination) const
 Stores the path by writing it out to a stream. More...
 

Static Public Attributes

static const float defaultToleranceForMeasurement
 
static const float defaultToleranceForTesting
 

Private Attributes

PathBounds bounds
 
ArrayAllocationBase< float, DummyCriticalSectiondata
 
size_t numElements = 0
 
bool useNonZeroWinding = true
 

Static Private Attributes

static const float closeSubPathMarker
 
static const float cubicMarker
 
static const float lineMarker
 
static const float moveMarker
 
static const float quadMarker
 

Friends

class Path::Iterator
 
class PathFlatteningIterator
 

Detailed Description

A path is a sequence of lines and curves that may either form a closed shape or be open-ended.

To use a path, you can create an empty one, then add lines and curves to it to create shapes, then it can be rendered by a Graphics context or used for geometric operations.

e.g.

Path myPath;
myPath.startNewSubPath (10.0f, 10.0f); // move the current position to (10, 10)
myPath.lineTo (100.0f, 200.0f); // draw a line from here to (100, 200)
myPath.quadraticTo (0.0f, 150.0f, 5.0f, 50.0f); // draw a curve that ends at (5, 50)
myPath.closeSubPath(); // close the subpath with a line back to (10, 10)
// add an ellipse as well, which will form a second sub-path within the path..
myPath.addEllipse (50.0f, 50.0f, 40.0f, 30.0f);
// double the width of the whole thing..
myPath.applyTransform (AffineTransform::scale (2.0f, 1.0f));
// and draw it to a graphics context with a 5-pixel thick outline.
g.strokePath (myPath, PathStrokeType (5.0f));

A path object can actually contain multiple sub-paths, which may themselves be open or closed.

See also
PathFlatteningIterator, PathStrokeType, Graphics

Constructor & Destructor Documentation

◆ Path() [1/3]

Path::Path ( )

Creates an empty path.

◆ Path() [2/3]

Path::Path ( const Path )

Creates a copy of another path.

◆ ~Path()

Path::~Path ( )

Destructor.

◆ Path() [3/3]

Path::Path ( Path &&  )
noexcept

Move constructor.

Member Function Documentation

◆ addArc()

void Path::addArc ( float  x,
float  y,
float  width,
float  height,
float  fromRadians,
float  toRadians,
bool  startAsNewSubPath = false 
)

Adds an elliptical arc to the current path.

Note that when specifying the start and end angles, the curve will be drawn either clockwise or anti-clockwise according to whether the end angle is greater than the start. This means that sometimes you may need to use values greater than 2*Pi for the end angle.

Parameters
xthe left-hand edge of the rectangle in which the elliptical outline fits
ythe top edge of the rectangle in which the elliptical outline fits
widththe width of the rectangle in which the elliptical outline fits
heightthe height of the rectangle in which the elliptical outline fits
fromRadiansthe angle (clockwise) in radians at which to start the arc segment (where 0 is the top-centre of the ellipse)
toRadiansthe angle (clockwise) in radians at which to end the arc segment (where 0 is the top-centre of the ellipse). This angle can be greater than 2*Pi, so for example to draw a curve clockwise from the 9 o'clock position to the 3 o'clock position via 12 o'clock, you'd use 1.5*Pi and 2.5*Pi as the start and finish points.
startAsNewSubPathif true, the arc will begin a new subpath from its starting point; if false, it will be added to the current sub-path, continuing from the current postition
See also
addCentredArc, arcTo, addPieSegment, addEllipse

◆ addArrow()

void Path::addArrow ( const Line< float > &  line,
float  lineThickness,
float  arrowheadWidth,
float  arrowheadLength 
)

Adds a line with an arrowhead on the end.

The arrow is added as a new closed sub-path. (Any currently open paths will be left open).

See also
PathStrokeType::createStrokeWithArrowheads

◆ addBubble()

void Path::addBubble ( const Rectangle< float > &  bodyArea,
const Rectangle< float > &  maximumArea,
const Point< float >  arrowTipPosition,
const float  cornerSize,
const float  arrowBaseWidth 
)

Adds a speech-bubble shape to the path.

Parameters
bodyAreathe area of the body of the bubble shape
maximumAreaan area which encloses the body area and defines the limits within which the arrow tip can be drawn - if the tip lies outside this area, the bubble will be drawn without an arrow
arrowTipPositionthe location of the tip of the arrow
cornerSizethe size of the rounded corners
arrowBaseWidththe width of the base of the arrow where it joins the main rectangle

◆ addCentredArc()

void Path::addCentredArc ( float  centreX,
float  centreY,
float  radiusX,
float  radiusY,
float  rotationOfEllipse,
float  fromRadians,
float  toRadians,
bool  startAsNewSubPath = false 
)

Adds an arc which is centred at a given point, and can have a rotation specified.

Note that when specifying the start and end angles, the curve will be drawn either clockwise or anti-clockwise according to whether the end angle is greater than the start. This means that sometimes you may need to use values greater than 2*Pi for the end angle.

Parameters
centreXthe centre x of the ellipse
centreYthe centre y of the ellipse
radiusXthe horizontal radius of the ellipse
radiusYthe vertical radius of the ellipse
rotationOfEllipsean angle by which the whole ellipse should be rotated about its centre, in radians (clockwise)
fromRadiansthe angle (clockwise) in radians at which to start the arc segment (where 0 is the top-centre of the ellipse)
toRadiansthe angle (clockwise) in radians at which to end the arc segment (where 0 is the top-centre of the ellipse). This angle can be greater than 2*Pi, so for example to draw a curve clockwise from the 9 o'clock position to the 3 o'clock position via 12 o'clock, you'd use 1.5*Pi and 2.5*Pi as the start and finish points.
startAsNewSubPathif true, the arc will begin a new subpath from its starting point; if false, it will be added to the current sub-path, continuing from the current postition
See also
addArc, arcTo

◆ addEllipse() [1/2]

void Path::addEllipse ( float  x,
float  y,
float  width,
float  height 
)

Adds an ellipse to the path.

The shape is added as a new sub-path. (Any currently open paths will be left open).

See also
addArc

◆ addEllipse() [2/2]

void Path::addEllipse ( Rectangle< float >  area)

Adds an ellipse to the path.

The shape is added as a new sub-path. (Any currently open paths will be left open).

See also
addArc

◆ addLineSegment()

void Path::addLineSegment ( const Line< float > &  line,
float  lineThickness 
)

Adds a line with a specified thickness.

The line is added as a new closed sub-path. (Any currently open paths will be left open).

See also
addArrow

Referenced by RenderingHelpers::SavedStateBase< SoftwareRendererSavedState >::drawLine().

◆ addPath() [1/2]

void Path::addPath ( const Path pathToAppend)

Adds another path to this one.

The new path is added as a new sub-path. (Any currently open paths in this path will be left open).

Parameters
pathToAppendthe path to add

◆ addPath() [2/2]

void Path::addPath ( const Path pathToAppend,
const AffineTransform transformToApply 
)

Adds another path to this one, transforming it on the way in.

The new path is added as a new sub-path, its points being transformed by the given matrix before being added.

Parameters
pathToAppendthe path to add
transformToApplyan optional transform to apply to the incoming vertices

◆ addPieSegment() [1/2]

void Path::addPieSegment ( float  x,
float  y,
float  width,
float  height,
float  fromRadians,
float  toRadians,
float  innerCircleProportionalSize 
)

Adds a "pie-chart" shape to the path.

The shape is added as a new sub-path. (Any currently open paths will be left open).

Note that when specifying the start and end angles, the curve will be drawn either clockwise or anti-clockwise according to whether the end angle is greater than the start. This means that sometimes you may need to use values greater than 2*Pi for the end angle.

Parameters
xthe left-hand edge of the rectangle in which the elliptical outline fits
ythe top edge of the rectangle in which the elliptical outline fits
widththe width of the rectangle in which the elliptical outline fits
heightthe height of the rectangle in which the elliptical outline fits
fromRadiansthe angle (clockwise) in radians at which to start the arc segment (where 0 is the top-centre of the ellipse)
toRadiansthe angle (clockwise) in radians at which to end the arc segment (where 0 is the top-centre of the ellipse)
innerCircleProportionalSizeif this is > 0, then the pie will be drawn as a curved band around a hollow ellipse at its centre, where this value indicates the inner ellipse's size with respect to the outer one.
See also
addArc

◆ addPieSegment() [2/2]

void Path::addPieSegment ( Rectangle< float >  segmentBounds,
float  fromRadians,
float  toRadians,
float  innerCircleProportionalSize 
)

Adds a "pie-chart" shape to the path.

The shape is added as a new sub-path. (Any currently open paths will be left open).

Note that when specifying the start and end angles, the curve will be drawn either clockwise or anti-clockwise according to whether the end angle is greater than the start. This means that sometimes you may need to use values greater than 2*Pi for the end angle.

Parameters
segmentBoundsthe outer rectangle in which the elliptical outline fits
fromRadiansthe angle (clockwise) in radians at which to start the arc segment (where 0 is the top-centre of the ellipse)
toRadiansthe angle (clockwise) in radians at which to end the arc segment (where 0 is the top-centre of the ellipse)
innerCircleProportionalSizeif this is > 0, then the pie will be drawn as a curved band around a hollow ellipse at its centre, where this value indicates the inner ellipse's size with respect to the outer one.
See also
addArc

◆ addPolygon()

void Path::addPolygon ( const Point< float >  centre,
int  numberOfSides,
float  radius,
float  startAngle = 0.0f 
)

Adds a polygon shape to the path.

See also
addStar

◆ addQuadrilateral()

void Path::addQuadrilateral ( float  x1,
float  y1,
float  x2,
float  y2,
float  x3,
float  y3,
float  x4,
float  y4 
)

Adds a quadrilateral to the path.

The quad is added as a new closed sub-path. (Any currently open paths will be left open).

Note that whether the vertices are specified in clockwise or anticlockwise order will affect how the quad is filled when it overlaps other shapes (the winding order setting will affect this of course).

◆ addRectangle() [1/2]

◆ addRectangle() [2/2]

template<typename ValueType >
void Path::addRectangle ( const Rectangle< ValueType > &  rectangle)
inline

Adds a rectangle to the path.

The rectangle is added as a new sub-path. (Any currently open paths will be left open).

See also
addRoundedRectangle, addTriangle

◆ addRoundedRectangle() [1/5]

void Path::addRoundedRectangle ( float  x,
float  y,
float  width,
float  height,
float  cornerSize 
)

Adds a rectangle with rounded corners to the path.

The rectangle is added as a new sub-path. (Any currently open paths will be left open).

See also
addRectangle, addTriangle

◆ addRoundedRectangle() [2/5]

void Path::addRoundedRectangle ( float  x,
float  y,
float  width,
float  height,
float  cornerSizeX,
float  cornerSizeY 
)

Adds a rectangle with rounded corners to the path.

The rectangle is added as a new sub-path. (Any currently open paths will be left open).

See also
addRectangle, addTriangle

◆ addRoundedRectangle() [3/5]

void Path::addRoundedRectangle ( float  x,
float  y,
float  width,
float  height,
float  cornerSizeX,
float  cornerSizeY,
bool  curveTopLeft,
bool  curveTopRight,
bool  curveBottomLeft,
bool  curveBottomRight 
)

Adds a rectangle with rounded corners to the path.

The rectangle is added as a new sub-path. (Any currently open paths will be left open).

See also
addRectangle, addTriangle

◆ addRoundedRectangle() [4/5]

template<typename ValueType >
void Path::addRoundedRectangle ( const Rectangle< ValueType > &  rectangle,
float  cornerSizeX,
float  cornerSizeY 
)
inline

Adds a rectangle with rounded corners to the path.

The rectangle is added as a new sub-path. (Any currently open paths will be left open).

See also
addRectangle, addTriangle

References Rectangle< ValueType >::getHeight(), Rectangle< ValueType >::getWidth(), Rectangle< ValueType >::getX(), and Rectangle< ValueType >::getY().

◆ addRoundedRectangle() [5/5]

template<typename ValueType >
void Path::addRoundedRectangle ( const Rectangle< ValueType > &  rectangle,
float  cornerSize 
)
inline

Adds a rectangle with rounded corners to the path.

The rectangle is added as a new sub-path. (Any currently open paths will be left open).

See also
addRectangle, addTriangle

References Justification::centred.

◆ addStar()

void Path::addStar ( const Point< float >  centre,
int  numberOfPoints,
float  innerRadius,
float  outerRadius,
float  startAngle = 0.0f 
)

Adds a star shape to the path.

See also
addPolygon

◆ addTriangle() [1/2]

void Path::addTriangle ( float  x1,
float  y1,
float  x2,
float  y2,
float  x3,
float  y3 
)

Adds a triangle to the path.

The triangle is added as a new closed sub-path. (Any currently open paths will be left open).

Note that whether the vertices are specified in clockwise or anticlockwise order will affect how the triangle is filled when it overlaps other shapes (the winding order setting will affect this of course).

◆ addTriangle() [2/2]

void Path::addTriangle ( Point< float >  point1,
Point< float >  point2,
Point< float >  point3 
)

Adds a triangle to the path.

The triangle is added as a new closed sub-path. (Any currently open paths will be left open).

Note that whether the vertices are specified in clockwise or anticlockwise order will affect how the triangle is filled when it overlaps other shapes (the winding order setting will affect this of course).

◆ applyTransform()

void Path::applyTransform ( const AffineTransform transform)
noexcept

◆ clear()

void Path::clear ( )
noexcept

Removes all lines and curves, resetting the path completely.

◆ closeSubPath()

void Path::closeSubPath ( )

Closes a the current sub-path with a line back to its start-point.

When creating a closed shape such as a triangle, don't use 3 lineTo() calls - instead use two lineTo() calls, followed by a closeSubPath() to join the final point back to the start.

This ensures that closes shapes are recognised as such, and this is important for tasks like drawing strokes, which needs to know whether to draw end-caps or not.

See also
startNewSubPath, lineTo, quadraticTo, cubicTo, closeSubPath

◆ contains() [1/2]

bool Path::contains ( float  x,
float  y,
float  tolerance = defaultToleranceForTesting 
) const

Checks whether a point lies within the path.

This is only relevant for closed paths (see closeSubPath()), and may produce false results if used on a path which has open sub-paths.

The path's winding rule is taken into account by this method.

The tolerance parameter is the maximum error allowed when flattening the path, so this method could return a false positive when your point is up to this distance outside the path's boundary.

See also
closeSubPath, setUsingNonZeroWinding

◆ contains() [2/2]

bool Path::contains ( const Point< float >  point,
float  tolerance = defaultToleranceForTesting 
) const

Checks whether a point lies within the path.

This is only relevant for closed paths (see closeSubPath()), and may produce false results if used on a path which has open sub-paths.

The path's winding rule is taken into account by this method.

The tolerance parameter is the maximum error allowed when flattening the path, so this method could return a false positive when your point is up to this distance outside the path's boundary.

See also
closeSubPath, setUsingNonZeroWinding

◆ createPathWithRoundedCorners()

Path Path::createPathWithRoundedCorners ( float  cornerRadius) const

Creates a version of this path where all sharp corners have been replaced by curves.

Wherever two lines meet at an angle, this will replace the corner with a curve of the given radius.

◆ cubicTo() [1/2]

void Path::cubicTo ( float  controlPoint1X,
float  controlPoint1Y,
float  controlPoint2X,
float  controlPoint2Y,
float  endPointX,
float  endPointY 
)

Adds a cubic bezier curve from the shape's last position to a new position.

This will connect the end-point of the last line or curve that was added to a new point, using a cubic spline with two control-points.

See the class description for an example of how to add lines and curves to a path.

See also
startNewSubPath, lineTo, quadraticTo, closeSubPath

◆ cubicTo() [2/2]

void Path::cubicTo ( const Point< float >  controlPoint1,
const Point< float >  controlPoint2,
const Point< float >  endPoint 
)

Adds a cubic bezier curve from the shape's last position to a new position.

This will connect the end-point of the last line or curve that was added to a new point, using a cubic spline with two control-points.

See the class description for an example of how to add lines and curves to a path.

See also
startNewSubPath, lineTo, quadraticTo, closeSubPath

◆ getBounds()

Rectangle<float> Path::getBounds ( ) const
noexcept

Returns the smallest rectangle that contains all points within the path.

◆ getBoundsTransformed()

Rectangle<float> Path::getBoundsTransformed ( const AffineTransform transform) const
noexcept

Returns the smallest rectangle that contains all points within the path after it's been transformed with the given tranasform matrix.

Referenced by RenderingHelpers::SavedStateBase< SoftwareRendererSavedState >::fillPath().

◆ getClippedLine()

Line<float> Path::getClippedLine ( Line< float >  line,
bool  keepSectionOutsidePath 
) const

Cuts off parts of a line to keep the parts that are either inside or outside this path.

Note that this isn't smart enough to cope with situations where the line would need to be cut into multiple pieces to correctly clip against a re-entrant shape.

Parameters
linethe line to clip
keepSectionOutsidePathif true, it's the section outside the path that will be kept; if false its the section inside the path

◆ getCurrentPosition()

Point<float> Path::getCurrentPosition ( ) const

Returns the last point that was added to the path by one of the drawing methods.

◆ getLength()

float Path::getLength ( const AffineTransform transform = AffineTransform(),
float  tolerance = defaultToleranceForMeasurement 
) const

Returns the length of the path.

See also
getPointAlongPath

◆ getNearestPoint()

float Path::getNearestPoint ( Point< float >  targetPoint,
Point< float > &  pointOnPath,
const AffineTransform transform = AffineTransform(),
float  tolerance = defaultToleranceForMeasurement 
) const

Finds the point along the path which is nearest to a given position.

This sets pointOnPath to the nearest point, and returns the distance of this point from the start of the path.

◆ getPointAlongPath()

Point<float> Path::getPointAlongPath ( float  distanceFromStart,
const AffineTransform transform = AffineTransform(),
float  tolerance = defaultToleranceForMeasurement 
) const

Returns a point that is the specified distance along the path.

If the distance is greater than the total length of the path, this will return the end point.

See also
getLength

◆ getTransformToScaleToFit() [1/2]

AffineTransform Path::getTransformToScaleToFit ( float  x,
float  y,
float  width,
float  height,
bool  preserveProportions,
Justification  justificationType = Justification::centred 
) const

Returns a transform that can be used to rescale the path to fit into a given space.

Parameters
xthe x position of the rectangle to fit the path inside
ythe y position of the rectangle to fit the path inside
widththe width of the rectangle to fit the path inside
heightthe height of the rectangle to fit the path inside
preserveProportionsif true, it will fit the path into the space without altering its horizontal/vertical scale ratio; if false, it will distort the path to fill the specified ratio both horizontally and vertically
justificationTypeif the proportions are preseved, the resultant path may be smaller than the available rectangle, so this describes how it should be positioned within the space.
Returns
an appropriate transformation
See also
applyTransform, scaleToFit

◆ getTransformToScaleToFit() [2/2]

AffineTransform Path::getTransformToScaleToFit ( const Rectangle< float > &  area,
bool  preserveProportions,
Justification  justificationType = Justification::centred 
) const

Returns a transform that can be used to rescale the path to fit into a given space.

Parameters
areathe rectangle to fit the path inside
preserveProportionsif true, it will fit the path into the space without altering its horizontal/vertical scale ratio; if false, it will distort the path to fill the specified ratio both horizontally and vertically
justificationTypeif the proportions are preseved, the resultant path may be smaller than the available rectangle, so this describes how it should be positioned within the space.
Returns
an appropriate transformation
See also
applyTransform, scaleToFit

◆ intersectsLine()

bool Path::intersectsLine ( Line< float >  line,
float  tolerance = defaultToleranceForTesting 
)

Checks whether a line crosses the path.

This will return positive if the line crosses any of the paths constituent lines or curves. It doesn't take into account whether the line is inside or outside the path, or whether the path is open or closed.

The tolerance parameter is the maximum error allowed when flattening the path, so this method could return a false positive when your point is up to this distance outside the path's boundary.

◆ isEmpty()

bool Path::isEmpty ( ) const
noexcept

Returns true if the path doesn't contain any lines or curves.

◆ isUsingNonZeroWinding()

bool Path::isUsingNonZeroWinding ( ) const
inline

Returns the flag that indicates whether the path should use a non-zero winding rule.

The default for a new path is true.

See also
setUsingNonZeroWinding

◆ lineTo() [1/2]

void Path::lineTo ( float  endX,
float  endY 
)

Adds a line from the shape's last position to a new end-point.

This will connect the end-point of the last line or curve that was added to a new point, using a straight line.

See the class description for an example of how to add lines and curves to a path.

See also
startNewSubPath, quadraticTo, cubicTo, closeSubPath

◆ lineTo() [2/2]

void Path::lineTo ( const Point< float >  end)

Adds a line from the shape's last position to a new end-point.

This will connect the end-point of the last line or curve that was added to a new point, using a straight line.

See the class description for an example of how to add lines and curves to a path.

See also
startNewSubPath, quadraticTo, cubicTo, closeSubPath

◆ loadPathFromData()

void Path::loadPathFromData ( const void *  data,
size_t  numberOfBytes 
)

Loads a stored path from a block of data.

This is similar to loadPathFromStream(), but just reads from a block of data. Useful if you're including stored shapes in your code as a block of static data.

See also
loadPathFromStream, writePathToStream

◆ loadPathFromStream()

void Path::loadPathFromStream ( InputStream source)

Loads a stored path from a data stream.

The data in the stream must have been written using writePathToStream().

Note that this will append the stored path to whatever is currently in this path, so you might need to call clear() beforehand.

See also
loadPathFromData, writePathToStream

◆ operator!=()

bool Path::operator!= ( const Path ) const
noexcept

◆ operator=() [1/2]

Path& Path::operator= ( const Path )

Copies this path from another one.

◆ operator=() [2/2]

Path& Path::operator= ( Path &&  )
noexcept

Move assignment operator.

◆ operator==()

bool Path::operator== ( const Path ) const
noexcept

◆ preallocateSpace()

void Path::preallocateSpace ( int  numExtraCoordsToMakeSpaceFor)

Preallocates enough space for adding the given number of coordinates to the path.

If you're about to add a large number of lines or curves to the path, it can make the task much more efficient to call this first and avoid costly reallocations as the structure grows. The actual value to pass is a bit tricky to calculate because the space required depends on what you're adding - e.g. each lineTo() or startNewSubPath() will require 3 coords (x, y and a type marker). Each quadraticTo() will need 5, and a cubicTo() will require 7. Closing a sub-path will require 1.

◆ quadraticTo() [1/2]

void Path::quadraticTo ( float  controlPointX,
float  controlPointY,
float  endPointX,
float  endPointY 
)

Adds a quadratic bezier curve from the shape's last position to a new position.

This will connect the end-point of the last line or curve that was added to a new point, using a quadratic spline with one control-point.

See the class description for an example of how to add lines and curves to a path.

See also
startNewSubPath, lineTo, cubicTo, closeSubPath

◆ quadraticTo() [2/2]

void Path::quadraticTo ( const Point< float >  controlPoint,
const Point< float >  endPoint 
)

Adds a quadratic bezier curve from the shape's last position to a new position.

This will connect the end-point of the last line or curve that was added to a new point, using a quadratic spline with one control-point.

See the class description for an example of how to add lines and curves to a path.

See also
startNewSubPath, lineTo, cubicTo, closeSubPath

◆ restoreFromString()

void Path::restoreFromString ( StringRef  stringVersion)

Restores this path from a string that was created with the toString() method.

See also
toString()

◆ scaleToFit()

void Path::scaleToFit ( float  x,
float  y,
float  width,
float  height,
bool  preserveProportions 
)
noexcept

Rescales this path to make it fit neatly into a given space.

This is effectively a quick way of calling applyTransform (getTransformToScaleToFit (x, y, w, h, preserveProportions))

Parameters
xthe x position of the rectangle to fit the path inside
ythe y position of the rectangle to fit the path inside
widththe width of the rectangle to fit the path inside
heightthe height of the rectangle to fit the path inside
preserveProportionsif true, it will fit the path into the space without altering its horizontal/vertical scale ratio; if false, it will distort the path to fill the specified ratio both horizontally and vertically
See also
applyTransform, getTransformToScaleToFit

◆ setUsingNonZeroWinding()

void Path::setUsingNonZeroWinding ( bool  isNonZeroWinding)
noexcept

Changes the winding-rule to be used when filling the path.

If set to true (which is the default), then the path uses a non-zero-winding rule to determine which points are inside the path. If set to false, it uses an alternate-winding rule.

The winding-rule comes into play when areas of the shape overlap other areas, and determines whether the overlapping regions are considered to be inside or outside.

Changing this value just sets a flag - it doesn't affect the contents of the path.

See also
isUsingNonZeroWinding

Referenced by RenderingHelpers::SavedStateBase< SoftwareRendererSavedState >::excludeClipRectangle().

◆ startNewSubPath() [1/2]

void Path::startNewSubPath ( float  startX,
float  startY 
)

Begins a new subpath with a given starting position.

This will move the path's current position to the coordinates passed in and make it ready to draw lines or curves starting from this position.

After adding whatever lines and curves are needed, you can either close the current sub-path using closeSubPath() or call startNewSubPath() to move to a new sub-path, leaving the old one open-ended.

See also
lineTo, quadraticTo, cubicTo, closeSubPath

◆ startNewSubPath() [2/2]

void Path::startNewSubPath ( const Point< float >  start)

Begins a new subpath with a given starting position.

This will move the path's current position to the coordinates passed in and make it ready to draw lines or curves starting from this position.

After adding whatever lines and curves are needed, you can either close the current sub-path using closeSubPath() or call startNewSubPath() to move to a new sub-path, leaving the old one open-ended.

See also
lineTo, quadraticTo, cubicTo, closeSubPath

◆ swapWithPath()

void Path::swapWithPath ( Path )
noexcept

Swaps the contents of this path with another one.

The internal data of the two paths is swapped over, so this is much faster than copying it to a temp variable and back.

◆ toString()

String Path::toString ( ) const

Creates a string containing a textual representation of this path.

See also
restoreFromString

◆ writePathToStream()

void Path::writePathToStream ( OutputStream destination) const

Stores the path by writing it out to a stream.

After writing out a path, you can reload it using loadPathFromStream().

See also
loadPathFromStream, loadPathFromData

Friends And Related Function Documentation

◆ Path::Iterator

friend class Path::Iterator
friend

◆ PathFlatteningIterator

friend class PathFlatteningIterator
friend

Member Data Documentation

◆ bounds

PathBounds Path::bounds
private

◆ closeSubPathMarker

const float Path::closeSubPathMarker
staticprivate

◆ cubicMarker

const float Path::cubicMarker
staticprivate

◆ data

ArrayAllocationBase<float, DummyCriticalSection> Path::data
private

◆ defaultToleranceForMeasurement

const float Path::defaultToleranceForMeasurement
static

◆ defaultToleranceForTesting

const float Path::defaultToleranceForTesting
static

◆ lineMarker

const float Path::lineMarker
staticprivate

◆ moveMarker

const float Path::moveMarker
staticprivate

◆ numElements

size_t Path::numElements = 0
private

◆ quadMarker

const float Path::quadMarker
staticprivate

◆ useNonZeroWinding

bool Path::useNonZeroWinding = true
private

The documentation for this class was generated from the following file: