java.awt

Class Polygon

public class Polygon extends Object implements Shape, Serializable

This class represents a polygon, a closed, two-dimensional region in a coordinate space. The region is bounded by an arbitrary number of line segments, between (x,y) coordinate vertices. The polygon has even-odd winding, meaning that a point is inside the shape if it crosses the boundary an odd number of times on the way to infinity.

There are some public fields; if you mess with them in an inconsistent manner, it is your own fault when you get NullPointerException, ArrayIndexOutOfBoundsException, or invalid results. Also, this class is not threadsafe.

Since: 1.0

UNKNOWN: updated to 1.4

Field Summary
protected Rectangle	bounds The bounding box of this polygon.
int	npoints This total number of endpoints.
int[]	xpoints The array of X coordinates of endpoints.
int[]	ypoints The array of Y coordinates of endpoints.

Constructor Summary
	Polygon() Initializes an empty polygon.
	Polygon(int[] xpoints, int[] ypoints, int npoints) Create a new polygon with the specified endpoints.

Method Summary
void	addPoint(int x, int y) Adds the specified endpoint to the polygon.
boolean	contains(Point p) Tests whether or not the specified point is inside this polygon.
boolean	contains(int x, int y) Tests whether or not the specified point is inside this polygon.
boolean	contains(double x, double y) Tests whether or not the specified point is inside this polygon.
boolean	contains(Point2D p) Tests whether or not the specified point is inside this polygon.
boolean	contains(double x, double y, double w, double h) Test if a high-precision rectangle lies completely in the shape.
boolean	contains(Rectangle2D r) Test if a high-precision rectangle lies completely in the shape.
Rectangle	getBoundingBox() Returns the bounding box of this polygon.
Rectangle	getBounds() Returns the bounding box of this polygon.
Rectangle2D	getBounds2D() Returns a high-precision bounding box of this polygon.
PathIterator	getPathIterator(AffineTransform transform) Return an iterator along the shape boundary.
PathIterator	getPathIterator(AffineTransform transform, double flatness) Return an iterator along the flattened version of the shape boundary.
boolean	inside(int x, int y) Tests whether or not the specified point is inside this polygon.
boolean	intersects(double x, double y, double w, double h) Test if a high-precision rectangle intersects the shape.
boolean	intersects(Rectangle2D r) Test if a high-precision rectangle intersects the shape.
void	invalidate() Invalidate or flush all cached data.
void	reset() Reset the polygon to be empty.
void	translate(int dx, int dy) Translates the polygon by adding the specified values to all X and Y coordinates.

Field Detail

bounds

protected Rectangle bounds

The bounding box of this polygon. This is lazily created and cached, so it must be invalidated after changing points.

Serial: the bounding box, or null

npoints

public int npoints

This total number of endpoints.

Serial: the number of endpoints, possibly less than the array sizes

xpoints

public int[] xpoints

The array of X coordinates of endpoints. This should not be null.

Serial: the x coordinates

See Also: Polygon

ypoints

public int[] ypoints

The array of Y coordinates of endpoints. This should not be null.

Serial: the y coordinates

See Also: Polygon

Constructor Detail

Polygon

public Polygon()

Initializes an empty polygon.

Polygon

public Polygon(int[] xpoints, int[] ypoints, int npoints)

Create a new polygon with the specified endpoints. The arrays are copied, so that future modifications to the parameters do not affect the polygon.

Parameters: xpoints the array of X coordinates for this polygon ypoints the array of Y coordinates for this polygon npoints the total number of endpoints in this polygon

Throws: NegativeArraySizeException if npoints is negative IndexOutOfBoundsException if npoints exceeds either array NullPointerException if xpoints or ypoints is null

Method Detail

addPoint

public void addPoint(int x, int y)

Adds the specified endpoint to the polygon. This updates the bounding box, if it has been created.

Parameters: x the X coordinate of the point to add y the Y coordiante of the point to add

contains

public boolean contains(Point p)

Tests whether or not the specified point is inside this polygon.

Parameters: p the point to test

Returns: true if the point is inside this polygon

Throws: NullPointerException if p is null

See Also: Polygon

contains

public boolean contains(int x, int y)

Tests whether or not the specified point is inside this polygon.

Parameters: x the X coordinate of the point to test y the Y coordinate of the point to test

Returns: true if the point is inside this polygon

Since: 1.1

See Also: Polygon

contains

public boolean contains(double x, double y)

