Class Path2D
- Direct Known Subclasses:
Path2D.Double
,Path2D.Float
Path2D
class provides a simple, yet flexible
shape which represents an arbitrary geometric path.
It can fully represent any path which can be iterated by the
PathIterator
interface including all of its segment
types and winding rules and it implements all of the
basic hit testing methods of the Shape
interface.
Use Path2D.Float
when dealing with data that can be represented
and used with floating point precision. Use Path2D.Double
for data that requires the accuracy or range of double precision.
Path2D
provides exactly those facilities required for
basic construction and management of a geometric path and
implementation of the above interfaces with little added
interpretation.
If it is useful to manipulate the interiors of closed
geometric shapes beyond simple hit testing then the
Area
class provides additional capabilities
specifically targeted at closed figures.
While both classes nominally implement the Shape
interface, they differ in purpose and together they provide
two useful views of a geometric shape where Path2D
deals primarily with a trajectory formed by path segments
and Area
deals more with interpretation and manipulation
of enclosed regions of 2D geometric space.
The PathIterator
interface has more detailed descriptions
of the types of segments that make up a path and the winding rules
that control how to determine which regions are inside or outside
the path.
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
TheDouble
class defines a geometric path with coordinates stored in double precision floating point.static class
TheFloat
class defines a geometric path with coordinates stored in single precision floating point. -
Field Summary
Modifier and TypeFieldDescriptionstatic final int
An even-odd winding rule for determining the interior of a path.static final int
A non-zero winding rule for determining the interior of a path. -
Method Summary
Modifier and TypeMethodDescriptionabstract void
append
(PathIterator pi, boolean connect) Appends the geometry of the specifiedPathIterator
object to the path, possibly connecting the new geometry to the existing path segments with a line segment.final void
Appends the geometry of the specifiedShape
object to the path, possibly connecting the new geometry to the existing path segments with a line segment.abstract Object
clone()
Creates a new object of the same class as this object.final void
Closes the current subpath by drawing a straight line back to the coordinates of the lastmoveTo
.final boolean
contains
(double x, double y) Tests if the specified coordinates are inside the boundary of theShape
, as described by the definition of insideness.final boolean
contains
(double x, double y, double w, double h) Tests if the interior of theShape
entirely contains the specified rectangular area.static boolean
contains
(PathIterator pi, double x, double y) Tests if the specified coordinates are inside the closed boundary of the specifiedPathIterator
.static boolean
contains
(PathIterator pi, double x, double y, double w, double h) Tests if the specified rectangular area is entirely inside the closed boundary of the specifiedPathIterator
.static boolean
contains
(PathIterator pi, Point2D p) Tests if the specifiedPoint2D
is inside the closed boundary of the specifiedPathIterator
.static boolean
contains
(PathIterator pi, Rectangle2D r) Tests if the specifiedRectangle2D
is entirely inside the closed boundary of the specifiedPathIterator
.final boolean
Tests if a specifiedPoint2D
is inside the boundary of theShape
, as described by the definition of insideness.final boolean
Tests if the interior of theShape
entirely contains the specifiedRectangle2D
.final Shape
Returns a newShape
representing a transformed version of thisPath2D
.abstract void
curveTo
(double x1, double y1, double x2, double y2, double x3, double y3) Adds a curved segment, defined by three new points, to the path by drawing a Bézier curve that intersects both the current coordinates and the specified coordinates(x3,y3)
, using the specified points(x1,y1)
and(x2,y2)
as Bézier control points.final Rectangle
Returns an integerRectangle
that completely encloses theShape
.final Point2D
Returns the coordinates most recently added to the end of the path as aPoint2D
object.final PathIterator
getPathIterator
(AffineTransform at, double flatness) Returns an iterator object that iterates along theShape
boundary and provides access to a flattened view of theShape
outline geometry.final int
Returns the fill style winding rule.final boolean
intersects
(double x, double y, double w, double h) Tests if the interior of theShape
intersects the interior of a specified rectangular area.static boolean
intersects
(PathIterator pi, double x, double y, double w, double h) Tests if the interior of the specifiedPathIterator
intersects the interior of a specified set of rectangular coordinates.static boolean
intersects
(PathIterator pi, Rectangle2D r) Tests if the interior of the specifiedPathIterator
intersects the interior of a specifiedRectangle2D
.final boolean
Tests if the interior of theShape
intersects the interior of a specifiedRectangle2D
.abstract void
lineTo
(double x, double y) Adds a point to the path by drawing a straight line from the current coordinates to the new specified coordinates specified in double precision.abstract void
moveTo
(double x, double y) Adds a point to the path by moving to the specified coordinates specified in double precision.abstract void
quadTo
(double x1, double y1, double x2, double y2) Adds a curved segment, defined by two new points, to the path by drawing a Quadratic curve that intersects both the current coordinates and the specified coordinates(x2,y2)
, using the specified point(x1,y1)
as a quadratic parametric control point.final void
reset()
Resets the path to empty.final void
setWindingRule
(int rule) Sets the winding rule for this path to the specified value.abstract void
Transforms the geometry of this path using the specifiedAffineTransform
.abstract void
Trims the capacity of this Path2D instance to its current size.Methods declared in class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods declared in interface java.awt.Shape
getBounds2D, getPathIterator
-
Field Details
-
WIND_EVEN_ODD
public static final int WIND_EVEN_ODDAn even-odd winding rule for determining the interior of a path.- Since:
- 1.6
- See Also:
-
WIND_NON_ZERO
public static final int WIND_NON_ZEROA non-zero winding rule for determining the interior of a path.- Since:
- 1.6
- See Also:
-
-
Method Details
-
moveTo
public abstract void moveTo(double x, double y) Adds a point to the path by moving to the specified coordinates specified in double precision.- Parameters:
x
- the specified X coordinatey
- the specified Y coordinate- Since:
- 1.6
-
lineTo
public abstract void lineTo(double x, double y) Adds a point to the path by drawing a straight line from the current coordinates to the new specified coordinates specified in double precision.- Parameters:
x
- the specified X coordinatey
- the specified Y coordinate- Since:
- 1.6
-
quadTo
public abstract void quadTo(double x1, double y1, double x2, double y2) Adds a curved segment, defined by two new points, to the path by drawing a Quadratic curve that intersects both the current coordinates and the specified coordinates(x2,y2)
, using the specified point(x1,y1)
as a quadratic parametric control point. All coordinates are specified in double precision.- Parameters:
x1
- the X coordinate of the quadratic control pointy1
- the Y coordinate of the quadratic control pointx2
- the X coordinate of the final end pointy2
- the Y coordinate of the final end point- Since:
- 1.6
-
curveTo
public abstract void curveTo(double x1, double y1, double x2, double y2, double x3, double y3) Adds a curved segment, defined by three new points, to the path by drawing a Bézier curve that intersects both the current coordinates and the specified coordinates(x3,y3)
, using the specified points(x1,y1)
and(x2,y2)
as Bézier control points. All coordinates are specified in double precision.- Parameters:
x1
- the X coordinate of the first Bézier control pointy1
- the Y coordinate of the first Bézier control pointx2
- the X coordinate of the second Bézier control pointy2
- the Y coordinate of the second Bézier control pointx3
- the X coordinate of the final end pointy3
- the Y coordinate of the final end point- Since:
- 1.6
-
closePath
public final void closePath()Closes the current subpath by drawing a straight line back to the coordinates of the lastmoveTo
. If the path is already closed then this method has no effect.- Since:
- 1.6
-
append
Appends the geometry of the specifiedShape
object to the path, possibly connecting the new geometry to the existing path segments with a line segment. If theconnect
parameter istrue
and the path is not empty then any initialmoveTo
in the geometry of the appendedShape
is turned into alineTo
segment. If the destination coordinates of such a connectinglineTo
segment match the ending coordinates of a currently open subpath then the segment is omitted as superfluous. The winding rule of the specifiedShape
is ignored and the appended geometry is governed by the winding rule specified for this path.- Parameters:
s
- theShape
whose geometry is appended to this pathconnect
- a boolean to control whether or not to turn an initialmoveTo
segment into alineTo
segment to connect the new geometry to the existing path- Since:
- 1.6
-
append
Appends the geometry of the specifiedPathIterator
object to the path, possibly connecting the new geometry to the existing path segments with a line segment. If theconnect
parameter istrue
and the path is not empty then any initialmoveTo
in the geometry of the appendedShape
is turned into alineTo
segment. If the destination coordinates of such a connectinglineTo
segment match the ending coordinates of a currently open subpath then the segment is omitted as superfluous. The winding rule of the specifiedShape
is ignored and the appended geometry is governed by the winding rule specified for this path.- Parameters:
pi
- thePathIterator
whose geometry is appended to this pathconnect
- a boolean to control whether or not to turn an initialmoveTo
segment into alineTo
segment to connect the new geometry to the existing path- Since:
- 1.6
-
getWindingRule
public final int getWindingRule()Returns the fill style winding rule.- Returns:
- an integer representing the current winding rule.
- Since:
- 1.6
- See Also:
-
setWindingRule
public final void setWindingRule(int rule) Sets the winding rule for this path to the specified value.- Parameters:
rule
- an integer representing the specified winding rule- Throws:
IllegalArgumentException
- ifrule
is not eitherWIND_EVEN_ODD
orWIND_NON_ZERO
- Since:
- 1.6
- See Also:
-
getCurrentPoint
-
reset
public final void reset()Resets the path to empty. The append position is set back to the beginning of the path and all coordinates and point types are forgotten.- Since:
- 1.6
-
transform
Transforms the geometry of this path using the specifiedAffineTransform
. The geometry is transformed in place, which permanently changes the boundary defined by this object.- Parameters:
at
- theAffineTransform
used to transform the area- Since:
- 1.6
-
createTransformedShape
Returns a newShape
representing a transformed version of thisPath2D
. Note that the exact type and coordinate precision of the return value is not specified for this method. The method will return a Shape that contains no less precision for the transformed geometry than thisPath2D
currently maintains, but it may contain no more precision either. If the tradeoff of precision vs. storage size in the result is important then the convenience constructors in thePath2D.Float
andPath2D.Double
subclasses should be used to make the choice explicit.- Parameters:
at
- theAffineTransform
used to transform a newShape
.- Returns:
- a new
Shape
, transformed with the specifiedAffineTransform
. - Since:
- 1.6
-
getBounds
Returns an integerRectangle
that completely encloses theShape
. Note that there is no guarantee that the returnedRectangle
is the smallest bounding box that encloses theShape
, only that theShape
lies entirely within the indicatedRectangle
. The returnedRectangle
might also fail to completely enclose theShape
if theShape
overflows the limited range of the integer data type. ThegetBounds2D
method generally returns a tighter bounding box due to its greater flexibility in representation.Note that the definition of insideness can lead to situations where points on the defining outline of the
shape
may not be considered contained in the returnedbounds
object, but only in cases where those points are also not considered contained in the originalshape
.If a
point
is inside theshape
according to thecontains(point)
method, then it must be inside the returnedRectangle
bounds object according to thecontains(point)
method of thebounds
. Specifically:shape.contains(x,y)
requiresbounds.contains(x,y)
If a
point
is not inside theshape
, then it might still be contained in thebounds
object:bounds.contains(x,y)
does not implyshape.contains(x,y)
-
contains
Tests if the specified coordinates are inside the closed boundary of the specifiedPathIterator
.This method provides a basic facility for implementors of the
Shape
interface to implement support for theShape.contains(double, double)
method.- Parameters:
pi
- the specifiedPathIterator
x
- the specified X coordinatey
- the specified Y coordinate- Returns:
true
if the specified coordinates are inside the specifiedPathIterator
;false
otherwise- Since:
- 1.6
-
contains
Tests if the specifiedPoint2D
is inside the closed boundary of the specifiedPathIterator
.This method provides a basic facility for implementors of the
Shape
interface to implement support for theShape.contains(Point2D)
method.- Parameters:
pi
- the specifiedPathIterator
p
- the specifiedPoint2D
- Returns:
true
if the specified coordinates are inside the specifiedPathIterator
;false
otherwise- Since:
- 1.6
-
contains
public final boolean contains(double x, double y) Tests if the specified coordinates are inside the boundary of theShape
, as described by the definition of insideness. -
contains
Tests if a specifiedPoint2D
is inside the boundary of theShape
, as described by the definition of insideness. -
contains
Tests if the specified rectangular area is entirely inside the closed boundary of the specifiedPathIterator
.This method provides a basic facility for implementors of the
Shape
interface to implement support for theShape.contains(double, double, double, double)
method.This method object may conservatively return false in cases where the specified rectangular area intersects a segment of the path, but that segment does not represent a boundary between the interior and exterior of the path. Such segments could lie entirely within the interior of the path if they are part of a path with a
WIND_NON_ZERO
winding rule or if the segments are retraced in the reverse direction such that the two sets of segments cancel each other out without any exterior area falling between them. To determine whether segments represent true boundaries of the interior of the path would require extensive calculations involving all of the segments of the path and the winding rule and are thus beyond the scope of this implementation.- Parameters:
pi
- the specifiedPathIterator
x
- the specified X coordinatey
- the specified Y coordinatew
- the width of the specified rectangular areah
- the height of the specified rectangular area- Returns:
true
if the specifiedPathIterator
contains the specified rectangular area;false
otherwise.- Since:
- 1.6
-
contains
Tests if the specifiedRectangle2D
is entirely inside the closed boundary of the specifiedPathIterator
.This method provides a basic facility for implementors of the
Shape
interface to implement support for theShape.contains(Rectangle2D)
method.This method object may conservatively return false in cases where the specified rectangular area intersects a segment of the path, but that segment does not represent a boundary between the interior and exterior of the path. Such segments could lie entirely within the interior of the path if they are part of a path with a
WIND_NON_ZERO
winding rule or if the segments are retraced in the reverse direction such that the two sets of segments cancel each other out without any exterior area falling between them. To determine whether segments represent true boundaries of the interior of the path would require extensive calculations involving all of the segments of the path and the winding rule and are thus beyond the scope of this implementation.- Parameters:
pi
- the specifiedPathIterator
r
- a specifiedRectangle2D
- Returns:
true
if the specifiedPathIterator
contains the specifiedRectangle2D
;false
otherwise.- Since:
- 1.6
-
contains
public final boolean contains(double x, double y, double w, double h) Tests if the interior of theShape
entirely contains the specified rectangular area. All coordinates that lie inside the rectangular area must lie within theShape
for the entire rectangular area to be considered contained within theShape
.The
Shape.contains()
method allows aShape
implementation to conservatively returnfalse
when:-
the
intersect
method returnstrue
and -
the calculations to determine whether or not the
Shape
entirely contains the rectangular area are prohibitively expensive.
Shapes
this method might returnfalse
even though theShape
contains the rectangular area. TheArea
class performs more accurate geometric computations than mostShape
objects and therefore can be used if a more precise answer is required.This method object may conservatively return false in cases where the specified rectangular area intersects a segment of the path, but that segment does not represent a boundary between the interior and exterior of the path. Such segments could lie entirely within the interior of the path if they are part of a path with a
WIND_NON_ZERO
winding rule or if the segments are retraced in the reverse direction such that the two sets of segments cancel each other out without any exterior area falling between them. To determine whether segments represent true boundaries of the interior of the path would require extensive calculations involving all of the segments of the path and the winding rule and are thus beyond the scope of this implementation.- Specified by:
contains
in interfaceShape
- Parameters:
x
- the X coordinate of the upper-left corner of the specified rectangular areay
- the Y coordinate of the upper-left corner of the specified rectangular areaw
- the width of the specified rectangular areah
- the height of the specified rectangular area- Returns:
true
if the interior of theShape
entirely contains the specified rectangular area;false
otherwise or, if theShape
contains the rectangular area and theintersects
method returnstrue
and the containment calculations would be too expensive to perform.- Since:
- 1.6
- See Also:
-
the
-
contains
Tests if the interior of theShape
entirely contains the specifiedRectangle2D
. TheShape.contains()
method allows aShape
implementation to conservatively returnfalse
when:-
the
intersect
method returnstrue
and -
the calculations to determine whether or not the
Shape
entirely contains theRectangle2D
are prohibitively expensive.
Shapes
this method might returnfalse
even though theShape
contains theRectangle2D
. TheArea
class performs more accurate geometric computations than mostShape
objects and therefore can be used if a more precise answer is required.This method object may conservatively return false in cases where the specified rectangular area intersects a segment of the path, but that segment does not represent a boundary between the interior and exterior of the path. Such segments could lie entirely within the interior of the path if they are part of a path with a
WIND_NON_ZERO
winding rule or if the segments are retraced in the reverse direction such that the two sets of segments cancel each other out without any exterior area falling between them. To determine whether segments represent true boundaries of the interior of the path would require extensive calculations involving all of the segments of the path and the winding rule and are thus beyond the scope of this implementation.- Specified by:
contains
in interfaceShape
- Parameters:
r
- The specifiedRectangle2D
- Returns:
true
if the interior of theShape
entirely contains theRectangle2D
;false
otherwise or, if theShape
contains theRectangle2D
and theintersects
method returnstrue
and the containment calculations would be too expensive to perform.- Since:
- 1.6
- See Also:
-
the
-
intersects
Tests if the interior of the specifiedPathIterator
intersects the interior of a specified set of rectangular coordinates.This method provides a basic facility for implementors of the
Shape
interface to implement support for theShape.intersects(double, double, double, double)
method.This method object may conservatively return true in cases where the specified rectangular area intersects a segment of the path, but that segment does not represent a boundary between the interior and exterior of the path. Such a case may occur if some set of segments of the path are retraced in the reverse direction such that the two sets of segments cancel each other out without any interior area between them. To determine whether segments represent true boundaries of the interior of the path would require extensive calculations involving all of the segments of the path and the winding rule and are thus beyond the scope of this implementation.
- Parameters:
pi
- the specifiedPathIterator
x
- the specified X coordinatey
- the specified Y coordinatew
- the width of the specified rectangular coordinatesh
- the height of the specified rectangular coordinates- Returns:
true
if the specifiedPathIterator
and the interior of the specified set of rectangular coordinates intersect each other;false
otherwise.- Since:
- 1.6
-
intersects
Tests if the interior of the specifiedPathIterator
intersects the interior of a specifiedRectangle2D
.This method provides a basic facility for implementors of the
Shape
interface to implement support for theShape.intersects(Rectangle2D)
method.This method object may conservatively return true in cases where the specified rectangular area intersects a segment of the path, but that segment does not represent a boundary between the interior and exterior of the path. Such a case may occur if some set of segments of the path are retraced in the reverse direction such that the two sets of segments cancel each other out without any interior area between them. To determine whether segments represent true boundaries of the interior of the path would require extensive calculations involving all of the segments of the path and the winding rule and are thus beyond the scope of this implementation.
- Parameters:
pi
- the specifiedPathIterator
r
- the specifiedRectangle2D
- Returns:
true
if the specifiedPathIterator
and the interior of the specifiedRectangle2D
intersect each other;false
otherwise.- Since:
- 1.6
-
intersects
public final boolean intersects(double x, double y, double w, double h) Tests if the interior of theShape
intersects the interior of a specified rectangular area. The rectangular area is considered to intersect theShape
if any point is contained in both the interior of theShape
and the specified rectangular area.The
Shape.intersects()
method allows aShape
implementation to conservatively returntrue
when:-
there is a high probability that the rectangular area and the
Shape
intersect, but - the calculations to accurately determine this intersection are prohibitively expensive.
Shapes
this method might returntrue
even though the rectangular area does not intersect theShape
. TheArea
class performs more accurate computations of geometric intersection than mostShape
objects and therefore can be used if a more precise answer is required.This method object may conservatively return true in cases where the specified rectangular area intersects a segment of the path, but that segment does not represent a boundary between the interior and exterior of the path. Such a case may occur if some set of segments of the path are retraced in the reverse direction such that the two sets of segments cancel each other out without any interior area between them. To determine whether segments represent true boundaries of the interior of the path would require extensive calculations involving all of the segments of the path and the winding rule and are thus beyond the scope of this implementation.
- Specified by:
intersects
in interfaceShape
- Parameters:
x
- the X coordinate of the upper-left corner of the specified rectangular areay
- the Y coordinate of the upper-left corner of the specified rectangular areaw
- the width of the specified rectangular areah
- the height of the specified rectangular area- Returns:
true
if the interior of theShape
and the interior of the rectangular area intersect, or are both highly likely to intersect and intersection calculations would be too expensive to perform;false
otherwise.- Since:
- 1.6
- See Also:
-
there is a high probability that the rectangular area and the
-
intersects
Tests if the interior of theShape
intersects the interior of a specifiedRectangle2D
. TheShape.intersects()
method allows aShape
implementation to conservatively returntrue
when:-
there is a high probability that the
Rectangle2D
and theShape
intersect, but - the calculations to accurately determine this intersection are prohibitively expensive.
Shapes
this method might returntrue
even though theRectangle2D
does not intersect theShape
. TheArea
class performs more accurate computations of geometric intersection than mostShape
objects and therefore can be used if a more precise answer is required.This method object may conservatively return true in cases where the specified rectangular area intersects a segment of the path, but that segment does not represent a boundary between the interior and exterior of the path. Such a case may occur if some set of segments of the path are retraced in the reverse direction such that the two sets of segments cancel each other out without any interior area between them. To determine whether segments represent true boundaries of the interior of the path would require extensive calculations involving all of the segments of the path and the winding rule and are thus beyond the scope of this implementation.
- Specified by:
intersects
in interfaceShape
- Parameters:
r
- the specifiedRectangle2D
- Returns:
true
if the interior of theShape
and the interior of the specifiedRectangle2D
intersect, or are both highly likely to intersect and intersection calculations would be too expensive to perform;false
otherwise.- Since:
- 1.6
- See Also:
-
there is a high probability that the
-
getPathIterator
Returns an iterator object that iterates along theShape
boundary and provides access to a flattened view of theShape
outline geometry.Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are returned by the iterator.
If an optional
AffineTransform
is specified, the coordinates returned in the iteration are transformed accordingly.The amount of subdivision of the curved segments is controlled by the
flatness
parameter, which specifies the maximum distance that any point on the unflattened transformed curve can deviate from the returned flattened path segments. Note that a limit on the accuracy of the flattened path might be silently imposed, causing very small flattening parameters to be treated as larger values. This limit, if there is one, is defined by the particular implementation that is used.Each call to this method returns a fresh
PathIterator
object that traverses theShape
object geometry independently from any otherPathIterator
objects in use at the same time.It is recommended, but not guaranteed, that objects implementing the
Shape
interface isolate iterations that are in process from any changes that might occur to the original object's geometry during such iterations.The iterator for this class is not multi-threaded safe, which means that this
Path2D
class does not guarantee that modifications to the geometry of thisPath2D
object do not affect any iterations of that geometry that are already in process.- Specified by:
getPathIterator
in interfaceShape
- Parameters:
at
- an optionalAffineTransform
to be applied to the coordinates as they are returned in the iteration, ornull
if untransformed coordinates are desiredflatness
- the maximum distance that the line segments used to approximate the curved segments are allowed to deviate from any point on the original curve- Returns:
- a new
PathIterator
that independently traverses a flattened view of the geometry of theShape
. - Since:
- 1.6
-
clone
Creates a new object of the same class as this object.- Overrides:
clone
in classObject
- Returns:
- a clone of this instance.
- Throws:
OutOfMemoryError
- if there is not enough memory.- Since:
- 1.6
- See Also:
-
trimToSize
public abstract void trimToSize()Trims the capacity of this Path2D instance to its current size. An application can use this operation to minimize the storage of a path.- Since:
- 10
-