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: }
|
