1 /*
2 * Copyright (c) 1996, 2017, 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} interface provides definitions for objects
35 * that represent some form of geometric shape. The {@code Shape}
36 * is described by a {@link PathIterator} object, which can express the
37 * outline of the {@code Shape} as well as a rule for determining
38 * how the outline divides the 2D plane into interior and exterior
39 * points. Each {@code Shape} 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}, and retrieve a {@code PathIterator}
43 * object that describes the trajectory path of the {@code Shape}
44 * outline.
45 * <p>
46 * <a id="def_insideness"><b>Definition of insideness:</b></a>
47 * A point is considered to lie inside a
48 * {@code Shape} if and only if:
49 * <ul>
50 * <li> it lies completely
51 * inside the {@code Shape} boundary <i>or</i>
52 * <li>
53 * it lies exactly on the {@code Shape} boundary <i>and</i> the
54 * space immediately adjacent to the
55 * point in the increasing {@code X} 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} direction is inside the boundary.
61 * </ul>
62 * <p>The {@code contains} and {@code intersects} methods
63 * consider the interior of a {@code Shape} 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}. Note that there is no guarantee that the
82 * returned {@code Rectangle} is the smallest bounding box that
83 * encloses the {@code Shape}, only that the {@code Shape}
84 * lies entirely within the indicated {@code Rectangle}. The
85 * returned {@code Rectangle} might also fail to completely
86 * enclose the {@code Shape} if the {@code Shape} overflows
87 * the limited range of the integer data type. The
88 * {@code getBounds2D} method generally returns a
89 * tighter bounding box due to its greater flexibility in
90 * representation.
91 *
92 * <p>
93 * Note that the
94 * <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
95 * definition of insideness</a> can lead to situations where points
96 * on the defining outline of the {@code shape} may not be considered
97 * contained in the returned {@code bounds} object, but only in cases
98 * where those points are also not considered contained in the original
99 * {@code shape}.
100 * </p>
101 * <p>
102 * If a {@code point} is inside the {@code shape} according to the
103 * {@link #contains(double x, double y) contains(point)} method, then
104 * it must be inside the returned {@code Rectangle} bounds object
105 * according to the {@link #contains(double x, double y) contains(point)}
106 * method of the {@code bounds}. Specifically:
107 * </p>
108 * <p>
109 * {@code shape.contains(x,y)} requires {@code bounds.contains(x,y)}
110 * </p>
111 * <p>
112 * If a {@code point} is not inside the {@code shape}, then it might
113 * still be contained in the {@code bounds} object:
114 * </p>
115 * <p>
116 * {@code bounds.contains(x,y)} does not imply {@code shape.contains(x,y)}
117 * </p>
118 * @return an integer {@code Rectangle} that completely encloses
119 * the {@code Shape}.
120 * @see #getBounds2D
121 * @since 1.2
122 */
123 public Rectangle getBounds();
124
125 /**
126 * Returns a high precision and more accurate bounding box of
127 * the {@code Shape} than the {@code getBounds} method.
128 * Note that there is no guarantee that the returned
129 * {@link Rectangle2D} is the smallest bounding box that encloses
130 * the {@code Shape}, only that the {@code Shape} lies
131 * entirely within the indicated {@code Rectangle2D}. The
132 * bounding box returned by this method is usually tighter than that
133 * returned by the {@code getBounds} method and never fails due
134 * to overflow problems since the return value can be an instance of
135 * the {@code Rectangle2D} that uses double precision values to
136 * store the dimensions.
137 *
138 * <p>
139 * Note that the
140 * <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
141 * definition of insideness</a> can lead to situations where points
142 * on the defining outline of the {@code shape} may not be considered
143 * contained in the returned {@code bounds} object, but only in cases
144 * where those points are also not considered contained in the original
145 * {@code shape}.
146 * </p>
147 * <p>
148 * If a {@code point} is inside the {@code shape} according to the
149 * {@link #contains(Point2D p) contains(point)} method, then it must
150 * be inside the returned {@code Rectangle2D} bounds object according
151 * to the {@link #contains(Point2D p) contains(point)} method of the
152 * {@code bounds}. Specifically:
153 * </p>
154 * <p>
155 * {@code shape.contains(p)} requires {@code bounds.contains(p)}
156 * </p>
157 * <p>
158 * If a {@code point} is not inside the {@code shape}, then it might
159 * still be contained in the {@code bounds} object:
160 * </p>
161 * <p>
162 * {@code bounds.contains(p)} does not imply {@code shape.contains(p)}
163 * </p>
164 * @return an instance of {@code Rectangle2D} that is a
165 * high-precision bounding box of the {@code Shape}.
166 * @see #getBounds
167 * @since 1.2
168 */
169 public Rectangle2D getBounds2D();
170
171 /**
172 * Tests if the specified coordinates are inside the boundary of the
173 * {@code Shape}, as described by the
174 * <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
175 * definition of insideness</a>.
176 * @param x the specified X coordinate to be tested
177 * @param y the specified Y coordinate to be tested
178 * @return {@code true} if the specified coordinates are inside
179 * the {@code Shape} boundary; {@code false}
180 * otherwise.
181 * @since 1.2
182 */
183 public boolean contains(double x, double y);
184
185 /**
186 * Tests if a specified {@link Point2D} is inside the boundary
187 * of the {@code Shape}, as described by the
188 * <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
189 * definition of insideness</a>.
190 * @param p the specified {@code Point2D} to be tested
191 * @return {@code true} if the specified {@code Point2D} is
192 * inside the boundary of the {@code Shape};
193 * {@code false} otherwise.
194 * @since 1.2
195 */
196 public boolean contains(Point2D p);
197
198 /**
199 * Tests if the interior of the {@code Shape} intersects the
200 * interior of a specified rectangular area.
201 * The rectangular area is considered to intersect the {@code Shape}
202 * if any point is contained in both the interior of the
203 * {@code Shape} and the specified rectangular area.
204 * <p>
205 * The {@code Shape.intersects()} method allows a {@code Shape}
206 * implementation to conservatively return {@code true} when:
207 * <ul>
208 * <li>
209 * there is a high probability that the rectangular area and the
210 * {@code Shape} intersect, but
211 * <li>
212 * the calculations to accurately determine this intersection
213 * are prohibitively expensive.
214 * </ul>
215 * This means that for some {@code Shapes} this method might
216 * return {@code true} even though the rectangular area does not
217 * intersect the {@code Shape}.
218 * The {@link java.awt.geom.Area Area} class performs
219 * more accurate computations of geometric intersection than most
220 * {@code Shape} objects and therefore can be used if a more precise
221 * answer is required.
222 *
223 * @param x the X coordinate of the upper-left corner
224 * of the specified rectangular area
225 * @param y the Y coordinate of the upper-left corner
226 * of the specified rectangular area
227 * @param w the width of the specified rectangular area
228 * @param h the height of the specified rectangular area
229 * @return {@code true} if the interior of the {@code Shape} and
230 * the interior of the rectangular area intersect, or are
231 * both highly likely to intersect and intersection calculations
232 * would be too expensive to perform; {@code false} otherwise.
233 * @see java.awt.geom.Area
234 * @since 1.2
235 */
236 public boolean intersects(double x, double y, double w, double h);
237
238 /**
239 * Tests if the interior of the {@code Shape} intersects the
240 * interior of a specified {@code Rectangle2D}.
241 * The {@code Shape.intersects()} method allows a {@code Shape}
242 * implementation to conservatively return {@code true} when:
243 * <ul>
244 * <li>
245 * there is a high probability that the {@code Rectangle2D} and the
246 * {@code Shape} intersect, but
247 * <li>
248 * the calculations to accurately determine this intersection
249 * are prohibitively expensive.
250 * </ul>
251 * This means that for some {@code Shapes} this method might
252 * return {@code true} even though the {@code Rectangle2D} does not
253 * intersect the {@code Shape}.
254 * The {@link java.awt.geom.Area Area} class performs
255 * more accurate computations of geometric intersection than most
256 * {@code Shape} objects and therefore can be used if a more precise
257 * answer is required.
258 *
259 * @param r the specified {@code Rectangle2D}
260 * @return {@code true} if the interior of the {@code Shape} and
261 * the interior of the specified {@code Rectangle2D}
262 * intersect, or are both highly likely to intersect and intersection
263 * calculations would be too expensive to perform; {@code false}
264 * otherwise.
265 * @see #intersects(double, double, double, double)
266 * @since 1.2
267 */
268 public boolean intersects(Rectangle2D r);
269
270 /**
271 * Tests if the interior of the {@code Shape} entirely contains
272 * the specified rectangular area. All coordinates that lie inside
273 * the rectangular area must lie within the {@code Shape} for the
274 * entire rectangular area to be considered contained within the
275 * {@code Shape}.
276 * <p>
277 * The {@code Shape.contains()} method allows a {@code Shape}
278 * implementation to conservatively return {@code false} when:
279 * <ul>
280 * <li>
281 * the {@code intersect} method returns {@code true} and
282 * <li>
283 * the calculations to determine whether or not the
284 * {@code Shape} entirely contains the rectangular area are
285 * prohibitively expensive.
286 * </ul>
287 * This means that for some {@code Shapes} this method might
288 * return {@code false} even though the {@code Shape} contains
289 * the rectangular area.
290 * The {@link java.awt.geom.Area Area} class performs
291 * more accurate geometric computations than most
292 * {@code Shape} objects and therefore can be used if a more precise
293 * answer is required.
294 *
295 * @param x the X coordinate of the upper-left corner
296 * of the specified rectangular area
297 * @param y the Y coordinate of the upper-left corner
298 * of the specified rectangular area
299 * @param w the width of the specified rectangular area
300 * @param h the height of the specified rectangular area
301 * @return {@code true} if the interior of the {@code Shape}
302 * entirely contains the specified rectangular area;
303 * {@code false} otherwise or, if the {@code Shape}
304 * contains the rectangular area and the
305 * {@code intersects} method returns {@code true}
306 * and the containment calculations would be too expensive to
307 * perform.
308 * @see java.awt.geom.Area
309 * @see #intersects
310 * @since 1.2
311 */
312 public boolean contains(double x, double y, double w, double h);
313
314 /**
315 * Tests if the interior of the {@code Shape} entirely contains the
316 * specified {@code Rectangle2D}.
317 * The {@code Shape.contains()} method allows a {@code Shape}
318 * implementation to conservatively return {@code false} when:
319 * <ul>
320 * <li>
321 * the {@code intersect} method returns {@code true} and
322 * <li>
323 * the calculations to determine whether or not the
324 * {@code Shape} entirely contains the {@code Rectangle2D}
325 * are prohibitively expensive.
326 * </ul>
327 * This means that for some {@code Shapes} this method might
328 * return {@code false} even though the {@code Shape} contains
329 * the {@code Rectangle2D}.
330 * The {@link java.awt.geom.Area Area} class performs
331 * more accurate geometric computations than most
332 * {@code Shape} objects and therefore can be used if a more precise
333 * answer is required.
334 *
335 * @param r The specified {@code Rectangle2D}
336 * @return {@code true} if the interior of the {@code Shape}
337 * entirely contains the {@code Rectangle2D};
338 * {@code false} otherwise or, if the {@code Shape}
339 * contains the {@code Rectangle2D} and the
340 * {@code intersects} method returns {@code true}
341 * and the containment calculations would be too expensive to
342 * perform.
343 * @see #contains(double, double, double, double)
344 * @since 1.2
345 */
346 public boolean contains(Rectangle2D r);
347
348 /**
349 * Returns an iterator object that iterates along the
350 * {@code Shape} boundary and provides access to the geometry of the
351 * {@code Shape} outline. If an optional {@link AffineTransform}
352 * is specified, the coordinates returned in the iteration are
353 * transformed accordingly.
354 * <p>
355 * Each call to this method returns a fresh {@code PathIterator}
356 * object that traverses the geometry of the {@code Shape} object
357 * independently from any other {@code PathIterator} objects in use
358 * at the same time.
359 * <p>
360 * It is recommended, but not guaranteed, that objects
361 * implementing the {@code Shape} interface isolate iterations
362 * that are in process from any changes that might occur to the original
363 * object's geometry during such iterations.
364 *
365 * @param at an optional {@code AffineTransform} to be applied to the
366 * coordinates as they are returned in the iteration, or
367 * {@code null} if untransformed coordinates are desired
368 * @return a new {@code PathIterator} object, which independently
369 * traverses the geometry of the {@code Shape}.
370 * @since 1.2
371 */
372 public PathIterator getPathIterator(AffineTransform at);
373
374 /**
375 * Returns an iterator object that iterates along the {@code Shape}
376 * boundary and provides access to a flattened view of the
377 * {@code Shape} outline geometry.
378 * <p>
379 * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are
380 * returned by the iterator.
381 * <p>
382 * If an optional {@code AffineTransform} is specified,
383 * the coordinates returned in the iteration are transformed
384 * accordingly.
385 * <p>
386 * The amount of subdivision of the curved segments is controlled
387 * by the {@code flatness} parameter, which specifies the
388 * maximum distance that any point on the unflattened transformed
389 * curve can deviate from the returned flattened path segments.
390 * Note that a limit on the accuracy of the flattened path might be
391 * silently imposed, causing very small flattening parameters to be
392 * treated as larger values. This limit, if there is one, is
393 * defined by the particular implementation that is used.
394 * <p>
395 * Each call to this method returns a fresh {@code PathIterator}
396 * object that traverses the {@code Shape} object geometry
397 * independently from any other {@code PathIterator} objects in use at
398 * the same time.
399 * <p>
400 * It is recommended, but not guaranteed, that objects
401 * implementing the {@code Shape} interface isolate iterations
402 * that are in process from any changes that might occur to the original
403 * object's geometry during such iterations.
404 *
405 * @param at an optional {@code AffineTransform} to be applied to the
406 * coordinates as they are returned in the iteration, or
407 * {@code null} if untransformed coordinates are desired
408 * @param flatness the maximum distance that the line segments used to
409 * approximate the curved segments are allowed to deviate
410 * from any point on the original curve
411 * @return a new {@code PathIterator} that independently traverses
412 * a flattened view of the geometry of the {@code Shape}.
413 * @since 1.2
414 */
415 public PathIterator getPathIterator(AffineTransform at, double flatness);
416 }