/*
* @(#)Shape.java 1.22 03/12/19
*
* Copyright 2004 Sun Microsystems, Inc. All rights reserved.
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*/
package java.awt;
import java.awt.geom.AffineTransform;
import java.awt.geom.PathIterator;
import java.awt.geom.Point2D;
import java.awt.geom.Rectangle2D;
/**
* The Shape
interface provides definitions for objects
* that represent some form of geometric shape. The Shape
* is described by a {@link PathIterator} object, which can express the
* outline of the Shape
as well as a rule for determining
* how the outline divides the 2D plane into interior and exterior
* points. Each Shape
object provides callbacks to get the
* bounding box of the geometry, determine whether points or
* rectangles lie partly or entirely within the interior
* of the Shape
, and retrieve a PathIterator
* object that describes the trajectory path of the Shape
* outline.
*
* Definition of insideness:
* A point is considered to lie inside a
* Shape
if and only if:
*
Shape
boundary or
* Shape
boundary and the
* space immediately adjacent to the
* point in the increasing X
direction is
* entirely inside the boundary or
* Y
direction is inside the boundary.
* The contains
and intersects
methods
* consider the interior of a Shape
to be the area it
* encloses as if it were filled. This means that these methods
* consider
* unclosed shapes to be implicitly closed for the purpose of
* determining if a shape contains or intersects a rectangle or if a
* shape contains a point.
*
* @see java.awt.geom.PathIterator
* @see java.awt.geom.AffineTransform
* @see java.awt.geom.FlatteningPathIterator
* @see java.awt.geom.GeneralPath
*
* @version 1.19 06/24/98
* @author Jim Graham
*/
public interface Shape {
/**
* Returns an integer {@link Rectangle} that completely encloses the
* Shape
. Note that there is no guarantee that the
* returned Rectangle
is the smallest bounding box that
* encloses the Shape
, only that the Shape
* lies entirely within the indicated Rectangle
. The
* returned Rectangle
might also fail to completely
* enclose the Shape
if the Shape
overflows
* the limited range of the integer data type. The
* getBounds2D
method generally returns a
* tighter bounding box due to its greater flexibility in
* representation.
* @return an integer Rectangle
that completely encloses
* the Shape
.
* @see #getBounds2D
*/
public Rectangle getBounds();
/**
* Returns a high precision and more accurate bounding box of
* the Shape
than the getBounds
method.
* Note that there is no guarantee that the returned
* {@link Rectangle2D} is the smallest bounding box that encloses
* the Shape
, only that the Shape
lies
* entirely within the indicated Rectangle2D
. The
* bounding box returned by this method is usually tighter than that
* returned by the getBounds
method and never fails due
* to overflow problems since the return value can be an instance of
* the Rectangle2D
that uses double precision values to
* store the dimensions.
* @return an instance of Rectangle2D
that is a
* high-precision bounding box of the Shape
.
* @see #getBounds
*/
public Rectangle2D getBounds2D();
/**
* Tests if the specified coordinates are inside the boundary of the
* Shape
.
* @param x the specified x coordinate
* @param y the specified y coordinate
* @return true
if the specified coordinates are inside
* the Shape
boundary; false
* otherwise.
*/
public boolean contains(double x, double y);
/**
* Tests if a specified {@link Point2D} is inside the boundary
* of the Shape
.
* @param p a specified Point2D
* @return true
if the specified Point2D
is
* inside the boundary of the Shape
;
* false
otherwise.
*/
public boolean contains(Point2D p);
/**
* Tests if the interior of the Shape
intersects the
* interior of a specified rectangular area.
* The rectangular area is considered to intersect the Shape
* if any point is contained in both the interior of the
* Shape
and the specified rectangular area.
*
* This method might conservatively return true
when:
*
Shape
intersect, but
* true
even
* though the rectangular area does not intersect the Shape
.
* The {@link java.awt.geom.Area Area} class can be used to perform
* more accurate computations of geometric intersection for any
* Shape
object if a more precise answer is required.
* @param x the x coordinate of the specified rectangular area
* @param y the y coordinate of the specified rectangular area
* @param w the width of the specified rectangular area
* @param h the height of the specified rectangular area
* @return true
if the interior of the Shape
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.
* @see java.awt.geom.Area
*/
public boolean intersects(double x, double y, double w, double h);
/**
* Tests if the interior of the Shape
intersects the
* interior of a specified Rectangle2D
.
* This method might conservatively return true
when:
* Rectangle2D
and the
* Shape
intersect, but
* true
even
* though the Rectangle2D
does not intersect the
* Shape
.
* @param r the specified Rectangle2D
* @return true
if the interior of the Shape
and
* the interior of the specified Rectangle2D
* intersect, or are both highly likely to intersect and intersection
* calculations would be too expensive to perform; false
* otherwise.
* @see #intersects(double, double, double, double)
*/
public boolean intersects(Rectangle2D r);
/**
* Tests if the interior of the Shape
entirely contains
* the specified rectangular area. All coordinates that lie inside
* the rectangular area must lie within the Shape
for the
* entire rectanglar area to be considered contained within the
* Shape
.
*
* This method might conservatively return false
when:
*
intersect
method returns true
and
* Shape
entirely contains the rectangular area are
* prohibitively expensive.
* false
even
* though the Shape
contains the rectangular area.
* The Area
class can be used to perform more accurate
* computations of geometric intersection for any Shape
* object if a more precise answer is required.
* @param x the x coordinate of the specified rectangular area
* @param y the y coordinate of the specified rectangular area
* @param w the width of the specified rectangular area
* @param h the height of the specified rectangular area
* @return true
if the interior of the Shape
* entirely contains the specified rectangular area;
* false
otherwise or, if the Shape
* contains the rectangular area and the
* intersects
method returns true
* and the containment calculations would be too expensive to
* perform.
* @see java.awt.geom.Area
* @see #intersects
*/
public boolean contains(double x, double y, double w, double h);
/**
* Tests if the interior of the Shape
entirely contains the
* specified Rectangle2D
.
* This method might conservatively return false
when:
* intersect
method returns true
and
* Shape
entirely contains the Rectangle2D
* are prohibitively expensive.
* false
even
* though the Shape
contains the
* Rectangle2D
.
* The Area
class can be used to perform more accurate
* computations of geometric intersection for any Shape
* object if a more precise answer is required.
* @param r The specified Rectangle2D
* @return true
if the interior of the Shape
* entirely contains the Rectangle2D
;
* false
otherwise or, if the Shape
* contains the Rectangle2D
and the
* intersects
method returns true
* and the containment calculations would be too expensive to
* perform.
* @see #contains(double, double, double, double)
*/
public boolean contains(Rectangle2D r);
/**
* Returns an iterator object that iterates along the
* Shape
boundary and provides access to the geometry of the
* Shape
outline. If an optional {@link AffineTransform}
* is specified, the coordinates returned in the iteration are
* transformed accordingly.
*
* Each call to this method returns a fresh PathIterator
* object that traverses the geometry of the Shape
object
* independently from any other PathIterator
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.
*
* Before using a particular implementation of the Shape
* interface in more than one thread simultaneously, refer to its
* documentation to verify that it guarantees that iterations are isolated
* from modifications.
* @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 a new PathIterator
object, which independently
* traverses the geometry of the Shape
.
*/
public PathIterator getPathIterator(AffineTransform at);
/**
* Returns an iterator object that iterates along the Shape
* boundary and provides access to a flattened view of the
* Shape
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 the Shape
object geometry
* independently from any other PathIterator
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.
*
* Before using a particular implementation of this interface in more
* than one thread simultaneously, refer to its documentation to
* verify that it guarantees that iterations are isolated from
* modifications.
* @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 distance that the line segments used to
* approximate the curved segments are allowed to deviate
* from any point on the original curve
* @return a new PathIterator
that independently traverses
* the Shape
geometry.
*/
public PathIterator getPathIterator(AffineTransform at, double flatness);
}