* Definition of insideness: * A point is considered to lie inside a * {@code Shape} if and only if: *
The {@code contains} and {@code intersects} methods * consider the interior of a {@code 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 * * @author Jim Graham * @since 1.2 */ public interface Shape { /** * Returns an integer {@link Rectangle} that completely encloses the * {@code Shape}. Note that there is no guarantee that the * returned {@code Rectangle} is the smallest bounding box that * encloses the {@code Shape}, only that the {@code Shape} * lies entirely within the indicated {@code Rectangle}. The * returned {@code Rectangle} might also fail to completely * enclose the {@code Shape} if the {@code Shape} overflows * the limited range of the integer data type. The * {@code getBounds2D} method generally returns a * tighter bounding box due to its greater flexibility in * representation. * *
* Note that the * definition of insideness can lead to situations where points * on the defining outline of the {@code shape} may not be considered * contained in the returned {@code bounds} object, but only in cases * where those points are also not considered contained in the original * {@code shape}. *
** If a {@code point} is inside the {@code shape} according to the * {@link #contains(double x, double y) contains(point)} method, then * it must be inside the returned {@code Rectangle} bounds object * according to the {@link #contains(double x, double y) contains(point)} * method of the {@code bounds}. Specifically: *
** {@code shape.contains(x,y)} requires {@code bounds.contains(x,y)} *
** If a {@code point} is not inside the {@code shape}, then it might * still be contained in the {@code bounds} object: *
** {@code bounds.contains(x,y)} does not imply {@code shape.contains(x,y)} *
* @return an integer {@code Rectangle} that completely encloses * the {@code Shape}. * @see #getBounds2D * @since 1.2 */ public Rectangle getBounds(); /** * Returns a high precision and more accurate bounding box of * the {@code Shape} than the {@code getBounds} method. * Note that there is no guarantee that the returned * {@link Rectangle2D} is the smallest bounding box that encloses * the {@code Shape}, only that the {@code Shape} lies * entirely within the indicated {@code Rectangle2D}. The * bounding box returned by this method is usually tighter than that * returned by the {@code getBounds} method and never fails due * to overflow problems since the return value can be an instance of * the {@code Rectangle2D} that uses double precision values to * store the dimensions. * ** Note that the * definition of insideness can lead to situations where points * on the defining outline of the {@code shape} may not be considered * contained in the returned {@code bounds} object, but only in cases * where those points are also not considered contained in the original * {@code shape}. *
** If a {@code point} is inside the {@code shape} according to the * {@link #contains(Point2D p) contains(point)} method, then it must * be inside the returned {@code Rectangle2D} bounds object according * to the {@link #contains(Point2D p) contains(point)} method of the * {@code bounds}. Specifically: *
** {@code shape.contains(p)} requires {@code bounds.contains(p)} *
** If a {@code point} is not inside the {@code shape}, then it might * still be contained in the {@code bounds} object: *
** {@code bounds.contains(p)} does not imply {@code shape.contains(p)} *
* @return an instance of {@code Rectangle2D} that is a * high-precision bounding box of the {@code Shape}. * @see #getBounds * @since 1.2 */ public Rectangle2D getBounds2D(); /** * Tests if the specified coordinates are inside the boundary of the * {@code Shape}, as described by the * * definition of insideness. * @param x the specified X coordinate to be tested * @param y the specified Y coordinate to be tested * @return {@code true} if the specified coordinates are inside * the {@code Shape} boundary; {@code false} * otherwise. * @since 1.2 */ public boolean contains(double x, double y); /** * Tests if a specified {@link Point2D} is inside the boundary * of the {@code Shape}, as described by the * * definition of insideness. * @param p the specified {@code Point2D} to be tested * @return {@code true} if the specified {@code Point2D} is * inside the boundary of the {@code Shape}; * {@code false} otherwise. * @since 1.2 */ public boolean contains(Point2D p); /** * Tests if the interior of the {@code Shape} intersects the * interior of a specified rectangular area. * The rectangular area is considered to intersect the {@code Shape} * if any point is contained in both the interior of the * {@code Shape} and the specified rectangular area. ** The {@code Shape.intersects()} method allows a {@code Shape} * implementation to conservatively return {@code true} when: *
* The {@code Shape.contains()} method allows a {@code Shape} * implementation to conservatively return {@code false} when: *
* Each call to this method returns a fresh {@code PathIterator} * object that traverses the geometry of the {@code Shape} object * independently from any other {@code PathIterator} objects in use * at the same time. *
* It is recommended, but not guaranteed, that objects * implementing the {@code Shape} interface isolate iterations * that are in process from any changes that might occur to the original * object's geometry during such iterations. * * @param at an optional {@code AffineTransform} to be applied to the * coordinates as they are returned in the iteration, or * {@code null} if untransformed coordinates are desired * @return a new {@code PathIterator} object, which independently * traverses the geometry of the {@code Shape}. * @since 1.2 */ public PathIterator getPathIterator(AffineTransform at); /** * Returns an iterator object that iterates along the {@code Shape} * boundary and provides access to a flattened view of the * {@code Shape} outline geometry. *
* Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are * returned by the iterator. *
* If an optional {@code AffineTransform} is specified, * the coordinates returned in the iteration are transformed * accordingly. *
* The amount of subdivision of the curved segments is controlled * by the {@code 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 {@code PathIterator} * object that traverses the {@code Shape} object geometry * independently from any other {@code PathIterator} objects in use at * the same time. *
* It is recommended, but not guaranteed, that objects * implementing the {@code Shape} interface isolate iterations * that are in process from any changes that might occur to the original * object's geometry during such iterations. * * @param at an optional {@code AffineTransform} to be applied to the * coordinates as they are returned in the iteration, or * {@code 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 {@code PathIterator} that independently traverses * a flattened view of the geometry of the {@code Shape}. * @since 1.2 */ public PathIterator getPathIterator(AffineTransform at, double flatness); }