java.awt.geom

Class Area

public class Area extends Object implements Shape, Cloneable

The Area class represents any area for the purpose of Constructive Area Geometry (CAG) manipulations. CAG manipulations work as an area-wise form of boolean logic, where the basic operations are:

Add (in boolean algebra: A or B)

Subtract (in boolean algebra: A and (not B) )

Intersect (in boolean algebra: A and B)

Exclusive Or
Illustration of CAG operations

Above is an illustration of the CAG operations on two ring shapes.

The contains and intersects() methods are also more accurate than the specification of #Shape requires.

Please note that constructing an Area can be slow (Self-intersection resolving is proportional to the square of the number of segments).

Since: 1.2

See Also: add subtract intersect

UNKNOWN: Works, but could be faster and more reliable.

Constructor Summary
	Area() Constructs an empty Area
	Area(Shape s) Constructs an Area from any given Shape.

Method Summary
void	add(Area area) Performs an add (union) operation on this area with another Area.
Object	clone() Create a new area of the same run-time type with the same contents as this one.
boolean	contains(double x, double y) Determines if the point (x,y) is contained within this Area.
boolean	contains(Point2D p) Determines if the Point2D p is contained within this Area.
boolean	contains(double x, double y, double w, double h) Determines if the rectangle specified by (x,y) as the upper-left and with width w and height h is completely contained within this Area, returns false otherwise. This method should always produce the correct results, unlike for other classes in geom.
boolean	contains(Rectangle2D r) Determines if the Rectangle2D specified by r is completely contained within this Area, returns false otherwise. This method should always produce the correct results, unlike for other classes in geom.
Area	createTransformedArea(AffineTransform at) Returns a new Area equal to this one, transformed by the AffineTransform at.
boolean	equals(Area area) Compares two Areas.
void	exclusiveOr(Area area) Performs an exclusive-or operation on this Area.
Rectangle	getBounds() Returns the bounds of this object in Rectangle format.
Rectangle2D	getBounds2D() Returns the bounding box of the Area. Unlike the CubicCurve2D and QuadraticCurve2D classes, this method will return the tightest possible bounding box, evaluating the extreme points of each curved segment.
PathIterator	getPathIterator(AffineTransform at) Returns a PathIterator object defining the contour of this Area, transformed by at.
PathIterator	getPathIterator(AffineTransform at, double flatness) Returns a flattened PathIterator object defining the contour of this Area, transformed by at and with a defined flatness.
void	intersect(Area area) Performs an intersection operation on this Area.
boolean	intersects(double x, double y, double w, double h) Determines if the rectangle specified by (x,y) as the upper-left and with width w and height h intersects any part of this Area.
boolean	intersects(Rectangle2D r) Determines if the Rectangle2D specified by r intersects any part of this Area.
boolean	isEmpty() Returns whether this area encloses any area.
boolean	isPolygonal() Determines whether the Area consists entirely of line segments
boolean	isRectangular() Determines if the Area is rectangular. This is strictly qualified.
boolean	isSingular() Returns whether the Area consists of more than one simple (non self-intersecting) subpath.
void	reset() Clears the Area object, creating an empty area.
void	subtract(Area area) Performs a subtraction operation on this Area.
void	transform(AffineTransform at) Transforms this area by the AffineTransform at.

Constructor Detail

Area

public Area(Shape s)

Constructs an Area from any given Shape.

If the Shape is self-intersecting, the created Area will consist of non-self-intersecting subpaths, and any inner paths which are found redundant in accordance with the Shape's winding rule will not be included.

Parameters: s the shape (null not permitted).

Throws: NullPointerException if s is null.

Method Detail

add

public void add(Area area)

Performs an add (union) operation on this area with another Area.

Parameters: area - the area to be unioned with this one

clone

public Object clone()

Create a new area of the same run-time type with the same contents as this one.

Returns: the clone

contains

public boolean contains(double x, double y)

Determines if the point (x,y) is contained within this Area.

Parameters: x the x-coordinate of the point. y the y-coordinate of the point.

Returns: true if the point is contained, false otherwise.

contains

public boolean contains(Point2D p)

Determines if the Point2D p is contained within this Area.

Parameters: p the point.

