1/*2* Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.3* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.4*5* This code is free software; you can redistribute it and/or modify it6* under the terms of the GNU General Public License version 2 only, as7* published by the Free Software Foundation. Oracle designates this8* particular file as subject to the "Classpath" exception as provided9* by Oracle in the LICENSE file that accompanied this code.10*11* This code is distributed in the hope that it will be useful, but WITHOUT12* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or13* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License14* version 2 for more details (a copy is included in the LICENSE file that15* accompanied this code).16*17* You should have received a copy of the GNU General Public License version18* 2 along with this work; if not, write to the Free Software Foundation,19* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.20*21* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA22* or visit www.oracle.com if you need additional information or have any23* questions.24*/25 26packagejava.awt; 27 28importjava.awt.geom.AffineTransform; 29importjava.awt.geom.PathIterator; 30importjava.awt.geom.Point2D; 31importjava.awt.geom.Rectangle2D; 32 33/**34* The <code>Shape</code> interface provides definitions for objects35* that represent some form of geometric shape. The <code>Shape</code>36* is described by a {@link PathIterator} object, which can express the37* outline of the <code>Shape</code> as well as a rule for determining38* how the outline divides the 2D plane into interior and exterior39* points. Each <code>Shape</code> object provides callbacks to get the40* bounding box of the geometry, determine whether points or41* rectangles lie partly or entirely within the interior42* of the <code>Shape</code>, and retrieve a <code>PathIterator</code>43* object that describes the trajectory path of the <code>Shape</code>44* outline.45* <p>46* <a name="def_insideness"><b>Definition of insideness:</b></a>47* A point is considered to lie inside a48* <code>Shape</code> if and only if:49* <ul>50* <li> it lies completely51* inside the<code>Shape</code> boundary <i>or</i>52* <li>53* it lies exactly on the <code>Shape</code> boundary <i>and</i> the54* space immediately adjacent to the55* point in the increasing <code>X</code> direction is56* entirely inside the boundary <i>or</i>57* <li>58* it lies exactly on a horizontal boundary segment <b>and</b> the59* space immediately adjacent to the point in the60* increasing <code>Y</code> direction is inside the boundary.61* </ul>62* <p>The <code>contains</code> and <code>intersects</code> methods63* consider the interior of a <code>Shape</code> to be the area it64* encloses as if it were filled. This means that these methods65* consider66* unclosed shapes to be implicitly closed for the purpose of67* determining if a shape contains or intersects a rectangle or if a68* shape contains a point.69*70* @see java.awt.geom.PathIterator71* @see java.awt.geom.AffineTransform72* @see java.awt.geom.FlatteningPathIterator73* @see java.awt.geom.GeneralPath74*75* @author Jim Graham76* @since 1.277*/78publicinterfaceShape { 79/**80* Returns an integer {@link Rectangle} that completely encloses the81* <code>Shape</code>. Note that there is no guarantee that the82* returned <code>Rectangle</code> is the smallest bounding box that83* encloses the <code>Shape</code>, only that the <code>Shape</code>84* lies entirely within the indicated <code>Rectangle</code>. The85* returned <code>Rectangle</code> might also fail to completely86* enclose the <code>Shape</code> if the <code>Shape</code> overflows87* the limited range of the integer data type. The88* <code>getBounds2D</code> method generally returns a89* tighter bounding box due to its greater flexibility in90* representation.91*92* <p>93* Note that the <a href="{@docRoot}/java/awt/Shape.html#def_insideness">94* definition of insideness</a> can lead to situations where points95* on the defining outline of the {@code shape} may not be considered96* contained in the returned {@code bounds} object, but only in cases97* where those points are also not considered contained in the original98* {@code shape}.99* </p>100* <p>101* If a {@code point} is inside the {@code shape} according to the102* {@link #contains(double x, double y) contains(point)} method, then103* it must be inside the returned {@code Rectangle} bounds object104* according to the {@link #contains(double x, double y) contains(point)}105* method of the {@code bounds}. Specifically:106* </p>107* <p>108* {@code shape.contains(x,y)} requires {@code bounds.contains(x,y)}109* </p>110* <p>111* If a {@code point} is not inside the {@code shape}, then it might112* still be contained in the {@code bounds} object:113* </p>114* <p>115* {@code bounds.contains(x,y)} does not imply {@code shape.contains(x,y)}116* </p>117* @return an integer <code>Rectangle</code> that completely encloses118* the <code>Shape</code>.119* @see #getBounds2D120* @since 1.2121*/122publicRectangle getBounds(); 123 124/**125* Returns a high precision and more accurate bounding box of126* the <code>Shape</code> than the <code>getBounds</code> method.127* Note that there is no guarantee that the returned128* {@link Rectangle2D} is the smallest bounding box that encloses129* the <code>Shape</code>, only that the <code>Shape</code> lies130* entirely within the indicated <code>Rectangle2D</code>. The131* bounding box returned by this method is usually tighter than that132* returned by the <code>getBounds</code> method and never fails due133* to overflow problems since the return value can be an instance of134* the <code>Rectangle2D</code> that uses double precision values to135* store the dimensions.136*137* <p>138* Note that the <a href="{@docRoot}/java/awt/Shape.html#def_insideness">139* definition of insideness</a> can lead to situations where points140* on the defining outline of the {@code shape} may not be considered141* contained in the returned {@code bounds} object, but only in cases142* where those points are also not considered contained in the original143* {@code shape}.144* </p>145* <p>146* If a {@code point} is inside the {@code shape} according to the147* {@link #contains(Point2D p) contains(point)} method, then it must148* be inside the returned {@code Rectangle2D} bounds object according149* to the {@link #contains(Point2D p) contains(point)} method of the150* {@code bounds}. Specifically:151* </p>152* <p>153* {@code shape.contains(p)} requires {@code bounds.contains(p)}154* </p>155* <p>156* If a {@code point} is not inside the {@code shape}, then it might157* still be contained in the {@code bounds} object:158* </p>159* <p>160* {@code bounds.contains(p)} does not imply {@code shape.contains(p)}161* </p>162* @return an instance of <code>Rectangle2D</code> that is a163* high-precision bounding box of the <code>Shape</code>.164* @see #getBounds165* @since 1.2166*/167publicRectangle2D getBounds2D(); 168 169/**170* Tests if the specified coordinates are inside the boundary of the171* <code>Shape</code>, as described by the172* <a href="{@docRoot}/java/awt/Shape.html#def_insideness">173* definition of insideness</a>.174* @param x the specified X coordinate to be tested175* @param y the specified Y coordinate to be tested176* @return <code>true</code> if the specified coordinates are inside177* the <code>Shape</code> boundary; <code>false</code>178* otherwise.179* @since 1.2180*/181publicbooleancontains(doublex,doubley); 182 183/**184* Tests if a specified {@link Point2D} is inside the boundary185* of the <code>Shape</code>, as described by the186* <a href="{@docRoot}/java/awt/Shape.html#def_insideness">187* definition of insideness</a>.188* @param p the specified <code>Point2D</code> to be tested189* @return <code>true</code> if the specified <code>Point2D</code> is190* inside the boundary of the <code>Shape</code>;191* <code>false</code> otherwise.192* @since 1.2193*/194publicbooleancontains(Point2D p); 195 196/**197* Tests if the interior of the <code>Shape</code> intersects the198* interior of a specified rectangular area.199* The rectangular area is considered to intersect the <code>Shape</code>200* if any point is contained in both the interior of the201* <code>Shape</code> and the specified rectangular area.202* <p>203* The {@code Shape.intersects()} method allows a {@code Shape}204* implementation to conservatively return {@code true} when:205* <ul>206* <li>207* there is a high probability that the rectangular area and the208* <code>Shape</code> intersect, but209* <li>210* the calculations to accurately determine this intersection211* are prohibitively expensive.212* </ul>213* This means that for some {@code Shapes} this method might214* return {@code true} even though the rectangular area does not215* intersect the {@code Shape}.216* The {@link java.awt.geom.Area Area} class performs217* more accurate computations of geometric intersection than most218* {@code Shape} objects and therefore can be used if a more precise219* answer is required.220*221* @param x the X coordinate of the upper-left corner222* of the specified rectangular area223* @param y the Y coordinate of the upper-left corner224* of the specified rectangular area225* @param w the width of the specified rectangular area226* @param h the height of the specified rectangular area227* @return <code>true</code> if the interior of the <code>Shape</code> and228* the interior of the rectangular area intersect, or are229* both highly likely to intersect and intersection calculations230* would be too expensive to perform; <code>false</code> otherwise.231* @see java.awt.geom.Area232* @since 1.2233*/234publicbooleanintersects(doublex,doubley,doublew,doubleh); 235 236/**237* Tests if the interior of the <code>Shape</code> intersects the238* interior of a specified <code>Rectangle2D</code>.239* The {@code Shape.intersects()} method allows a {@code Shape}240* implementation to conservatively return {@code true} when:241* <ul>242* <li>243* there is a high probability that the <code>Rectangle2D</code> and the244* <code>Shape</code> intersect, but245* <li>246* the calculations to accurately determine this intersection247* are prohibitively expensive.248* </ul>249* This means that for some {@code Shapes} this method might250* return {@code true} even though the {@code Rectangle2D} does not251* intersect the {@code Shape}.252* The {@link java.awt.geom.Area Area} class performs253* more accurate computations of geometric intersection than most254* {@code Shape} objects and therefore can be used if a more precise255* answer is required.256*257* @param r the specified <code>Rectangle2D</code>258* @return <code>true</code> if the interior of the <code>Shape</code> and259* the interior of the specified <code>Rectangle2D</code>260* intersect, or are both highly likely to intersect and intersection261* calculations would be too expensive to perform; <code>false</code>262* otherwise.263* @see #intersects(double, double, double, double)264* @since 1.2265*/266publicbooleanintersects(Rectangle2D r); 267 268/**269* Tests if the interior of the <code>Shape</code> entirely contains270* the specified rectangular area. All coordinates that lie inside271* the rectangular area must lie within the <code>Shape</code> for the272* entire rectangular area to be considered contained within the273* <code>Shape</code>.274* <p>275* The {@code Shape.contains()} method allows a {@code Shape}276* implementation to conservatively return {@code false} when:277* <ul>278* <li>279* the <code>intersect</code> method returns <code>true</code> and280* <li>281* the calculations to determine whether or not the282* <code>Shape</code> entirely contains the rectangular area are283* prohibitively expensive.284* </ul>285* This means that for some {@code Shapes} this method might286* return {@code false} even though the {@code Shape} contains287* the rectangular area.288* The {@link java.awt.geom.Area Area} class performs289* more accurate geometric computations than most290* {@code Shape} objects and therefore can be used if a more precise291* answer is required.292*293* @param x the X coordinate of the upper-left corner294* of the specified rectangular area295* @param y the Y coordinate of the upper-left corner296* of the specified rectangular area297* @param w the width of the specified rectangular area298* @param h the height of the specified rectangular area299* @return <code>true</code> if the interior of the <code>Shape</code>300* entirely contains the specified rectangular area;301* <code>false</code> otherwise or, if the <code>Shape</code>302* contains the rectangular area and the303* <code>intersects</code> method returns <code>true</code>304* and the containment calculations would be too expensive to305* perform.306* @see java.awt.geom.Area307* @see #intersects308* @since 1.2309*/310publicbooleancontains(doublex,doubley,doublew,doubleh); 311 312/**313* Tests if the interior of the <code>Shape</code> entirely contains the314* specified <code>Rectangle2D</code>.315* The {@code Shape.contains()} method allows a {@code Shape}316* implementation to conservatively return {@code false} when:317* <ul>318* <li>319* the <code>intersect</code> method returns <code>true</code> and320* <li>321* the calculations to determine whether or not the322* <code>Shape</code> entirely contains the <code>Rectangle2D</code>323* are prohibitively expensive.324* </ul>325* This means that for some {@code Shapes} this method might326* return {@code false} even though the {@code Shape} contains327* the {@code Rectangle2D}.328* The {@link java.awt.geom.Area Area} class performs329* more accurate geometric computations than most330* {@code Shape} objects and therefore can be used if a more precise331* answer is required.332*333* @param r The specified <code>Rectangle2D</code>334* @return <code>true</code> if the interior of the <code>Shape</code>335* entirely contains the <code>Rectangle2D</code>;336* <code>false</code> otherwise or, if the <code>Shape</code>337* contains the <code>Rectangle2D</code> and the338* <code>intersects</code> method returns <code>true</code>339* and the containment calculations would be too expensive to340* perform.341* @see #contains(double, double, double, double)342* @since 1.2343*/344publicbooleancontains(Rectangle2D r); 345 346/**347* Returns an iterator object that iterates along the348* <code>Shape</code> boundary and provides access to the geometry of the349* <code>Shape</code> outline. If an optional {@link AffineTransform}350* is specified, the coordinates returned in the iteration are351* transformed accordingly.352* <p>353* Each call to this method returns a fresh <code>PathIterator</code>354* object that traverses the geometry of the <code>Shape</code> object355* independently from any other <code>PathIterator</code> objects in use356* at the same time.357* <p>358* It is recommended, but not guaranteed, that objects359* implementing the <code>Shape</code> interface isolate iterations360* that are in process from any changes that might occur to the original361* object's geometry during such iterations.362*363* @param at an optional <code>AffineTransform</code> to be applied to the364* coordinates as they are returned in the iteration, or365* <code>null</code> if untransformed coordinates are desired366* @return a new <code>PathIterator</code> object, which independently367* traverses the geometry of the <code>Shape</code>.368* @since 1.2369*/370publicPathIterator getPathIterator(AffineTransform at); 371 372/**373* Returns an iterator object that iterates along the <code>Shape</code>374* boundary and provides access to a flattened view of the375* <code>Shape</code> outline geometry.376* <p>377* Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are378* returned by the iterator.379* <p>380* If an optional <code>AffineTransform</code> is specified,381* the coordinates returned in the iteration are transformed382* accordingly.383* <p>384* The amount of subdivision of the curved segments is controlled385* by the <code>flatness</code> parameter, which specifies the386* maximum distance that any point on the unflattened transformed387* curve can deviate from the returned flattened path segments.388* Note that a limit on the accuracy of the flattened path might be389* silently imposed, causing very small flattening parameters to be390* treated as larger values. This limit, if there is one, is391* defined by the particular implementation that is used.392* <p>393* Each call to this method returns a fresh <code>PathIterator</code>394* object that traverses the <code>Shape</code> object geometry395* independently from any other <code>PathIterator</code> objects in use at396* the same time.397* <p>398* It is recommended, but not guaranteed, that objects399* implementing the <code>Shape</code> interface isolate iterations400* that are in process from any changes that might occur to the original401* object's geometry during such iterations.402*403* @param at an optional <code>AffineTransform</code> to be applied to the404* coordinates as they are returned in the iteration, or405* <code>null</code> if untransformed coordinates are desired406* @param flatness the maximum distance that the line segments used to407* approximate the curved segments are allowed to deviate408* from any point on the original curve409* @return a new <code>PathIterator</code> that independently traverses410* a flattened view of the geometry of the <code>Shape</code>.411* @since 1.2412*/413publicPathIterator getPathIterator(AffineTransform at,doubleflatness); 414 }