001 /*
002 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt;
027
028 import java.awt.geom.AffineTransform;
029 import java.awt.geom.PathIterator;
030 import java.awt.geom.Point2D;
031 import java.awt.geom.Rectangle2D;
032
033 /**
034 * The <code>Shape</code> interface provides definitions for objects
035 * that represent some form of geometric shape. The <code>Shape</code>
036 * is described by a {@link PathIterator} object, which can express the
037 * outline of the <code>Shape</code> as well as a rule for determining
038 * how the outline divides the 2D plane into interior and exterior
039 * points. Each <code>Shape</code> object provides callbacks to get the
040 * bounding box of the geometry, determine whether points or
041 * rectangles lie partly or entirely within the interior
042 * of the <code>Shape</code>, and retrieve a <code>PathIterator</code>
043 * object that describes the trajectory path of the <code>Shape</code>
044 * outline.
045 * <p>
046 * <b>Definition of insideness:</b>
047 * A point is considered to lie inside a
048 * <code>Shape</code> if and only if:
049 * <ul>
050 * <li> it lies completely
051 * inside the<code>Shape</code> boundary <i>or</i>
052 * <li>
053 * it lies exactly on the <code>Shape</code> boundary <i>and</i> the
054 * space immediately adjacent to the
055 * point in the increasing <code>X</code> direction is
056 * entirely inside the boundary <i>or</i>
057 * <li>
058 * it lies exactly on a horizontal boundary segment <b>and</b> the
059 * space immediately adjacent to the point in the
060 * increasing <code>Y</code> direction is inside the boundary.
061 * </ul>
062 * <p>The <code>contains</code> and <code>intersects</code> methods
063 * consider the interior of a <code>Shape</code> to be the area it
064 * encloses as if it were filled. This means that these methods
065 * consider
066 * unclosed shapes to be implicitly closed for the purpose of
067 * determining if a shape contains or intersects a rectangle or if a
068 * shape contains a point.
069 *
070 * @see java.awt.geom.PathIterator
071 * @see java.awt.geom.AffineTransform
072 * @see java.awt.geom.FlatteningPathIterator
073 * @see java.awt.geom.GeneralPath
074 *
075 * @version 1.19 06/24/98
076 * @author Jim Graham
077 * @since 1.2
078 */
079 public interface Shape {
080 /**
081 * Returns an integer {@link Rectangle} that completely encloses the
082 * <code>Shape</code>. Note that there is no guarantee that the
083 * returned <code>Rectangle</code> is the smallest bounding box that
084 * encloses the <code>Shape</code>, only that the <code>Shape</code>
085 * lies entirely within the indicated <code>Rectangle</code>. The
086 * returned <code>Rectangle</code> might also fail to completely
087 * enclose the <code>Shape</code> if the <code>Shape</code> overflows
088 * the limited range of the integer data type. The
089 * <code>getBounds2D</code> method generally returns a
090 * tighter bounding box due to its greater flexibility in
091 * representation.
092 * @return an integer <code>Rectangle</code> that completely encloses
093 * the <code>Shape</code>.
094 * @see #getBounds2D
095 * @since 1.2
096 */
097 public Rectangle getBounds();
098
099 /**
100 * Returns a high precision and more accurate bounding box of
101 * the <code>Shape</code> than the <code>getBounds</code> method.
102 * Note that there is no guarantee that the returned
103 * {@link Rectangle2D} is the smallest bounding box that encloses
104 * the <code>Shape</code>, only that the <code>Shape</code> lies
105 * entirely within the indicated <code>Rectangle2D</code>. The
106 * bounding box returned by this method is usually tighter than that
107 * returned by the <code>getBounds</code> method and never fails due
108 * to overflow problems since the return value can be an instance of
109 * the <code>Rectangle2D</code> that uses double precision values to
110 * store the dimensions.
111 * @return an instance of <code>Rectangle2D</code> that is a
112 * high-precision bounding box of the <code>Shape</code>.
113 * @see #getBounds
114 * @since 1.2
115 */
116 public Rectangle2D getBounds2D();
117
118 /**
119 * Tests if the specified coordinates are inside the boundary of the
120 * <code>Shape</code>.
121 * @param x the specified X coordinate to be tested
122 * @param y the specified Y coordinate to be tested
123 * @return <code>true</code> if the specified coordinates are inside
124 * the <code>Shape</code> boundary; <code>false</code>
125 * otherwise.
126 * @since 1.2
127 */
128 public boolean contains(double x, double y);
129
130 /**
131 * Tests if a specified {@link Point2D} is inside the boundary
132 * of the <code>Shape</code>.
133 * @param p the specified <code>Point2D</code> to be tested
134 * @return <code>true</code> if the specified <code>Point2D</code> is
135 * inside the boundary of the <code>Shape</code>;
136 * <code>false</code> otherwise.
137 * @since 1.2
138 */
139 public boolean contains(Point2D p);
140
141 /**
142 * Tests if the interior of the <code>Shape</code> intersects the
143 * interior of a specified rectangular area.
144 * The rectangular area is considered to intersect the <code>Shape</code>
145 * if any point is contained in both the interior of the
146 * <code>Shape</code> and the specified rectangular area.
147 * <p>
148 * The {@code Shape.intersects()} method allows a {@code Shape}
149 * implementation to conservatively return {@code true} when:
150 * <ul>
151 * <li>
152 * there is a high probability that the rectangular area and the
153 * <code>Shape</code> intersect, but
154 * <li>
155 * the calculations to accurately determine this intersection
156 * are prohibitively expensive.
157 * </ul>
158 * This means that for some {@code Shapes} this method might
159 * return {@code true} even though the rectangular area does not
160 * intersect the {@code Shape}.
161 * The {@link java.awt.geom.Area Area} class performs
162 * more accurate computations of geometric intersection than most
163 * {@code Shape} objects and therefore can be used if a more precise
164 * answer is required.
165 *
166 * @param x the X coordinate of the upper-left corner
167 * of the specified rectangular area
168 * @param y the Y coordinate of the upper-left corner
169 * of the specified rectangular area
170 * @param w the width of the specified rectangular area
171 * @param h the height of the specified rectangular area
172 * @return <code>true</code> if the interior of the <code>Shape</code> and
173 * the interior of the rectangular area intersect, or are
174 * both highly likely to intersect and intersection calculations
175 * would be too expensive to perform; <code>false</code> otherwise.
176 * @see java.awt.geom.Area
177 * @since 1.2
178 */
179 public boolean intersects(double x, double y, double w, double h);
180
181 /**
182 * Tests if the interior of the <code>Shape</code> intersects the
183 * interior of a specified <code>Rectangle2D</code>.
184 * The {@code Shape.intersects()} method allows a {@code Shape}
185 * implementation to conservatively return {@code true} when:
186 * <ul>
187 * <li>
188 * there is a high probability that the <code>Rectangle2D</code> and the
189 * <code>Shape</code> intersect, but
190 * <li>
191 * the calculations to accurately determine this intersection
192 * are prohibitively expensive.
193 * </ul>
194 * This means that for some {@code Shapes} this method might
195 * return {@code true} even though the {@code Rectangle2D} does not
196 * intersect the {@code Shape}.
197 * The {@link java.awt.geom.Area Area} class performs
198 * more accurate computations of geometric intersection than most
199 * {@code Shape} objects and therefore can be used if a more precise
200 * answer is required.
201 *
202 * @param r the specified <code>Rectangle2D</code>
203 * @return <code>true</code> if the interior of the <code>Shape</code> and
204 * the interior of the specified <code>Rectangle2D</code>
205 * intersect, or are both highly likely to intersect and intersection
206 * calculations would be too expensive to perform; <code>false</code>
207 * otherwise.
208 * @see #intersects(double, double, double, double)
209 * @since 1.2
210 */
211 public boolean intersects(Rectangle2D r);
212
213 /**
214 * Tests if the interior of the <code>Shape</code> entirely contains
215 * the specified rectangular area. All coordinates that lie inside
216 * the rectangular area must lie within the <code>Shape</code> for the
217 * entire rectanglar area to be considered contained within the
218 * <code>Shape</code>.
219 * <p>
220 * The {@code Shape.contains()} method allows a {@code Shape}
221 * implementation to conservatively return {@code false} when:
222 * <ul>
223 * <li>
224 * the <code>intersect</code> method returns <code>true</code> and
225 * <li>
226 * the calculations to determine whether or not the
227 * <code>Shape</code> entirely contains the rectangular area are
228 * prohibitively expensive.
229 * </ul>
230 * This means that for some {@code Shapes} this method might
231 * return {@code false} even though the {@code Shape} contains
232 * the rectangular area.
233 * The {@link java.awt.geom.Area Area} class performs
234 * more accurate geometric computations than most
235 * {@code Shape} objects and therefore can be used if a more precise
236 * answer is required.
237 *
238 * @param x the X coordinate of the upper-left corner
239 * of the specified rectangular area
240 * @param y the Y coordinate of the upper-left corner
241 * of the specified rectangular area
242 * @param w the width of the specified rectangular area
243 * @param h the height of the specified rectangular area
244 * @return <code>true</code> if the interior of the <code>Shape</code>
245 * entirely contains the specified rectangular area;
246 * <code>false</code> otherwise or, if the <code>Shape</code>
247 * contains the rectangular area and the
248 * <code>intersects</code> method returns <code>true</code>
249 * and the containment calculations would be too expensive to
250 * perform.
251 * @see java.awt.geom.Area
252 * @see #intersects
253 * @since 1.2
254 */
255 public boolean contains(double x, double y, double w, double h);
256
257 /**
258 * Tests if the interior of the <code>Shape</code> entirely contains the
259 * specified <code>Rectangle2D</code>.
260 * The {@code Shape.contains()} method allows a {@code Shape}
261 * implementation to conservatively return {@code false} when:
262 * <ul>
263 * <li>
264 * the <code>intersect</code> method returns <code>true</code> and
265 * <li>
266 * the calculations to determine whether or not the
267 * <code>Shape</code> entirely contains the <code>Rectangle2D</code>
268 * are prohibitively expensive.
269 * </ul>
270 * This means that for some {@code Shapes} this method might
271 * return {@code false} even though the {@code Shape} contains
272 * the {@code Rectangle2D}.
273 * The {@link java.awt.geom.Area Area} class performs
274 * more accurate geometric computations than most
275 * {@code Shape} objects and therefore can be used if a more precise
276 * answer is required.
277 *
278 * @param r The specified <code>Rectangle2D</code>
279 * @return <code>true</code> if the interior of the <code>Shape</code>
280 * entirely contains the <code>Rectangle2D</code>;
281 * <code>false</code> otherwise or, if the <code>Shape</code>
282 * contains the <code>Rectangle2D</code> and the
283 * <code>intersects</code> method returns <code>true</code>
284 * and the containment calculations would be too expensive to
285 * perform.
286 * @see #contains(double, double, double, double)
287 * @since 1.2
288 */
289 public boolean contains(Rectangle2D r);
290
291 /**
292 * Returns an iterator object that iterates along the
293 * <code>Shape</code> boundary and provides access to the geometry of the
294 * <code>Shape</code> outline. If an optional {@link AffineTransform}
295 * is specified, the coordinates returned in the iteration are
296 * transformed accordingly.
297 * <p>
298 * Each call to this method returns a fresh <code>PathIterator</code>
299 * object that traverses the geometry of the <code>Shape</code> object
300 * independently from any other <code>PathIterator</code> objects in use
301 * at the same time.
302 * <p>
303 * It is recommended, but not guaranteed, that objects
304 * implementing the <code>Shape</code> interface isolate iterations
305 * that are in process from any changes that might occur to the original
306 * object's geometry during such iterations.
307 *
308 * @param at an optional <code>AffineTransform</code> to be applied to the
309 * coordinates as they are returned in the iteration, or
310 * <code>null</code> if untransformed coordinates are desired
311 * @return a new <code>PathIterator</code> object, which independently
312 * traverses the geometry of the <code>Shape</code>.
313 * @since 1.2
314 */
315 public PathIterator getPathIterator(AffineTransform at);
316
317 /**
318 * Returns an iterator object that iterates along the <code>Shape</code>
319 * boundary and provides access to a flattened view of the
320 * <code>Shape</code> outline geometry.
321 * <p>
322 * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are
323 * returned by the iterator.
324 * <p>
325 * If an optional <code>AffineTransform</code> is specified,
326 * the coordinates returned in the iteration are transformed
327 * accordingly.
328 * <p>
329 * The amount of subdivision of the curved segments is controlled
330 * by the <code>flatness</code> parameter, which specifies the
331 * maximum distance that any point on the unflattened transformed
332 * curve can deviate from the returned flattened path segments.
333 * Note that a limit on the accuracy of the flattened path might be
334 * silently imposed, causing very small flattening parameters to be
335 * treated as larger values. This limit, if there is one, is
336 * defined by the particular implementation that is used.
337 * <p>
338 * Each call to this method returns a fresh <code>PathIterator</code>
339 * object that traverses the <code>Shape</code> object geometry
340 * independently from any other <code>PathIterator</code> objects in use at
341 * the same time.
342 * <p>
343 * It is recommended, but not guaranteed, that objects
344 * implementing the <code>Shape</code> interface isolate iterations
345 * that are in process from any changes that might occur to the original
346 * object's geometry during such iterations.
347 *
348 * @param at an optional <code>AffineTransform</code> to be applied to the
349 * coordinates as they are returned in the iteration, or
350 * <code>null</code> if untransformed coordinates are desired
351 * @param flatness the maximum distance that the line segments used to
352 * approximate the curved segments are allowed to deviate
353 * from any point on the original curve
354 * @return a new <code>PathIterator</code> that independently traverses
355 * a flattened view of the geometry of the <code>Shape</code>.
356 * @since 1.2
357 */
358 public PathIterator getPathIterator(AffineTransform at,
359 double flatness);
360 }
|