Returns: true if the point is contained, false otherwise.

Throws: NullPointerException if p is null.

contains

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

Determines if the rectangle specified by (x,y) as the upper-left and with width w and height h is completely contained within this Area, returns false otherwise.

This method should always produce the correct results, unlike for other classes in geom.

Parameters: x the x-coordinate of the rectangle. y the y-coordinate of the rectangle. w the width of the the rectangle. h the height of the rectangle.

Returns: true if the rectangle is considered contained

contains

public boolean contains(Rectangle2D r)

Determines if the Rectangle2D specified by r is completely contained within this Area, returns false otherwise.

This method should always produce the correct results, unlike for other classes in geom.

Parameters: r the rectangle.

Returns: true if the rectangle is considered contained

Throws: NullPointerException if r is null.

createTransformedArea

public Area createTransformedArea(AffineTransform at)

Returns a new Area equal to this one, transformed by the AffineTransform at.

Parameters: at the transform.

Returns: the transformed area

Throws: NullPointerException if at is null.

equals

public boolean equals(Area area)

Compares two Areas.

Parameters: area the area to compare against this area (null permitted).

Returns: true if the areas are equal, and false otherwise.

exclusiveOr

public void exclusiveOr(Area area)

Performs an exclusive-or operation on this Area.

Parameters: area - the area to be XORed with this area.

Throws: NullPointerException if area is null.

getBounds

public Rectangle getBounds()

Returns the bounds of this object in Rectangle format. Please note that this may lead to loss of precision.

Returns: The bounds.

getBounds2D

public Rectangle2D getBounds2D()

Returns the bounding box of the Area.

Unlike the CubicCurve2D and QuadraticCurve2D classes, this method will return the tightest possible bounding box, evaluating the extreme points of each curved segment.

Returns: the bounding box

getPathIterator

public PathIterator getPathIterator(AffineTransform at)

Returns a PathIterator object defining the contour of this Area, transformed by at.

Parameters: at the transform.

Returns: A path iterator.

getPathIterator

public PathIterator getPathIterator(AffineTransform at, double flatness)

Returns a flattened PathIterator object defining the contour of this Area, transformed by at and with a defined flatness.

Parameters: at the transform. flatness the flatness.

Returns: A path iterator.

intersect

public void intersect(Area area)

Performs an intersection operation on this Area.

Parameters: area - the area to be intersected with this area.

Throws: NullPointerException if area is null.

intersects

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

Determines if the rectangle specified by (x,y) as the upper-left and with width w and height h intersects any part of this Area.

Parameters: x the x-coordinate for the rectangle. y the y-coordinate for the rectangle. w the width of the rectangle. h the height of the rectangle.

Returns: true if the rectangle intersects the area, false otherwise.

intersects

public boolean intersects(Rectangle2D r)

Determines if the Rectangle2D specified by r intersects any part of this Area.

Parameters: r the rectangle to test intersection with (null not permitted).

Returns: true if the rectangle intersects the area, false otherwise.

Throws: NullPointerException if r is null.

isEmpty

public boolean isEmpty()

Returns whether this area encloses any area.

Returns: true if the object encloses any area.

isPolygonal

public boolean isPolygonal()

Determines whether the Area consists entirely of line segments

Returns: true if the Area lines-only, false otherwise

isRectangular

public boolean isRectangular()

Determines if the Area is rectangular.

This is strictly qualified. An area is considered rectangular if:

It consists of a single polygonal path.

It is oriented parallel/perpendicular to the xy axis

It must be exactly rectangular, i.e. small errors induced by transformations may cause a false result, although the area is visibly rectangular.

Returns: true if the above criteria are met, false otherwise

isSingular

public boolean isSingular()

Returns whether the Area consists of more than one simple (non self-intersecting) subpath.

Returns: true if the Area consists of none or one simple subpath, false otherwise.

reset

public void reset()

Clears the Area object, creating an empty area.

subtract

public void subtract(Area area)

Performs a subtraction operation on this Area.

Parameters: area the area to be subtracted from this area.

Throws: NullPointerException if area is null.

transform

public void transform(AffineTransform at)

Transforms this area by the AffineTransform at.

Parameters: at the transform.