Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Java Platform 1.2
Beta 4

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Interface java.awt.Shape

All Known Implementing Classes:

Polygon, RectangularShape, Rectangle, Line2D, CubicCurve2D, Area, GeneralPath, QuadCurve2D

public abstract interface Shape

The interface for objects which represent some form of geometric shape. The shape is described by a 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, to determine whether points or rectangles lie partly or entirely within the interior of the shape and to retrieve a PathIterator object to describe the trajectory path of the outline of the shape.

Definition of insideness:

A point is considered to lie inside a Shape if it lies completely inside the boundary of the Shape, or if it lies exactly on the boundary of the Shape and the space immediately adjacent to the point in the increasing X direction is entirely inside the boundary, or if it lies exactly on a horizontal boundary segment and the space immediately adjacent to the point in the increasing Y direction is inside the boundary.

See Also:

PathIterator, AffineTransform, FlatteningPathIterator, GeneralPath

Method Summary

boolean	contains(double x, double y, double w, double h) Tests if the interior of the Shape entirely contains the given rectangular area.
boolean	contains(double x, double y) Tests if a given coordinate is inside the boundary of the shape.
boolean	contains(Point2D p) Tests if a given Point is inside the boundary of the shape.
boolean	contains(Rectangle2D r) Test if the interior of the Shape entirely contains the given Rectangle.
Rectangle	getBounds() Returns an integer Rectangle which completely encloses the Shape.
Rectangle2D	getBounds2D() Returns a high precision and more accurate bounding box of the Shape than the getBounds method.
PathIterator	getPathIterator(AffineTransform at, double flatness) Return an iterator object that iterates along the boundary of the shape and provides access to a flattened view of the geometry of the outline of the shape.
PathIterator	getPathIterator(AffineTransform at) Return an iterator object that iterates along the boundary of the shape and provides access to the geometry of the outline of the shape.
boolean	intersects(double x, double y, double w, double h) Tests if the interior of the Shape intersects the interior of a given rectangular area.
boolean	intersects(Rectangle2D r) Tests if the interior of the Shape intersects the interior of a given Rectangle.

Method Detail

getBounds

public Rectangle getBounds()

Returns an integer Rectangle which 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 may also fail to completely enclose the Shape if the Shape overflows the limited range of the integer data type. The getBounds2D method will generally return a tighter bounding box due to its greater flexibility in representation.

See Also:

getBounds2D()

getBounds2D

public Rectangle2D getBounds2D()

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 rectangle is the smallest bounding box that encloses the Shape, only that the Shape lies entirely within the indicated Rectangle. The bounding box returned by this method will generally be tighter than that returned by the getBounds method and will never fail due to overflow problems since the return value can be an instance of Rectangle2D which uses double precision values to store the dimensions.

See Also:

getBounds()

contains

public boolean contains(double x,
                        double y)

Tests if a given coordinate is inside the boundary of the shape.

contains

public boolean contains(Point2D p)

Tests if a given Point is inside the boundary of the shape.

intersects

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

Tests if the interior of the Shape intersects the interior of a given 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 may conservatively return true when the Shape and the rectangle do not actually overlap if there is a high probability that there is an intersection and the calculations to more accurately detect the intersection would be prohibitively expensive. 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.

See Also:

Area

intersects

public boolean intersects(Rectangle2D r)

Tests if the interior of the Shape intersects the interior of a given Rectangle.

See Also:

intersects(double, double, double, double)

contains

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

Tests if the interior of the Shape entirely contains the given rectangular area. All coordinates that lie inside the rectangular area must lie within the Shape for the rectangle to be considered contained in the Shape.

This method may conservatively return false when the rectangle is actually contained entirely within the Shape as long as the intersects method returns true in that case and the calculations to more accurately detect the containment would be prohibitively expensive. 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.

See Also:

Area, intersects(double, double, double, double)

contains

public boolean contains(Rectangle2D r)

Test if the interior of the Shape entirely contains the given Rectangle.

See Also:

contains(double, double, double, double)

getPathIterator

public PathIterator getPathIterator(AffineTransform at)

Return an iterator object that iterates along the boundary of the shape and provides access to the geometry of the outline of the shape. An optional affine transform can be specified in which case the coordinates returned in the iteration will be transformed accordingly.

Each call to this method will return a fresh PathIterator object that will traverse 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 which implement the Shape interface attempt to isolate the iterations that are in process from any changes that occur to the original object's geometry should the geometry be modified while such an iteration is taking place. Consult the documentation for a given geometry object that implements this interface to see if it provides any guarantees about the isolation of iterations from modifications before using such an object in more than one thread at the same time.

Parameters:

at - an optional AffineTransform to be applied to the coordinates as they are returned in the iteration, or null if the untransformed coordinates are desired.

getPathIterator

public PathIterator getPathIterator(AffineTransform at,
                                    double flatness)

Return an iterator object that iterates along the boundary of the shape and provides access to a flattened view of the geometry of the outline of the shape. An optional affine transform can be specified in which case the coordinates returned in the iteration will be 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 is allowed to deviate from the flattened path segments that are returned. Note that there may be a silently imposed limit on the accuracy of the flattened path which will cause very small flattening parameters to be be treated as a larger value defined by the implementation. Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types will be returned by the iterator.

Each call to this method will return a fresh PathIterator object that will traverse 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 which implement the Shape interface attempt to isolate the iterations that are in process from any changes that occur to the original object's geometry should the geometry be modified while such an iteration is taking place. Consult the documentation for a given geometry object that implements this interface to see if it provides any guarantees about the isolation of iterations from modifications before using such an object in more than one thread at the same time.

Parameters:

at - an optional AffineTransform to be applied to the coordinates as they are returned in the iteration, or null if the 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 endpoints.