Class Area

java.lang.Object
java.awt.geom.Area
All Implemented Interfaces:
Shape,Cloneable
public classAreaextendsObjectimplementsShape,Cloneable
AnArea 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 otherArea objects. The CAG operations include areaaddition,subtraction,intersection, andexclusive or. See the linked method documentation for examples of the various operations.

TheArea class implements theShape interface and provides full support for all of its hit-testing and path iteration facilities, but anArea 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 theGraphics2D.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 theArea 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 theArea include:
  • Creating anArea from an unclosed (open)Shape results in a closed outline in theArea object.
  • Creating anArea from aShape which encloses no area (even when "closed") produces an emptyArea. A common example of this issue is that producing anArea from a line will be empty since the line encloses no area. An emptyArea will iterate no geometry in itsPathIterator objects.
  • A self-intersectingShape may be split into two (or more) sub-paths each enclosing one of the non-intersecting portions of the original path.
  • AnArea may take more path segments to describe the same geometry even when the original outline is simple and obvious. The analysis that theArea class must perform on the path may not reflect the same concepts of "simple and obvious" as a human being perceives.

Since:
1.2

  • Constructor Summary

    Constructors
    Constructor
    Description
    Default constructor which creates an empty area.
    TheArea class creates an area geometry from the specifiedShape object.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(Area rhs)
    Adds the shape of the specifiedArea to the shape of thisArea.
    Returns an exact copy of thisArea object.
    boolean
    contains(double x, double y)
    Tests if the specified coordinates are inside the boundary of theShape, as described by thedefinition of insideness.
    boolean
    contains(double x, double y, double w, double h)
    Tests if the interior of theShape entirely contains the specified rectangular area.
    boolean
    Tests if a specifiedPoint2D is inside the boundary of theShape, as described by the definition of insideness.
    boolean
    Tests if the interior of theShape entirely contains the specifiedRectangle2D.
    Creates a newArea object that contains the same geometry as thisArea transformed by the specifiedAffineTransform.
    boolean
    equals(Area other)
    Tests whether the geometries of the twoArea objects are equal.
    void
    Sets the shape of thisArea to be the combined area of its current shape and the shape of the specifiedArea, minus their intersection.
    Returns a boundingRectangle that completely encloses thisArea.
    Returns a high precision boundingRectangle2D that completely encloses thisArea.
    Creates aPathIterator for the outline of thisArea object.
    getPathIterator(AffineTransform at, double flatness)
    Creates aPathIterator for the flattened outline of thisArea object.
    void
    Sets the shape of thisArea to the intersection of its current shape and the shape of the specifiedArea.
    boolean
    intersects(double x, double y, double w, double h)
    Tests if the interior of theShape intersects the interior of a specified rectangular area.
    boolean
    Tests if the interior of theShape intersects the interior of a specifiedRectangle2D.
    boolean
    Tests whether thisArea object encloses any area.
    boolean
    Tests whether thisArea consists entirely of straight edged polygonal geometry.
    boolean
    Tests whether thisArea is rectangular in shape.
    boolean
    Tests whether thisArea is comprised of a single closed subpath.
    void
    Removes all of the geometry from thisArea and restores it to an empty area.
    void
    Subtracts the shape of the specifiedArea from the shape of thisArea.
    void
    Transforms the geometry of thisArea using the specifiedAffineTransform.

  • Constructor Details

    • Area

      public Area()
      Default constructor which creates an empty area.
      Since:
      1.2

    • Area

      public Area(Shape s)
      TheArea class creates an area geometry from the specifiedShape object. The geometry is explicitly closed, if theShape is not already closed. The fill rule (even-odd or winding) specified by the geometry of theShape is used to determine the resulting enclosed area.
      Parameters:
      s - theShape from which the area is constructed
      Throws:
      NullPointerException - ifs is null
      Since:
      1.2

  • Method Details

    • add

      public void add(Area rhs)
      Adds the shape of the specifiedArea to the shape of thisArea. The resulting shape of thisArea will include the union of both shapes, or all areas that were contained in either this or the specifiedArea.
           // 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)     ################     ################     ################     ##############         ##############     ################     ############             ############     ################     ##########                 ##########     ################     ########                     ########     ################     ######                         ######     ######    ######     ####                             ####     ####        ####     ##                                 ##     ##            ##
      Parameters:
      rhs - theArea to be added to the current shape
      Throws:
      NullPointerException - ifrhs is null
      Since:
      1.2

    • subtract

      public void subtract(Area rhs)
      Subtracts the shape of the specifiedArea from the shape of thisArea. The resulting shape of thisArea will include areas that were contained only in thisArea and not in the specifiedArea.
           // 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)     ################     ################     ##############         ##############     ##     ############             ############     ####     ##########                 ##########     ######     ########                     ########     ########     ######                         ######     ######     ####                             ####     ####     ##                                 ##     ##
      Parameters:
      rhs - theArea to be subtracted from the current shape
      Throws:
      NullPointerException - ifrhs is null
      Since:
      1.2

    • intersect

      public void intersect(Area rhs)
      Sets the shape of thisArea to the intersection of its current shape and the shape of the specifiedArea. The resulting shape of thisArea will include only areas that were contained in both thisArea and also in the specifiedArea.
           // 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)     ################     ################     ################     ##############         ##############       ############     ############             ############         ########     ##########                 ##########           ####     ########                     ########     ######                         ######     ####                             ####     ##                                 ##
      Parameters:
      rhs - theArea to be intersected with thisArea
      Throws:
      NullPointerException - ifrhs is null
      Since:
      1.2

    • exclusiveOr

      public void exclusiveOr(Area rhs)
      Sets the shape of thisArea to be the combined area of its current shape and the shape of the specifiedArea, minus their intersection. The resulting shape of thisArea will include only areas that were contained in either thisArea or in the specifiedArea, 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)     ################     ################     ##############         ##############     ##            ##     ############             ############     ####        ####     ##########                 ##########     ######    ######     ########                     ########     ################     ######                         ######     ######    ######     ####                             ####     ####        ####     ##                                 ##     ##            ##
      Parameters:
      rhs - theArea to be exclusive ORed with thisArea.
      Throws:
      NullPointerException - ifrhs is null
      Since:
      1.2

    • reset

      public void reset()
      Removes all of the geometry from thisArea and restores it to an empty area.
      Since:
      1.2

    • isEmpty

      public boolean isEmpty()
      Tests whether thisArea object encloses any area.
      Returns:
      true if thisArea object represents an empty area;false otherwise.
      Since:
      1.2

    • isPolygonal

      public boolean isPolygonal()
      Tests whether thisArea consists entirely of straight edged polygonal geometry.
      Returns:
      true if the geometry of thisArea consists entirely of line segments;false otherwise.
      Since:
      1.2

    • isRectangular

      public boolean isRectangular()
      Tests whether thisArea is rectangular in shape.
      Returns:
      true if the geometry of thisArea is rectangular in shape;false otherwise.
      Since:
      1.2

    • isSingular

      public boolean isSingular()
      Tests whether thisArea is comprised of a single closed subpath. This method returnstrue if the path contains 0 or 1 subpaths, orfalse if the path contains more than 1 subpath. The subpaths are counted by the number ofSEG_MOVETO segments that appear in the path.
      Returns:
      true if theArea is comprised of a single basic geometry;false otherwise.
      Since:
      1.2

    • getBounds2D

      public Rectangle2D getBounds2D()
      Returns a high precision boundingRectangle2D that completely encloses thisArea.

      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.

      Specified by:
      getBounds2D in interface Shape
      Returns:
      the boundingRectangle2D for theArea.
      Since:
      1.2
      See Also:

    • getBounds

      public Rectangle getBounds()
      Returns a boundingRectangle that completely encloses thisArea.

      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.

      Specified by:
      getBounds in interface Shape
      Returns:
      the boundingRectangle for theArea.
      Since:
      1.2
      See Also:

    • clone

      public Object clone()
      Returns an exact copy of thisArea object.
      Overrides:
      clone in class Object
      Returns:
      Created clone object
      Since:
      1.2
      See Also:

    • equals

      public boolean equals(Area other)
      Tests whether the geometries of the twoArea objects are equal. This method will return false if the argument is null.
      Parameters:
      other - theArea to be compared to thisArea
      Returns:
      true if the two geometries are equal;false otherwise.
      Since:
      1.2

    • transform

      public void transform(AffineTransform t)
      Transforms the geometry of thisArea using the specifiedAffineTransform. The geometry is transformed in place, which permanently changes the enclosed area defined by this object.
      Parameters:
      t - the transformation used to transform the area
      Throws:
      NullPointerException - ift is null
      Since:
      1.2

    • createTransformedArea

      public Area createTransformedArea(AffineTransform t)
      Creates a newArea object that contains the same geometry as thisArea transformed by the specifiedAffineTransform. ThisArea object is unchanged.
      Parameters:
      t - the specifiedAffineTransform used to transform the newArea
      Returns:
      a newArea object representing the transformed geometry.
      Throws:
      NullPointerException - ift is null
      Since:
      1.2

    • contains

      public boolean contains(double x, double y)
      Tests if the specified coordinates are inside the boundary of theShape, as described by thedefinition of insideness.
      Specified by:
      contains in interface Shape
      Parameters:
      x - the specified X coordinate to be tested
      y - the specified Y coordinate to be tested
      Returns:
      true if the specified coordinates are inside theShape boundary;false otherwise.
      Since:
      1.2

    • contains

      public boolean contains(Point2D p)
      Tests if a specifiedPoint2D is inside the boundary of theShape, as described by the definition of insideness.
      Specified by:
      contains in interface Shape
      Parameters:
      p - the specifiedPoint2D to be tested
      Returns:
      true if the specifiedPoint2D is inside the boundary of theShape;false otherwise.
      Since:
      1.2

    • contains

      public 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.

      TheShape.contains() method allows aShape implementation to conservatively returnfalse when:

      • theintersect method returnstrue and
      • the calculations to determine whether or not theShape entirely contains the rectangular area are prohibitively expensive.
      This means that for someShapes 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.

      Specified by:
      contains in interface Shape
      Parameters:
      x - the X coordinate of the upper-left corner of the specified rectangular area
      y - the Y coordinate of the upper-left corner of the specified rectangular area
      w - the width of the specified rectangular area
      h - 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.2
      See Also:

    • contains

      public boolean contains(Rectangle2D r)
      Tests if the interior of theShape entirely contains the specifiedRectangle2D. TheShape.contains() method allows aShape implementation to conservatively returnfalse when:
      • theintersect method returnstrue and
      • the calculations to determine whether or not theShape entirely contains theRectangle2D are prohibitively expensive.
      This means that for someShapes 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.
      Specified by:
      contains in interface Shape
      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.2
      See Also:

    • intersects

      public 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.

      TheShape.intersects() method allows aShape implementation to conservatively returntrue when:

      • there is a high probability that the rectangular area and theShape intersect, but
      • the calculations to accurately determine this intersection are prohibitively expensive.
      This means that for someShapes 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.

      Specified by:
      intersects in interface Shape
      Parameters:
      x - the X coordinate of the upper-left corner of the specified rectangular area
      y - the Y coordinate of the upper-left corner of the specified rectangular area
      w - the width of the specified rectangular area
      h - 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.2
      See Also:

    • intersects

      public boolean intersects(Rectangle2D r)
      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 theRectangle2D and theShape intersect, but
      • the calculations to accurately determine this intersection are prohibitively expensive.
      This means that for someShapes 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.
      Specified by:
      intersects in interface Shape
      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.2
      See Also:

    • getPathIterator

      public PathIterator getPathIterator(AffineTransform at)
      Creates aPathIterator for the outline of thisArea object. ThisArea object is unchanged.
      Specified by:
      getPathIterator in interface Shape
      Parameters:
      at - an optionalAffineTransform to be applied to the coordinates as they are returned in the iteration, ornull if untransformed coordinates are desired
      Returns:
      thePathIterator object that returns the geometry of the outline of thisArea, one segment at a time.
      Since:
      1.2

    • getPathIterator

      public PathIterator getPathIterator(AffineTransform at, double flatness)
      Creates aPathIterator for the flattened outline of thisArea object. Only uncurved path segments represented by the SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are returned by the iterator. ThisArea object is unchanged.
      Specified by:
      getPathIterator in interface Shape
      Parameters:
      at - an optionalAffineTransform to be applied to the coordinates as they are returned in the iteration, ornull if untransformed coordinates are desired
      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
      Returns:
      thePathIterator object that returns the geometry of the outline of thisArea, one segment at a time.
      Since:
      1.2