History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/awt/Shape.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/awt/Shape.java+414−0
@@ -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+}