--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/awt/Shape.java Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,358 @@
+/*
+ * Copyright 1996-2006 Sun Microsystems, Inc. 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. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.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>
+ * <b>Definition of insideness:</b>
+ * 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.
+ * @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.
+ * @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>.
+ * @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>.
+ * @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);
+}