< prev index next >

src/java.desktop/share/classes/java/awt/Shape.java

Print this page

        

*** 29,68 **** 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. --- 29,68 ---- import java.awt.geom.PathIterator; import java.awt.geom.Point2D; import java.awt.geom.Rectangle2D; /** ! * The {@code Shape} interface provides definitions for objects ! * that represent some form of geometric shape. The {@code Shape} * is described by a {@link PathIterator} object, which can express the ! * outline of the {@code Shape} as well as a rule for determining * how the outline divides the 2D plane into interior and exterior ! * points. Each {@code 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 {@code Shape}, and retrieve a {@code PathIterator} ! * object that describes the trajectory path of the {@code Shape} * outline. * <p> * <a name="def_insideness"><b>Definition of insideness:</b></a> * A point is considered to lie inside a ! * {@code Shape} if and only if: * <ul> * <li> it lies completely ! * inside the {@code Shape} boundary <i>or</i> * <li> ! * it lies exactly on the {@code Shape} boundary <i>and</i> the * space immediately adjacent to the ! * point in the increasing {@code X} 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} direction is inside the boundary. * </ul> ! * <p>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.
*** 76,93 **** * @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"> --- 76,93 ---- * @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. * * <p> * Note that the <a href="{@docRoot}/java/awt/Shape.html#def_insideness">
*** 112,139 **** * 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 --- 112,139 ---- * 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} 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. * * <p> * Note that the <a href="{@docRoot}/java/awt/Shape.html#def_insideness"> * definition of insideness</a> can lead to situations where points
*** 157,213 **** * 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 --- 157,213 ---- * 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} 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 * <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} 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 * <a href="{@docRoot}/java/awt/Shape.html#def_insideness"> * definition of insideness</a>. ! * @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. * <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} intersect, but * <li> * the calculations to accurately determine this intersection * are prohibitively expensive. * </ul> * This means that for some {@code Shapes} this method might
*** 222,249 **** * 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 --- 222,249 ---- * 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} if the interior of the {@code 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; {@code false} 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} intersects the ! * interior of a specified {@code Rectangle2D}. * 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} and the ! * {@code Shape} intersect, but * <li> * the calculations to accurately determine this intersection * are prohibitively expensive. * </ul> * This means that for some {@code Shapes} this method might
*** 252,287 **** * 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 rectangular 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. --- 252,287 ---- * 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} ! * @return {@code true} if the interior of the {@code Shape} and ! * the interior of the specified {@code Rectangle2D} * intersect, or are both highly likely to intersect and intersection ! * calculations would be too expensive to perform; {@code false} * otherwise. * @see #intersects(double, double, double, double) * @since 1.2 */ public boolean intersects(Rectangle2D r); /** ! * Tests if the interior of the {@code Shape} entirely contains * the specified rectangular area. All coordinates that lie inside ! * the rectangular area must lie within the {@code Shape} for the * entire rectangular area to be considered contained within the ! * {@code Shape}. * <p> * The {@code Shape.contains()} method allows a {@code Shape} * implementation to conservatively return {@code false} when: * <ul> * <li> ! * the {@code intersect} method returns {@code true} and * <li> * the calculations to determine whether or not the ! * {@code Shape} 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.
*** 294,414 **** * 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); } --- 294,414 ---- * 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} if the interior of the {@code Shape} * entirely contains the specified rectangular area; ! * {@code false} otherwise or, if the {@code Shape} * contains the rectangular area and the ! * {@code intersects} method returns {@code true} * 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} entirely contains the ! * specified {@code Rectangle2D}. * The {@code Shape.contains()} method allows a {@code Shape} * implementation to conservatively return {@code false} when: * <ul> * <li> ! * the {@code intersect} method returns {@code true} and * <li> * the calculations to determine whether or not the ! * {@code Shape} entirely contains the {@code Rectangle2D} * 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} ! * @return {@code true} if the interior of the {@code Shape} ! * entirely contains the {@code Rectangle2D}; ! * {@code false} otherwise or, if the {@code Shape} ! * contains the {@code Rectangle2D} and the ! * {@code intersects} method returns {@code true} * 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} boundary and provides access to the geometry of the ! * {@code Shape} 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} ! * object that traverses the geometry of the {@code Shape} object ! * independently from any other {@code PathIterator} objects in use * at the same time. * <p> * 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. * <p> * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are * returned by the iterator. * <p> ! * If an optional {@code AffineTransform} 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} 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} ! * object that traverses the {@code Shape} object geometry ! * independently from any other {@code PathIterator} objects in use at * the same time. * <p> * 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); }
< prev index next >