Showing the changes to java/pkg/java/awt/Shape.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,414 @@ | |||
| 1 | /* | ||
| 2 | * Copyright (c) 1996, 2006, 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 it | ||
| 6 | * under the terms of the GNU General Public License version 2 only, as | ||
| 7 | * published by the Free Software Foundation. Oracle designates this | ||
| 8 | * particular file as subject to the "Classpath" exception as provided | ||
| 9 | * 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 WITHOUT | ||
| 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | ||
| 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | ||
| 14 | * version 2 for more details (a copy is included in the LICENSE file that | ||
| 15 | * accompanied this code). | ||
| 16 | * | ||
| 17 | * You should have received a copy of the GNU General Public License version | ||
| 18 | * 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 USA | ||
| 22 | * or visit www.oracle.com if you need additional information or have any | ||
| 23 | * questions. | ||
| 24 | */ | ||
| 25 | |||
| 26 | package java.awt; | ||
| 27 | |||
| 28 | import java.awt.geom.AffineTransform; | ||
| 29 | import java.awt.geom.PathIterator; | ||
| 30 | import java.awt.geom.Point2D; | ||
| 31 | import java.awt.geom.Rectangle2D; | ||
| 32 | |||
| 33 | /** | ||
| 34 | * The <code>Shape</code> interface provides definitions for objects | ||
| 35 | * that represent some form of geometric shape. The <code>Shape</code> | ||
| 36 | * is described by a {@link PathIterator} object, which can express the | ||
| 37 | * outline of the <code>Shape</code> as well as a rule for determining | ||
| 38 | * how the outline divides the 2D plane into interior and exterior | ||
| 39 | * points. Each <code>Shape</code> object provides callbacks to get the | ||
| 40 | * bounding box of the geometry, determine whether points or | ||
| 41 | * rectangles lie partly or entirely within the interior | ||
| 42 | * 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 a | ||
| 48 | * <code>Shape</code> if and only if: | ||
| 49 | * <ul> | ||
| 50 | * <li> it lies completely | ||
| 51 | * inside the<code>Shape</code> boundary <i>or</i> | ||
| 52 | * <li> | ||
| 53 | * it lies exactly on the <code>Shape</code> boundary <i>and</i> the | ||
| 54 | * space immediately adjacent to the | ||
| 55 | * point in the increasing <code>X</code> direction is | ||
| 56 | * entirely inside the boundary <i>or</i> | ||
| 57 | * <li> | ||
| 58 | * it lies exactly on a horizontal boundary segment <b>and</b> the | ||
| 59 | * space immediately adjacent to the point in the | ||
| 60 | * increasing <code>Y</code> direction is inside the boundary. | ||
| 61 | * </ul> | ||
| 62 | * <p>The <code>contains</code> and <code>intersects</code> methods | ||
| 63 | * consider the interior of a <code>Shape</code> to be the area it | ||
| 64 | * encloses as if it were filled. This means that these methods | ||
| 65 | * consider | ||
| 66 | * unclosed shapes to be implicitly closed for the purpose of | ||
| 67 | * determining if a shape contains or intersects a rectangle or if a | ||
| 68 | * shape contains a point. | ||
| 69 | * | ||
| 70 | * @see java.awt.geom.PathIterator | ||
| 71 | * @see java.awt.geom.AffineTransform | ||
| 72 | * @see java.awt.geom.FlatteningPathIterator | ||
| 73 | * @see java.awt.geom.GeneralPath | ||
| 74 | * | ||
| 75 | * @author Jim Graham | ||
| 76 | * @since 1.2 | ||
| 77 | */ | ||
| 78 | public interface Shape { | ||
| 79 | /** | ||
| 80 | * Returns an integer {@link Rectangle} that completely encloses the | ||
| 81 | * <code>Shape</code>. Note that there is no guarantee that the | ||
| 82 | * returned <code>Rectangle</code> is the smallest bounding box that | ||
| 83 | * encloses the <code>Shape</code>, only that the <code>Shape</code> | ||
| 84 | * lies entirely within the indicated <code>Rectangle</code>. The | ||
| 85 | * returned <code>Rectangle</code> might also fail to completely | ||
| 86 | * enclose the <code>Shape</code> if the <code>Shape</code> overflows | ||
| 87 | * the limited range of the integer data type. The | ||
| 88 | * <code>getBounds2D</code> method generally returns a | ||
| 89 | * tighter bounding box due to its greater flexibility in | ||
| 90 | * 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 points | ||
| 95 | * on the defining outline of the {@code shape} may not be considered | ||
| 96 | * contained in the returned {@code bounds} object, but only in cases | ||
| 97 | * where those points are also not considered contained in the original | ||
| 98 | * {@code shape}. | ||
| 99 | * </p> | ||
| 100 | * <p> | ||
| 101 | * If a {@code point} is inside the {@code shape} according to the | ||
| 102 | * {@link #contains(double x, double y) contains(point)} method, then | ||
| 103 | * it must be inside the returned {@code Rectangle} bounds object | ||
| 104 | * 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 might | ||
| 112 | * 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 encloses | ||
| 118 | * the <code>Shape</code>. | ||
| 119 | * @see #getBounds2D | ||
| 120 | * @since 1.2 | ||
| 121 | */ | ||
| 122 | public Rectangle getBounds(); | ||
| 123 | |||
| 124 | /** | ||
| 125 | * Returns a high precision and more accurate bounding box of | ||
| 126 | * the <code>Shape</code> than the <code>getBounds</code> method. | ||
| 127 | * Note that there is no guarantee that the returned | ||
| 128 | * {@link Rectangle2D} is the smallest bounding box that encloses | ||
| 129 | * the <code>Shape</code>, only that the <code>Shape</code> lies | ||
| 130 | * entirely within the indicated <code>Rectangle2D</code>. The | ||
| 131 | * bounding box returned by this method is usually tighter than that | ||
| 132 | * returned by the <code>getBounds</code> method and never fails due | ||
| 133 | * to overflow problems since the return value can be an instance of | ||
| 134 | * the <code>Rectangle2D</code> that uses double precision values to | ||
| 135 | * 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 points | ||
| 140 | * on the defining outline of the {@code shape} may not be considered | ||
| 141 | * contained in the returned {@code bounds} object, but only in cases | ||
| 142 | * where those points are also not considered contained in the original | ||
| 143 | * {@code shape}. | ||
| 144 | * </p> | ||
| 145 | * <p> | ||
| 146 | * If a {@code point} is inside the {@code shape} according to the | ||
| 147 | * {@link #contains(Point2D p) contains(point)} method, then it must | ||
| 148 | * be inside the returned {@code Rectangle2D} bounds object according | ||
| 149 | * to the {@link #contains(Point2D p) contains(point)} method of the | ||
| 150 | * {@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 might | ||
| 157 | * 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 a | ||
| 163 | * high-precision bounding box of the <code>Shape</code>. | ||
| 164 | * @see #getBounds | ||
| 165 | * @since 1.2 | ||
| 166 | */ | ||
| 167 | public Rectangle2D getBounds2D(); | ||
| 168 | |||
| 169 | /** | ||
| 170 | * Tests if the specified coordinates are inside the boundary of the | ||
| 171 | * <code>Shape</code>, as described by the | ||
| 172 | * <a href="{@docRoot}/java/awt/Shape.html#def_insideness"> | ||
| 173 | * definition of insideness</a>. | ||
| 174 | * @param x the specified X coordinate to be tested | ||
| 175 | * @param y the specified Y coordinate to be tested | ||
| 176 | * @return <code>true</code> if the specified coordinates are inside | ||
| 177 | * the <code>Shape</code> boundary; <code>false</code> | ||
| 178 | * otherwise. | ||
| 179 | * @since 1.2 | ||
| 180 | */ | ||
| 181 | public boolean contains(double x, double y); | ||
| 182 | |||
| 183 | /** | ||
| 184 | * Tests if a specified {@link Point2D} is inside the boundary | ||
| 185 | * of the <code>Shape</code>, as described by the | ||
| 186 | * <a href="{@docRoot}/java/awt/Shape.html#def_insideness"> | ||
| 187 | * definition of insideness</a>. | ||
| 188 | * @param p the specified <code>Point2D</code> to be tested | ||
| 189 | * @return <code>true</code> if the specified <code>Point2D</code> is | ||
| 190 | * inside the boundary of the <code>Shape</code>; | ||
| 191 | * <code>false</code> otherwise. | ||
| 192 | * @since 1.2 | ||
| 193 | */ | ||
| 194 | public boolean contains(Point2D p); | ||
| 195 | |||
| 196 | /** | ||
| 197 | * Tests if the interior of the <code>Shape</code> intersects the | ||
| 198 | * 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 the | ||
| 201 | * <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 the | ||
| 208 | * <code>Shape</code> intersect, but | ||
| 209 | * <li> | ||
| 210 | * the calculations to accurately determine this intersection | ||
| 211 | * are prohibitively expensive. | ||
| 212 | * </ul> | ||
| 213 | * This means that for some {@code Shapes} this method might | ||
| 214 | * return {@code true} even though the rectangular area does not | ||
| 215 | * intersect the {@code Shape}. | ||
| 216 | * The {@link java.awt.geom.Area Area} class performs | ||
| 217 | * more accurate computations of geometric intersection than most | ||
| 218 | * {@code Shape} objects and therefore can be used if a more precise | ||
| 219 | * answer is required. | ||
| 220 | * | ||
| 221 | * @param x the X coordinate of the upper-left corner | ||
| 222 | * of the specified rectangular area | ||
| 223 | * @param y the Y coordinate of the upper-left corner | ||
| 224 | * of the specified rectangular area | ||
| 225 | * @param w the width of the specified rectangular area | ||
| 226 | * @param h the height of the specified rectangular area | ||
| 227 | * @return <code>true</code> if the interior of the <code>Shape</code> and | ||
| 228 | * the interior of the rectangular area intersect, or are | ||
| 229 | * both highly likely to intersect and intersection calculations | ||
| 230 | * would be too expensive to perform; <code>false</code> otherwise. | ||
| 231 | * @see java.awt.geom.Area | ||
| 232 | * @since 1.2 | ||
| 233 | */ | ||
| 234 | public boolean intersects(double x, double y, double w, double h); | ||
| 235 | |||
| 236 | /** | ||
| 237 | * Tests if the interior of the <code>Shape</code> intersects the | ||
| 238 | * 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 the | ||
| 244 | * <code>Shape</code> intersect, but | ||
| 245 | * <li> | ||
| 246 | * the calculations to accurately determine this intersection | ||
| 247 | * are prohibitively expensive. | ||
| 248 | * </ul> | ||
| 249 | * This means that for some {@code Shapes} this method might | ||
| 250 | * return {@code true} even though the {@code Rectangle2D} does not | ||
| 251 | * intersect the {@code Shape}. | ||
| 252 | * The {@link java.awt.geom.Area Area} class performs | ||
| 253 | * more accurate computations of geometric intersection than most | ||
| 254 | * {@code Shape} objects and therefore can be used if a more precise | ||
| 255 | * 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> and | ||
| 259 | * the interior of the specified <code>Rectangle2D</code> | ||
| 260 | * intersect, or are both highly likely to intersect and intersection | ||
| 261 | * calculations would be too expensive to perform; <code>false</code> | ||
| 262 | * otherwise. | ||
| 263 | * @see #intersects(double, double, double, double) | ||
| 264 | * @since 1.2 | ||
| 265 | */ | ||
| 266 | public boolean intersects(Rectangle2D r); | ||
| 267 | |||
| 268 | /** | ||
| 269 | * Tests if the interior of the <code>Shape</code> entirely contains | ||
| 270 | * the specified rectangular area. All coordinates that lie inside | ||
| 271 | * the rectangular area must lie within the <code>Shape</code> for the | ||
| 272 | * entire rectanglar area to be considered contained within the | ||
| 273 | * <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> and | ||
| 280 | * <li> | ||
| 281 | * the calculations to determine whether or not the | ||
| 282 | * <code>Shape</code> entirely contains the rectangular area are | ||
| 283 | * prohibitively expensive. | ||
| 284 | * </ul> | ||
| 285 | * This means that for some {@code Shapes} this method might | ||
| 286 | * return {@code false} even though the {@code Shape} contains | ||
| 287 | * the rectangular area. | ||
| 288 | * The {@link java.awt.geom.Area Area} class performs | ||
| 289 | * more accurate geometric computations than most | ||
| 290 | * {@code Shape} objects and therefore can be used if a more precise | ||
| 291 | * answer is required. | ||
| 292 | * | ||
| 293 | * @param x the X coordinate of the upper-left corner | ||
| 294 | * of the specified rectangular area | ||
| 295 | * @param y the Y coordinate of the upper-left corner | ||
| 296 | * of the specified rectangular area | ||
| 297 | * @param w the width of the specified rectangular area | ||
| 298 | * @param h the height of the specified rectangular area | ||
| 299 | * @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 the | ||
| 303 | * <code>intersects</code> method returns <code>true</code> | ||
| 304 | * and the containment calculations would be too expensive to | ||
| 305 | * perform. | ||
| 306 | * @see java.awt.geom.Area | ||
| 307 | * @see #intersects | ||
| 308 | * @since 1.2 | ||
| 309 | */ | ||
| 310 | public boolean contains(double x, double y, double w, double h); | ||
| 311 | |||
| 312 | /** | ||
| 313 | * Tests if the interior of the <code>Shape</code> entirely contains the | ||
| 314 | * 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> and | ||
| 320 | * <li> | ||
| 321 | * the calculations to determine whether or not the | ||
| 322 | * <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 might | ||
| 326 | * return {@code false} even though the {@code Shape} contains | ||
| 327 | * the {@code Rectangle2D}. | ||
| 328 | * The {@link java.awt.geom.Area Area} class performs | ||
| 329 | * more accurate geometric computations than most | ||
| 330 | * {@code Shape} objects and therefore can be used if a more precise | ||
| 331 | * 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 the | ||
| 338 | * <code>intersects</code> method returns <code>true</code> | ||
| 339 | * and the containment calculations would be too expensive to | ||
| 340 | * perform. | ||
| 341 | * @see #contains(double, double, double, double) | ||
| 342 | * @since 1.2 | ||
| 343 | */ | ||
| 344 | public boolean contains(Rectangle2D r); | ||
| 345 | |||
| 346 | /** | ||
| 347 | * Returns an iterator object that iterates along the | ||
| 348 | * <code>Shape</code> boundary and provides access to the geometry of the | ||
| 349 | * <code>Shape</code> outline. If an optional {@link AffineTransform} | ||
| 350 | * is specified, the coordinates returned in the iteration are | ||
| 351 | * 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> object | ||
| 355 | * independently from any other <code>PathIterator</code> objects in use | ||
| 356 | * at the same time. | ||
| 357 | * <p> | ||
| 358 | * It is recommended, but not guaranteed, that objects | ||
| 359 | * implementing the <code>Shape</code> interface isolate iterations | ||
| 360 | * that are in process from any changes that might occur to the original | ||
| 361 | * object's geometry during such iterations. | ||
| 362 | * | ||
| 363 | * @param at an optional <code>AffineTransform</code> to be applied to the | ||
| 364 | * coordinates as they are returned in the iteration, or | ||
| 365 | * <code>null</code> if untransformed coordinates are desired | ||
| 366 | * @return a new <code>PathIterator</code> object, which independently | ||
| 367 | * traverses the geometry of the <code>Shape</code>. | ||
| 368 | * @since 1.2 | ||
| 369 | */ | ||
| 370 | public PathIterator 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 the | ||
| 375 | * <code>Shape</code> outline geometry. | ||
| 376 | * <p> | ||
| 377 | * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are | ||
| 378 | * returned by the iterator. | ||
| 379 | * <p> | ||
| 380 | * If an optional <code>AffineTransform</code> is specified, | ||
| 381 | * the coordinates returned in the iteration are transformed | ||
| 382 | * accordingly. | ||
| 383 | * <p> | ||
| 384 | * The amount of subdivision of the curved segments is controlled | ||
| 385 | * by the <code>flatness</code> parameter, which specifies the | ||
| 386 | * maximum distance that any point on the unflattened transformed | ||
| 387 | * curve can deviate from the returned flattened path segments. | ||
| 388 | * Note that a limit on the accuracy of the flattened path might be | ||
| 389 | * silently imposed, causing very small flattening parameters to be | ||
| 390 | * treated as larger values. This limit, if there is one, is | ||
| 391 | * 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 geometry | ||
| 395 | * independently from any other <code>PathIterator</code> objects in use at | ||
| 396 | * the same time. | ||
| 397 | * <p> | ||
| 398 | * It is recommended, but not guaranteed, that objects | ||
| 399 | * implementing the <code>Shape</code> interface isolate iterations | ||
| 400 | * that are in process from any changes that might occur to the original | ||
| 401 | * object's geometry during such iterations. | ||
| 402 | * | ||
| 403 | * @param at an optional <code>AffineTransform</code> to be applied to the | ||
| 404 | * coordinates as they are returned in the iteration, or | ||
| 405 | * <code>null</code> if untransformed coordinates are desired | ||
| 406 | * @param flatness the maximum distance that the line segments used to | ||
| 407 | * approximate the curved segments are allowed to deviate | ||
| 408 | * from any point on the original curve | ||
| 409 | * @return a new <code>PathIterator</code> that independently traverses | ||
| 410 | * a flattened view of the geometry of the <code>Shape</code>. | ||
| 411 | * @since 1.2 | ||
| 412 | */ | ||
| 413 | public PathIterator getPathIterator(AffineTransform at, double flatness); | ||
| 414 | } | ||