Shape


1   /*
2    * @(#)Shape.java   1.22 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt;
9   
10  import java.awt.geom.AffineTransform  ;
11  import java.awt.geom.PathIterator  ;
12  import java.awt.geom.Point2D  ;
13  import java.awt.geom.Rectangle2D  ;
14  
15  /**
16   * The <code>Shape</code> interface provides definitions for objects 
17   * that represent some form of geometric shape.  The <code>Shape</code>
18   * is described by a {@link PathIterator} object, which can express the 
19   * outline of the <code>Shape</code> as well as a rule for determining 
20   * how the outline divides the 2D plane into interior and exterior 
21   * points.  Each <code>Shape</code> object provides callbacks to get the 
22   * bounding box of the geometry, determine whether points or 
23   * rectangles lie partly or entirely within the interior
24   * of the <code>Shape</code>, and retrieve a <code>PathIterator</code>
25   * object that describes the trajectory path of the <code>Shape</code>
26   * outline.
27   * <p>
28   * <b>Definition of insideness:</b>
29   * A point is considered to lie inside a 
30   * <code>Shape</code> if and only if:
31   * <ul>
32   * <li> it lies completely
33   * inside the<code>Shape</code> boundary <i>or</i> 
34   * <li>
35   * it lies exactly on the <code>Shape</code> boundary <i>and</i> the 
36   * space immediately adjacent to the
37   * point in the increasing <code>X</code> direction is 
38   * entirely inside the boundary <i>or</i>
39   * <li>
40   * it lies exactly on a horizontal boundary segment <b>and</b> the
41   * space immediately adjacent to the point in the 
42   * increasing <code>Y</code> direction is inside the boundary.
43   * </ul>
44   * <p>The <code>contains</code> and <code>intersects</code> methods
45   * consider the interior of a <code>Shape</code> to be the area it
46   * encloses as if it were filled.  This means that these methods
47   * consider
48   * unclosed shapes to be implicitly closed for the purpose of
49   * determining if a shape contains or intersects a rectangle or if a
50   * shape contains a point.
51   * 
52   * @see java.awt.geom.PathIterator
53   * @see java.awt.geom.AffineTransform
54   * @see java.awt.geom.FlatteningPathIterator
55   * @see java.awt.geom.GeneralPath
56   *
57   * @version 1.19 06/24/98
58   * @author Jim Graham
59   */
60  public interface Shape {
61      /**
62       * Returns an integer {@link Rectangle} that completely encloses the
63       * <code>Shape</code>.  Note that there is no guarantee that the
64       * returned <code>Rectangle</code> is the smallest bounding box that
65       * encloses the <code>Shape</code>, only that the <code>Shape</code>
66       * lies entirely within the indicated  <code>Rectangle</code>.  The
67       * returned <code>Rectangle</code> might also fail to completely
68       * enclose the <code>Shape</code> if the <code>Shape</code> overflows
69       * the limited range of the integer data type.  The 
70       * <code>getBounds2D</code> method generally returns a
71       * tighter bounding box due to its greater flexibility in
72       * representation.
73       * @return an integer <code>Rectangle</code> that completely encloses
74       *                 the <code>Shape</code>.
75       * @see #getBounds2D
76       */
77      public Rectangle   getBounds();
78  
79      /**
80       * Returns a high precision and more accurate bounding box of
81       * the <code>Shape</code> than the <code>getBounds</code> method.
82       * Note that there is no guarantee that the returned 
83       * {@link Rectangle2D} is the smallest bounding box that encloses 
84       * the <code>Shape</code>, only that the <code>Shape</code> lies 
85       * entirely within the indicated <code>Rectangle2D</code>.  The 
86       * bounding box returned by this method is usually tighter than that 
87       * returned by the <code>getBounds</code> method and never fails due 
88       * to overflow problems since the return value can be an instance of 
89       * the <code>Rectangle2D</code> that uses double precision values to 
90       * store the dimensions.
91       * @return an instance of <code>Rectangle2D</code> that is a
92       *                 high-precision bounding box of the <code>Shape</code>.
93       * @see #getBounds
94       */
95      public Rectangle2D   getBounds2D();
96  
97      /**
98       * Tests if the specified coordinates are inside the boundary of the 
99       * <code>Shape</code>.
100      * @param x the specified x coordinate
101      * @param y the specified y coordinate
102      * @return <code>true</code> if the specified coordinates are inside 
103      *         the <code>Shape</code> boundary; <code>false</code>
104      *         otherwise.
105      */
106     public boolean contains(double x, double y);
107 
108     /**
109      * Tests if a specified {@link Point2D} is inside the boundary
110      * of the <code>Shape</code>.
111      * @param p a specified <code>Point2D</code>
112      * @return <code>true</code> if the specified <code>Point2D</code> is 
113      *          inside the boundary of the <code>Shape</code>;
114      *      <code>false</code> otherwise.
115      */
116     public boolean contains(Point2D   p);
117 
118     /**
119      * Tests if the interior of the <code>Shape</code> intersects the 
120      * interior of a specified rectangular area.
121      * The rectangular area is considered to intersect the <code>Shape</code> 
122      * if any point is contained in both the interior of the 
123      * <code>Shape</code> and the specified rectangular area.
124      * <p>
125      * This method might conservatively return <code>true</code> when:
126      * <ul>
127      * <li>
128      * there is a high probability that the rectangular area and the
129      * <code>Shape</code> intersect, but
130      * <li>
131      * the calculations to accurately determine this intersection
132      * are prohibitively expensive.
133      * </ul>
134      * This means that this method might return <code>true</code> even
135      * though the rectangular area does not intersect the <code>Shape</code>.
136      * The {@link java.awt.geom.Area Area} class can be used to perform 
137      * more accurate computations of geometric intersection for any 
138      * <code>Shape</code> object if a more precise answer is required.
139      * @param x the x coordinate of the specified rectangular area
140      * @param y the y coordinate of the specified rectangular area
141      * @param w the width of the specified rectangular area
142      * @param h the height of the specified rectangular area
143      * @return <code>true</code> if the interior of the <code>Shape</code> and
144      *      the interior of the rectangular area intersect, or are
145      *      both highly likely to intersect and intersection calculations 
146      *      would be too expensive to perform; <code>false</code> otherwise.
147      * @see java.awt.geom.Area
148      */
149     public boolean intersects(double x, double y, double w, double h);
150 
151     /**
152      * Tests if the interior of the <code>Shape</code> intersects the 
153      * interior of a specified <code>Rectangle2D</code>.
154      * This method might conservatively return <code>true</code> when:
155      * <ul>
156      * <li>
157      * there is a high probability that the <code>Rectangle2D</code> and the
158      * <code>Shape</code> intersect, but
159      * <li>
160      * the calculations to accurately determine this intersection
161      * are prohibitively expensive.
162      * </ul>
163      * This means that this method might return <code>true</code> even
164      * though the <code>Rectangle2D</code> does not intersect the
165      * <code>Shape</code>. 
166      * @param r the specified <code>Rectangle2D</code>
167      * @return <code>true</code> if the interior of the <code>Shape</code> and  
168      *      the interior of the specified <code>Rectangle2D</code>
169      *      intersect, or are both highly likely to intersect and intersection
170      *      calculations would be too expensive to perform; <code>false</code>
171      *      otherwise.
172      * @see #intersects(double, double, double, double)
173      */
174     public boolean intersects(Rectangle2D   r);
175 
176     /**
177      * Tests if the interior of the <code>Shape</code> entirely contains 
178      * the specified rectangular area.  All coordinates that lie inside
179      * the rectangular area must lie within the <code>Shape</code> for the
180      * entire rectanglar area to be considered contained within the 
181      * <code>Shape</code>.
182      * <p>
183      * This method might conservatively return <code>false</code> when:
184      * <ul>
185      * <li>
186      * the <code>intersect</code> method returns <code>true</code> and
187      * <li>
188      * the calculations to determine whether or not the
189      * <code>Shape</code> entirely contains the rectangular area are
190      * prohibitively expensive.
191      * </ul>
192      * This means that this method might return <code>false</code> even
193      * though the <code>Shape</code> contains the rectangular area.
194      * The <code>Area</code> class can be used to perform more accurate 
195      * computations of geometric intersection for any <code>Shape</code>
196      * object if a more precise answer is required.
197      * @param x the x coordinate of the specified rectangular area
198      * @param y the y coordinate of the specified rectangular area
199      * @param w the width of the specified rectangular area
200      * @param h the height of the specified rectangular area
201      * @return <code>true</code> if the interior of the <code>Shape</code>
202      *      entirely contains the specified rectangular area;
203      *      <code>false</code> otherwise or, if the <code>Shape</code>    
204      *      contains the rectangular area and the   
205      *      <code>intersects</code> method returns <code>true</code> 
206      *      and the containment calculations would be too expensive to
207      *      perform.
208      * @see java.awt.geom.Area
209      * @see #intersects
210      */
211     public boolean contains(double x, double y, double w, double h);
212 
213     /**
214      * Tests if the interior of the <code>Shape</code> entirely contains the 
215      * specified <code>Rectangle2D</code>.
216      * This method might conservatively return <code>false</code> when:
217      * <ul>
218      * <li>
219      * the <code>intersect</code> method returns <code>true</code> and
220      * <li>
221      * the calculations to determine whether or not the
222      * <code>Shape</code> entirely contains the <code>Rectangle2D</code>
223      * are prohibitively expensive.
224      * </ul>
225      * This means that this method might return <code>false</code> even   
226      * though the <code>Shape</code> contains the
227      * <code>Rectangle2D</code>.
228      * The <code>Area</code> class can be used to perform more accurate 
229      * computations of geometric intersection for any <code>Shape</code>  
230      * object if a more precise answer is required.
231      * @param r The specified <code>Rectangle2D</code>
232      * @return <code>true</code> if the interior of the <code>Shape</code>
233      *          entirely contains the <code>Rectangle2D</code>;
234      *          <code>false</code> otherwise or, if the <code>Shape</code>
235      *          contains the <code>Rectangle2D</code> and the
236      *          <code>intersects</code> method returns <code>true</code>
237      *          and the containment calculations would be too expensive to
238      *          perform. 
239      * @see #contains(double, double, double, double)
240      */
241     public boolean contains(Rectangle2D   r);
242 
243     /**
244      * Returns an iterator object that iterates along the 
245      * <code>Shape</code> boundary and provides access to the geometry of the 
246      * <code>Shape</code> outline.  If an optional {@link AffineTransform}
247      * is specified, the coordinates returned in the iteration are
248      * transformed accordingly.
249      * <p>
250      * Each call to this method returns a fresh <code>PathIterator</code>
251      * object that traverses the geometry of the <code>Shape</code> object
252      * independently from any other <code>PathIterator</code> objects in use
253      * at the same time.
254      * <p>
255      * It is recommended, but not guaranteed, that objects 
256      * implementing the <code>Shape</code> interface isolate iterations
257      * that are in process from any changes that might occur to the original
258      * object's geometry during such iterations.
259      * <p>
260      * Before using a particular implementation of the <code>Shape</code> 
261      * interface in more than one thread simultaneously, refer to its 
262      * documentation to verify that it guarantees that iterations are isolated 
263      * from modifications.
264      * @param at an optional <code>AffineTransform</code> to be applied to the
265      *      coordinates as they are returned in the iteration, or 
266      *      <code>null</code> if untransformed coordinates are desired
267      * @return a new <code>PathIterator</code> object, which independently    
268      *      traverses the geometry of the <code>Shape</code>.
269      */
270     public PathIterator   getPathIterator(AffineTransform   at);
271 
272     /**
273      * Returns an iterator object that iterates along the <code>Shape</code>
274      * boundary and provides access to a flattened view of the
275      * <code>Shape</code> outline geometry.
276      * <p>
277      * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are
278      * returned by the iterator.
279      * <p>
280      * If an optional <code>AffineTransform</code> is specified,
281      * the coordinates returned in the iteration are transformed
282      * accordingly.
283      * <p>
284      * The amount of subdivision of the curved segments is controlled
285      * by the <code>flatness</code> parameter, which specifies the
286      * maximum distance that any point on the unflattened transformed
287      * curve can deviate from the returned flattened path segments.
288      * Note that a limit on the accuracy of the flattened path might be
289      * silently imposed, causing very small flattening parameters to be
290      * treated as larger values.  This limit, if there is one, is
291      * defined by the particular implementation that is used.
292      * <p>
293      * Each call to this method returns a fresh <code>PathIterator</code>
294      * object that traverses the <code>Shape</code> object geometry 
295      * independently from any other <code>PathIterator</code> objects in use at
296      * the same time.
297      * <p>
298      * It is recommended, but not guaranteed, that objects 
299      * implementing the <code>Shape</code> interface isolate iterations
300      * that are in process from any changes that might occur to the original
301      * object's geometry during such iterations.
302      * <p>
303      * Before using a particular implementation of this interface in more
304      * than one thread simultaneously, refer to its documentation to
305      * verify that it guarantees that iterations are isolated from
306      * modifications.
307      * @param at an optional <code>AffineTransform</code> to be applied to the
308      *      coordinates as they are returned in the iteration, or 
309      *      <code>null</code> if untransformed coordinates are desired
310      * @param flatness the maximum distance that the line segments used to
311      *          approximate the curved segments are allowed to deviate
312      *          from any point on the original curve
313      * @return a new <code>PathIterator</code> that independently traverses 
314      *      the <code>Shape</code> geometry.
315     */
316     public PathIterator   getPathIterator(AffineTransform   at, double flatness);
317 }
318
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags