FileDocCategorySizeDatePackage
Area.javaAPI DocJava SE 6 API24795Tue Jun 10 00:25:26 BST 2008java.awt.geom

Area

public class Area extends Object implements Shape, Cloneable
An Area object stores and manipulates a resolution-independent description of an enclosed area of 2-dimensional space. Area objects can be transformed and can perform various Constructive Area Geometry (CAG) operations when combined with other Area objects. The CAG operations include area {@link #add addition}, {@link #subtract subtraction}, {@link #intersect intersection}, and {@link #exclusiveOr exclusive or}. See the linked method documentation for examples of the various operations.

The Area class implements the Shape interface and provides full support for all of its hit-testing and path iteration facilities, but an Area is more specific than a generalized path in a number of ways:

  • Only closed paths and sub-paths are stored. Area objects constructed from unclosed paths are implicitly closed during construction as if those paths had been filled by the Graphics2D.fill method.
  • The interiors of the individual stored sub-paths are all non-empty and non-overlapping. Paths are decomposed during construction into separate component non-overlapping parts, empty pieces of the path are discarded, and then these non-empty and non-overlapping properties are maintained through all subsequent CAG operations. Outlines of different component sub-paths may touch each other, as long as they do not cross so that their enclosed areas overlap.
  • The geometry of the path describing the outline of the Area resembles the path from which it was constructed only in that it describes the same enclosed 2-dimensional area, but may use entirely different types and ordering of the path segments to do so.
Interesting issues which are not always obvious when using the Area include:
  • Creating an Area from an unclosed (open) Shape results in a closed outline in the Area object.
  • Creating an Area from a Shape which encloses no area (even when "closed") produces an empty Area. A common example of this issue is that producing an Area from a line will be empty since the line encloses no area. An empty Area will iterate no geometry in its PathIterator objects.
  • A self-intersecting Shape may be split into two (or more) sub-paths each enclosing one of the non-intersecting portions of the original path.
  • An Area may take more path segments to describe the same geometry even when the original outline is simple and obvious. The analysis that the Area class must perform on the path may not reflect the same concepts of "simple and obvious" as a human being perceives.
since
1.2

Fields Summary
private static Vector
EmptyCurves
private Vector
curves
private Rectangle2D
cachedBounds
Constructors Summary
public Area()
Default constructor which creates an empty area.

since
1.2


                  
      
	curves = EmptyCurves;
public Area(Shape s)
The Area class creates an area geometry from the specified {@link Shape} object. The geometry is explicitly closed, if the Shape is not already closed. The fill rule (even-odd or winding) specified by the geometry of the Shape is used to determine the resulting enclosed area.

param
s the Shape from which the area is constructed
throws
NullPointerException if s is null
since
1.2

	if (s instanceof Area) {
	    curves = ((Area) s).curves;
	} else {
            curves = pathToCurves(s.getPathIterator(null));
        }
Methods Summary
public voidadd(java.awt.geom.Area rhs)
Adds the shape of the specified Area to the shape of this Area. The resulting shape of this Area will include the union of both shapes, or all areas that were contained in either this or the specified Area. 
// Example:
Area a1 = new Area([triangle 0,0 => 8,0 => 0,8]);
Area a2 = new Area([triangle 0,0 => 8,0 => 8,8]);
a1.add(a2);

a1(before) + a2 = a1(after)

################ ################ ################
############## ############## ################
############ ############ ################
########## ########## ################
######## ######## ################
###### ###### ###### ######
#### #### #### ####
## ## ## ##

param
rhs the Area to be added to the current shape
throws
NullPointerException if rhs is null
since
1.2

	curves = new AreaOp.AddOp().calculate(this.curves, rhs.curves);
	invalidateBounds();
public java.lang.Objectclone()
Returns an exact copy of this Area object.

return
Created clone object
since
1.2

	return new Area(this);
public booleancontains(double x, double y)
{@inheritDoc}

since
1.2

	if (!getCachedBounds().contains(x, y)) {
	    return false;
	}
	Enumeration enum_ = curves.elements();
	int crossings = 0;
	while (enum_.hasMoreElements()) {
	    Curve c = (Curve) enum_.nextElement();
	    crossings += c.crossingsFor(x, y);
	}
	return ((crossings & 1) == 1);
public booleancontains(java.awt.geom.Point2D p)
{@inheritDoc}

since
1.2

	return contains(p.getX(), p.getY());
public booleancontains(double x, double y, double w, double h)
{@inheritDoc}

since
1.2

	if (w < 0 || h < 0) {
	    return false;
	}
	if (!getCachedBounds().contains(x, y, w, h)) {
	    return false;
	}
	Crossings c = Crossings.findCrossings(curves, x, y, x+w, y+h);
	return (c != null && c.covers(y, y+h));
public booleancontains(java.awt.geom.Rectangle2D r)
{@inheritDoc}

since
1.2

	return contains(r.getX(), r.getY(), r.getWidth(), r.getHeight());
public java.awt.geom.AreacreateTransformedArea(java.awt.geom.AffineTransform t)
Creates a new Area object that contains the same geometry as this Area transformed by the specified AffineTransform. This Area object is unchanged.

param
t the specified AffineTransform used to transform the new Area
throws
NullPointerException if t is null
return
a new Area object representing the transformed geometry.
since
1.2

        Area a = new Area(this);
        a.transform(t);
        return a;
public booleanequals(java.awt.geom.Area other)
Tests whether the geometries of the two Area objects are equal. This method will return false if the argument is null.

param
other the Area to be compared to this Area
return
true if the two geometries are equal; false otherwise.
since
1.2

	// REMIND: A *much* simpler operation should be possible...
	// Should be able to do a curve-wise comparison since all Areas
	// should evaluate their curves in the same top-down order.
	if (other == this) {
	    return true;
	}
	if (other == null) {
	    return false;
	}
	Vector c = new AreaOp.XorOp().calculate(this.curves, other.curves);
	return c.isEmpty();
public voidexclusiveOr(java.awt.geom.Area rhs)
Sets the shape of this Area to be the combined area of its current shape and the shape of the specified Area, minus their intersection. The resulting shape of this Area will include only areas that were contained in either this Area or in the specified Area, but not in both. 
// Example:
Area a1 = new Area([triangle 0,0 => 8,0 => 0,8]);
Area a2 = new Area([triangle 0,0 => 8,0 => 8,8]);
a1.exclusiveOr(a2);

a1(before) xor a2 = a1(after)

################ ################
############## ############## ## ##
############ ############ #### ####
########## ########## ###### ######
######## ######## ################
###### ###### ###### ######
#### #### #### ####
## ## ## ##

param
rhs the Area to be exclusive ORed with this Area.
throws
NullPointerException if rhs is null
since
1.2

	curves = new AreaOp.XorOp().calculate(this.curves, rhs.curves);
	invalidateBounds();
public java.awt.RectanglegetBounds()
Returns a bounding {@link Rectangle} that completely encloses this Area.

The Area class will attempt to return the tightest bounding box possible for the Shape. The bounding box will not be padded to include the control points of curves in the outline of the Shape, but should tightly fit the actual geometry of the outline itself. Since the returned object represents the bounding box with integers, the bounding box can only be as tight as the nearest integer coordinates that encompass the geometry of the Shape.

return
the bounding Rectangle for the Area.
since
1.2

	return getCachedBounds().getBounds();
public java.awt.geom.Rectangle2DgetBounds2D()
Returns a high precision bounding {@link Rectangle2D} that completely encloses this Area.

The Area class will attempt to return the tightest bounding box possible for the Shape. The bounding box will not be padded to include the control points of curves in the outline of the Shape, but should tightly fit the actual geometry of the outline itself.

return
the bounding Rectangle2D for the Area.
since
1.2

	return getCachedBounds().getBounds2D();
private java.awt.geom.Rectangle2DgetCachedBounds()

	if (cachedBounds != null) {
	    return cachedBounds;
	}
	Rectangle2D r = new Rectangle2D.Double();
	if (curves.size() > 0) {
	    Curve c = (Curve) curves.get(0);
	    // First point is always an order 0 curve (moveto)
	    r.setRect(c.getX0(), c.getY0(), 0, 0);
	    for (int i = 1; i < curves.size(); i++) {
		((Curve) curves.get(i)).enlarge(r);
	    }
	}
	return (cachedBounds = r);
public java.awt.geom.PathIteratorgetPathIterator(java.awt.geom.AffineTransform at)
Creates a {@link PathIterator} for the outline of this Area object. This Area object is unchanged.

param
at an optional AffineTransform to be applied to the coordinates as they are returned in the iteration, or null if untransformed coordinates are desired
return
the PathIterator object that returns the geometry of the outline of this Area, one segment at a time.
since
1.2

	return new AreaIterator(curves, at);
public java.awt.geom.PathIteratorgetPathIterator(java.awt.geom.AffineTransform at, double flatness)
Creates a PathIterator for the flattened outline of this Area object. Only uncurved path segments represented by the SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are returned by the iterator. This Area object is unchanged.

param
at an optional AffineTransform to be applied to the coordinates as they are returned in the iteration, or null if untransformed coordinates are desired
param
flatness the maximum amount that the control points for a given curve can vary from colinear before a subdivided curve is replaced by a straight line connecting the end points
return
the PathIterator object that returns the geometry of the outline of this Area, one segment at a time.
since
1.2

	return new FlatteningPathIterator(getPathIterator(at), flatness);
public voidintersect(java.awt.geom.Area rhs)
Sets the shape of this Area to the intersection of its current shape and the shape of the specified Area. The resulting shape of this Area will include only areas that were contained in both this Area and also in the specified Area. 
// Example:
Area a1 = new Area([triangle 0,0 => 8,0 => 0,8]);
Area a2 = new Area([triangle 0,0 => 8,0 => 8,8]);
a1.intersect(a2);

a1(before) intersect a2 = a1(after)

################ ################ ################
############## ############## ############
############ ############ ########
########## ########## ####
######## ########
###### ######
#### ####
## ##

param
rhs the Area to be intersected with this Area
throws
NullPointerException if rhs is null
since
1.2

	curves = new AreaOp.IntOp().calculate(this.curves, rhs.curves);
	invalidateBounds();
public booleanintersects(double x, double y, double w, double h)
{@inheritDoc}

since
1.2

	if (w < 0 || h < 0) {
	    return false;
	}
	if (!getCachedBounds().intersects(x, y, w, h)) {
	    return false;
	}
	Crossings c = Crossings.findCrossings(curves, x, y, x+w, y+h);
	return (c == null || !c.isEmpty());
public booleanintersects(java.awt.geom.Rectangle2D r)
{@inheritDoc}

since
1.2

	return intersects(r.getX(), r.getY(), r.getWidth(), r.getHeight());
private voidinvalidateBounds()

	cachedBounds = null;
public booleanisEmpty()
Tests whether this Area object encloses any area.

return
true if this Area object represents an empty area; false otherwise.
since
1.2

	return (curves.size() == 0);
public booleanisPolygonal()
Tests whether this Area consists entirely of straight edged polygonal geometry.

return
true if the geometry of this Area consists entirely of line segments; false otherwise.
since
1.2

	Enumeration enum_ = curves.elements();
	while (enum_.hasMoreElements()) {
	    if (((Curve) enum_.nextElement()).getOrder() > 1) {
		return false;
	    }
	}
	return true;
public booleanisRectangular()
Tests whether this Area is rectangular in shape.

return
true if the geometry of this Area is rectangular in shape; false otherwise.
since
1.2

	int size = curves.size();
	if (size == 0) {
	    return true;
	}
	if (size > 3) {
	    return false;
	}
	Curve c1 = (Curve) curves.get(1);
	Curve c2 = (Curve) curves.get(2);
	if (c1.getOrder() != 1 || c2.getOrder() != 1) {
	    return false;
	}
	if (c1.getXTop() != c1.getXBot() || c2.getXTop() != c2.getXBot()) {
	    return false;
	}
	if (c1.getYTop() != c2.getYTop() || c1.getYBot() != c2.getYBot()) {
	    // One might be able to prove that this is impossible...
	    return false;
	}
	return true;
public booleanisSingular()
Tests whether this Area is comprised of a single closed subpath. This method returns true if the path contains 0 or 1 subpaths, or false if the path contains more than 1 subpath. The subpaths are counted by the number of {@link PathIterator#SEG_MOVETO SEG_MOVETO} segments that appear in the path.

return
true if the Area is comprised of a single basic geometry; false otherwise.
since
1.2

	if (curves.size() < 3) {
	    return true;
	}
	Enumeration enum_ = curves.elements();
	enum_.nextElement(); // First Order0 "moveto"
	while (enum_.hasMoreElements()) {
	    if (((Curve) enum_.nextElement()).getOrder() == 0) {
		return false;
	    }
	}
	return true;
private static java.util.VectorpathToCurves(java.awt.geom.PathIterator pi)

	Vector curves = new Vector();
	int windingRule = pi.getWindingRule();
	// coords array is big enough for holding:
	//     coordinates returned from currentSegment (6)
	//     OR
	//         two subdivided quadratic curves (2+4+4=10)
	//         AND
	//             0-1 horizontal splitting parameters
	//             OR
	//             2 parametric equation derivative coefficients
	//     OR
	//         three subdivided cubic curves (2+6+6+6=20)
	//         AND
	//             0-2 horizontal splitting parameters
	//             OR
	//             3 parametric equation derivative coefficients
	double coords[] = new double[23];
	double movx = 0, movy = 0;
	double curx = 0, cury = 0;
	double newx, newy;
	while (!pi.isDone()) {
	    switch (pi.currentSegment(coords)) {
	    case PathIterator.SEG_MOVETO:
		Curve.insertLine(curves, curx, cury, movx, movy);
		curx = movx = coords[0];
		cury = movy = coords[1];
		Curve.insertMove(curves, movx, movy);
		break;
	    case PathIterator.SEG_LINETO:
		newx = coords[0];
		newy = coords[1];
		Curve.insertLine(curves, curx, cury, newx, newy);
		curx = newx;
		cury = newy;
		break;
	    case PathIterator.SEG_QUADTO:
		newx = coords[2];
		newy = coords[3];
		Curve.insertQuad(curves, curx, cury, coords);
		curx = newx;
		cury = newy;
		break;
	    case PathIterator.SEG_CUBICTO:
		newx = coords[4];
		newy = coords[5];
		Curve.insertCubic(curves, curx, cury, coords);
		curx = newx;
		cury = newy;
		break;
	    case PathIterator.SEG_CLOSE:
		Curve.insertLine(curves, curx, cury, movx, movy);
		curx = movx;
		cury = movy;
		break;
	    }
	    pi.next();
	}
	Curve.insertLine(curves, curx, cury, movx, movy);
	AreaOp operator;
	if (windingRule == PathIterator.WIND_EVEN_ODD) {
	    operator = new AreaOp.EOWindOp();
	} else {
	    operator = new AreaOp.NZWindOp();
	}
	return operator.calculate(curves, EmptyCurves);
public voidreset()
Removes all of the geometry from this Area and restores it to an empty area.

since
1.2

	curves = new Vector();
	invalidateBounds();
public voidsubtract(java.awt.geom.Area rhs)
Subtracts the shape of the specified Area from the shape of this Area. The resulting shape of this Area will include areas that were contained only in this Area and not in the specified Area. 
// Example:
Area a1 = new Area([triangle 0,0 => 8,0 => 0,8]);
Area a2 = new Area([triangle 0,0 => 8,0 => 8,8]);
a1.subtract(a2);

a1(before) - a2 = a1(after)

################ ################
############## ############## ##
############ ############ ####
########## ########## ######
######## ######## ########
###### ###### ######
#### #### ####
## ## ##

param
rhs the Area to be subtracted from the current shape
throws
NullPointerException if rhs is null
since
1.2

	curves = new AreaOp.SubOp().calculate(this.curves, rhs.curves);
	invalidateBounds();
public voidtransform(java.awt.geom.AffineTransform t)
Transforms the geometry of this Area using the specified {@link AffineTransform}. The geometry is transformed in place, which permanently changes the enclosed area defined by this object.

param
t the transformation used to transform the area
throws
NullPointerException if t is null
since
1.2

        if (t == null) {
            throw new NullPointerException("transform must not be null");
        }
	// REMIND: A simpler operation can be performed for some types
	// of transform.
        curves = pathToCurves(getPathIterator(t));
	invalidateBounds();