Tests whether or not the specified point is inside this polygon.

Parameters: x the X coordinate of the point to test y the Y coordinate of the point to test

Returns: true if the point is inside this polygon

Since: 1.2

contains

public boolean contains(Point2D p)

Tests whether or not the specified point is inside this polygon.

Parameters: p the point to test

Returns: true if the point is inside this polygon

Throws: NullPointerException if p is null

Since: 1.2

See Also: Polygon

contains

public boolean contains(double x, double y, double w, double h)

Test if a high-precision rectangle lies completely in the shape. This is true if all points in the rectangle are in the shape. This implementation is precise.

Parameters: x the x coordinate of the rectangle y the y coordinate of the rectangle w the width of the rectangle, treated as point if negative h the height of the rectangle, treated as point if negative

Returns: true if the rectangle is contained in this shape

Since: 1.2

contains

public boolean contains(Rectangle2D r)

Test if a high-precision rectangle lies completely in the shape. This is true if all points in the rectangle are in the shape. This implementation is precise.

Parameters: r the rectangle

Returns: true if the rectangle is contained in this shape

Throws: NullPointerException if r is null

Since: 1.2

See Also: Polygon

getBoundingBox

public Rectangle getBoundingBox()

Deprecated: use {@link #getBounds()} instead

Returns the bounding box of this polygon. This is the smallest rectangle with sides parallel to the X axis that will contain this polygon.

Returns: the bounding box for this polygon

getBounds

public Rectangle getBounds()

Returns the bounding box of this polygon. This is the smallest rectangle with sides parallel to the X axis that will contain this polygon.

Returns: the bounding box for this polygon

Since: 1.1

getBounds2D

public Rectangle2D getBounds2D()

Returns a high-precision bounding box of this polygon. This is the smallest rectangle with sides parallel to the X axis that will contain this polygon.

Returns: the bounding box for this polygon

Since: 1.2

getPathIterator

public PathIterator getPathIterator(AffineTransform transform)

Return an iterator along the shape boundary. If the optional transform is provided, the iterator is transformed accordingly. Each call returns a new object, independent from others in use. This class is not threadsafe to begin with, so the path iterator is not either.

Parameters: transform an optional transform to apply to the iterator

Returns: a new iterator over the boundary

Since: 1.2

getPathIterator

public PathIterator getPathIterator(AffineTransform transform, double flatness)

Return an iterator along the flattened version of the shape boundary. Since polygons are already flat, the flatness parameter is ignored, and the resulting iterator only has SEG_MOVETO, SEG_LINETO and SEG_CLOSE points. If the optional transform is provided, the iterator is transformed accordingly. Each call returns a new object, independent from others in use. This class is not threadsafe to begin with, so the path iterator is not either.

Parameters: transform an optional transform to apply to the iterator flatness the maximum distance for deviation from the real boundary

Returns: a new iterator over the boundary

Since: 1.2

inside

public boolean inside(int x, int y)

Deprecated: use {@link #contains(int, int)} instead

Tests whether or not the specified point is inside this polygon.

Parameters: x the X coordinate of the point to test y the Y coordinate of the point to test

Returns: true if the point is inside this polygon

See Also: Polygon

intersects

public boolean intersects(double x, double y, double w, double h)

Test if a high-precision rectangle intersects the shape. This is true if any point in the rectangle is in the shape. This implementation is precise.

Returns: true if the rectangle intersects this shape

Since: 1.2

intersects

public boolean intersects(Rectangle2D r)

Test if a high-precision rectangle intersects the shape. This is true if any point in the rectangle is in the shape. This implementation is precise.

Parameters: r the rectangle

Returns: true if the rectangle intersects this shape

Throws: NullPointerException if r is null

Since: 1.2

See Also: Polygon

invalidate

public void invalidate()

Invalidate or flush all cached data. After direct manipulation of the public member fields, this is necessary to avoid inconsistent results in methods like contains.

Since: 1.4

reset

public void reset()

Reset the polygon to be empty. The arrays are left alone, to avoid object allocation, but the number of points is set to 0, and all cached data is discarded. If you are discarding a huge number of points, it may be more efficient to just create a new Polygon.

Since: 1.4

translate

public void translate(int dx, int dy)

Translates the polygon by adding the specified values to all X and Y coordinates. This updates the bounding box, if it has been calculated.

Parameters: dx the amount to add to all X coordinates dy the amount to add to all Y coordinates

Since: 1.1