/* * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.awt; import java.awt.geom.AffineTransform;import java.awt.geom.PathIterator;import java.awt.geom.Point2D;import java.awt.geom.Rectangle2D; /** * The <code>Shape</code> interface provides definitions for objects * that represent some form of geometric shape.  The <code>Shape</code> * is described by a {@link PathIterator} object, which can express the * outline of the <code>Shape</code> as well as a rule for determining * how the outline divides the 2D plane into interior and exterior * points.  Each <code>Shape</code> 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 <code>Shape</code>, and retrieve a <code>PathIterator</code> * object that describes the trajectory path of the <code>Shape</code> * outline. * <p> * <a name="def_insideness"><b>Definition of insideness:</b></a> * A point is considered to lie inside a * <code>Shape</code> if and only if: * <ul> * <li> it lies completely * inside the<code>Shape</code> boundary <i>or</i> * <li> * it lies exactly on the <code>Shape</code> boundary <i>and</i> the * space immediately adjacent to the * point in the increasing <code>X</code> direction is * entirely inside the boundary <i>or</i> * <li> * it lies exactly on a horizontal boundary segment <b>and</b> the * space immediately adjacent to the point in the * increasing <code>Y</code> direction is inside the boundary. * </ul> * <p>The <code>contains</code> and <code>intersects</code> methods * consider the interior of a <code>Shape</code> 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</code>.  Note that there is no guarantee that the     * returned <code>Rectangle</code> is the smallest bounding box that     * encloses the <code>Shape</code>, only that the <code>Shape</code>     * lies entirely within the indicated  <code>Rectangle</code>.  The     * returned <code>Rectangle</code> might also fail to completely     * enclose the <code>Shape</code> if the <code>Shape</code> overflows     * the limited range of the integer data type.  The     * <code>getBounds2D</code> method generally returns a     * tighter bounding box due to its greater flexibility in     * representation.     *     * <p>     * Note that the <a href="{@docRoot}/java/awt/Shape.html#def_insideness">     * definition of insideness</a> 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}.     * </p>     * <p>     * 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:     * </p>     * <p>     *  {@code shape.contains(x,y)} requires {@code bounds.contains(x,y)}     * </p>     * <p>     * If a {@code point} is not inside the {@code shape}, then it might     * still be contained in the {@code bounds} object:     * </p>     * <p>     *  {@code bounds.contains(x,y)} does not imply {@code shape.contains(x,y)}     * </p>     * @return an integer <code>Rectangle</code> that completely encloses     *                 the <code>Shape</code>.     * @see #getBounds2D     * @since 1.2     */    public Rectangle getBounds();     /**     * Returns a high precision and more accurate bounding box of     * the <code>Shape</code> than the <code>getBounds</code> method.     * Note that there is no guarantee that the returned     * {@link Rectangle2D} is the smallest bounding box that encloses     * the <code>Shape</code>, only that the <code>Shape</code> lies     * entirely within the indicated <code>Rectangle2D</code>.  The     * bounding box returned by this method is usually tighter than that     * returned by the <code>getBounds</code> method and never fails due     * to overflow problems since the return value can be an instance of     * the <code>Rectangle2D</code> that uses double precision values to     * store the dimensions.     *     * <p>     * Note that the <a href="{@docRoot}/java/awt/Shape.html#def_insideness">     * definition of insideness</a> 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}.     * </p>     * <p>     * 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:     * </p>     * <p>     *  {@code shape.contains(p)} requires {@code bounds.contains(p)}     * </p>     * <p>     * If a {@code point} is not inside the {@code shape}, then it might     * still be contained in the {@code bounds} object:     * </p>     * <p>     *  {@code bounds.contains(p)} does not imply {@code shape.contains(p)}     * </p>     * @return an instance of <code>Rectangle2D</code> that is a     *                 high-precision bounding box of the <code>Shape</code>.     * @see #getBounds     * @since 1.2     */    public Rectangle2D getBounds2D();     /**     * Tests if the specified coordinates are inside the boundary of the     * <code>Shape</code>, as described by the     * <a href="{@docRoot}/java/awt/Shape.html#def_insideness">     * definition of insideness</a>.     * @param x the specified X coordinate to be tested     * @param y the specified Y coordinate to be tested     * @return <code>true</code> if the specified coordinates are inside     *         the <code>Shape</code> boundary; <code>false</code>     *         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</code>, as described by the     * <a href="{@docRoot}/java/awt/Shape.html#def_insideness">     * definition of insideness</a>.     * @param p the specified <code>Point2D</code> to be tested     * @return <code>true</code> if the specified <code>Point2D</code> is     *          inside the boundary of the <code>Shape</code>;     *          <code>false</code> otherwise.     * @since 1.2     */    public boolean contains(Point2D p);     /**     * Tests if the interior of the <code>Shape</code> intersects the     * interior of a specified rectangular area.     * The rectangular area is considered to intersect the <code>Shape</code>     * if any point is contained in both the interior of the     * <code>Shape</code> and the specified rectangular area.     * <p>     * The {@code Shape.intersects()} method allows a {@code Shape}     * implementation to conservatively return {@code true} when:     * <ul>     * <li>     * there is a high probability that the rectangular area and the     * <code>Shape</code> intersect, but     * <li>     * the calculations to accurately determine this intersection     * are prohibitively expensive.     * </ul>     * This means that for some {@code Shapes} this method might     * return {@code true} even though the rectangular area does not     * intersect the {@code Shape}.     * The {@link java.awt.geom.Area Area} class performs     * more accurate computations of geometric intersection than most     * {@code Shape} objects and therefore can be used if a more precise     * answer is required.     *     * @param x the X coordinate of the upper-left corner     *          of the specified rectangular area     * @param y the Y coordinate of the upper-left corner     *          of the specified rectangular area     * @param w the width of the specified rectangular area     * @param h the height of the specified rectangular area     * @return <code>true</code> if the interior of the <code>Shape</code> and     *          the interior of the rectangular area intersect, or are     *          both highly likely to intersect and intersection calculations     *          would be too expensive to perform; <code>false</code> otherwise.     * @see java.awt.geom.Area     * @since 1.2     */    public boolean intersects(double x, double y, double w, double h);     /**     * Tests if the interior of the <code>Shape</code> intersects the     * interior of a specified <code>Rectangle2D</code>.     * The {@code Shape.intersects()} method allows a {@code Shape}     * implementation to conservatively return {@code true} when:     * <ul>     * <li>     * there is a high probability that the <code>Rectangle2D</code> and the     * <code>Shape</code> intersect, but     * <li>     * the calculations to accurately determine this intersection     * are prohibitively expensive.     * </ul>     * This means that for some {@code Shapes} this method might     * return {@code true} even though the {@code Rectangle2D} does not     * intersect the {@code Shape}.     * The {@link java.awt.geom.Area Area} class performs     * more accurate computations of geometric intersection than most     * {@code Shape} objects and therefore can be used if a more precise     * answer is required.     *     * @param r the specified <code>Rectangle2D</code>     * @return <code>true</code> if the interior of the <code>Shape</code> and     *          the interior of the specified <code>Rectangle2D</code>     *          intersect, or are both highly likely to intersect and intersection     *          calculations would be too expensive to perform; <code>false</code>     *          otherwise.     * @see #intersects(double, double, double, double)     * @since 1.2     */    public boolean intersects(Rectangle2D r);     /**     * Tests if the interior of the <code>Shape</code> entirely contains     * the specified rectangular area.  All coordinates that lie inside     * the rectangular area must lie within the <code>Shape</code> for the     * entire rectanglar area to be considered contained within the     * <code>Shape</code>.     * <p>     * The {@code Shape.contains()} method allows a {@code Shape}     * implementation to conservatively return {@code false} when:     * <ul>     * <li>     * the <code>intersect</code> method returns <code>true</code> and     * <li>     * the calculations to determine whether or not the     * <code>Shape</code> entirely contains the rectangular area are     * prohibitively expensive.     * </ul>     * This means that for some {@code Shapes} this method might     * return {@code false} even though the {@code Shape} contains     * the rectangular area.     * The {@link java.awt.geom.Area Area} class performs     * more accurate geometric computations than most     * {@code Shape} objects and therefore can be used if a more precise     * answer is required.     *     * @param x the X coordinate of the upper-left corner     *          of the specified rectangular area     * @param y the Y coordinate of the upper-left corner     *          of the specified rectangular area     * @param w the width of the specified rectangular area     * @param h the height of the specified rectangular area     * @return <code>true</code> if the interior of the <code>Shape</code>     *          entirely contains the specified rectangular area;     *          <code>false</code> otherwise or, if the <code>Shape</code>     *          contains the rectangular area and the     *          <code>intersects</code> method returns <code>true</code>     *          and the containment calculations would be too expensive to     *          perform.     * @see java.awt.geom.Area     * @see #intersects     * @since 1.2     */    public boolean contains(double x, double y, double w, double h);     /**     * Tests if the interior of the <code>Shape</code> entirely contains the     * specified <code>Rectangle2D</code>.     * The {@code Shape.contains()} method allows a {@code Shape}     * implementation to conservatively return {@code false} when:     * <ul>     * <li>     * the <code>intersect</code> method returns <code>true</code> and     * <li>     * the calculations to determine whether or not the     * <code>Shape</code> entirely contains the <code>Rectangle2D</code>     * are prohibitively expensive.     * </ul>     * This means that for some {@code Shapes} this method might     * return {@code false} even though the {@code Shape} contains     * the {@code Rectangle2D}.     * The {@link java.awt.geom.Area Area} class performs     * more accurate geometric computations than most     * {@code Shape} objects and therefore can be used if a more precise     * answer is required.     *     * @param r The specified <code>Rectangle2D</code>     * @return <code>true</code> if the interior of the <code>Shape</code>     *          entirely contains the <code>Rectangle2D</code>;     *          <code>false</code> otherwise or, if the <code>Shape</code>     *          contains the <code>Rectangle2D</code> and the     *          <code>intersects</code> method returns <code>true</code>     *          and the containment calculations would be too expensive to     *          perform.     * @see #contains(double, double, double, double)     * @since 1.2     */    public boolean contains(Rectangle2D r);     /**     * Returns an iterator object that iterates along the     * <code>Shape</code> boundary and provides access to the geometry of the     * <code>Shape</code> outline.  If an optional {@link AffineTransform}     * is specified, the coordinates returned in the iteration are     * transformed accordingly.     * <p>     * Each call to this method returns a fresh <code>PathIterator</code>     * object that traverses the geometry of the <code>Shape</code> object     * independently from any other <code>PathIterator</code> objects in use     * at the same time.     * <p>     * It is recommended, but not guaranteed, that objects     * implementing the <code>Shape</code> 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</code> to be applied to the     *          coordinates as they are returned in the iteration, or     *          <code>null</code> if untransformed coordinates are desired     * @return a new <code>PathIterator</code> object, which independently     *          traverses the geometry of the <code>Shape</code>.     * @since 1.2     */    public PathIterator getPathIterator(AffineTransform at);     /**     * Returns an iterator object that iterates along the <code>Shape</code>     * boundary and provides access to a flattened view of the     * <code>Shape</code> outline geometry.     * <p>     * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are     * returned by the iterator.     * <p>     * If an optional <code>AffineTransform</code> is specified,     * the coordinates returned in the iteration are transformed     * accordingly.     * <p>     * The amount of subdivision of the curved segments is controlled     * by the <code>flatness</code> 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.     * <p>     * Each call to this method returns a fresh <code>PathIterator</code>     * object that traverses the <code>Shape</code> object geometry     * independently from any other <code>PathIterator</code> objects in use at     * the same time.     * <p>     * It is recommended, but not guaranteed, that objects     * implementing the <code>Shape</code> 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</code> to be applied to the     *          coordinates as they are returned in the iteration, or     *          <code>null</code> 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</code> that independently traverses     *         a flattened view of the geometry of the  <code>Shape</code>.     * @since 1.2     */    public PathIterator getPathIterator(AffineTransform at, double flatness);}