View Javadoc
1   /*
2    * Copyright (c) 1997, 2011, 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.geom;
27  
28  import java.awt.Shape;
29  import java.awt.Rectangle;
30  import java.beans.Transient;
31  
32  /**
33   * <code>RectangularShape</code> is the base class for a number of
34   * {@link Shape} objects whose geometry is defined by a rectangular frame.
35   * This class does not directly specify any specific geometry by
36   * itself, but merely provides manipulation methods inherited by
37   * a whole category of <code>Shape</code> objects.
38   * The manipulation methods provided by this class can be used to
39   * query and modify the rectangular frame, which provides a reference
40   * for the subclasses to define their geometry.
41   *
42   * @author      Jim Graham
43   * @since 1.2
44   */
45  public abstract class RectangularShape implements Shape, Cloneable {
46  
47      /**
48       * This is an abstract class that cannot be instantiated directly.
49       *
50       * @see Arc2D
51       * @see Ellipse2D
52       * @see Rectangle2D
53       * @see RoundRectangle2D
54       * @since 1.2
55       */
56      protected RectangularShape() {
57      }
58  
59      /**
60       * Returns the X coordinate of the upper-left corner of
61       * the framing rectangle in <code>double</code> precision.
62       * @return the X coordinate of the upper-left corner of
63       * the framing rectangle.
64       * @since 1.2
65       */
66      public abstract double getX();
67  
68      /**
69       * Returns the Y coordinate of the upper-left corner of
70       * the framing rectangle in <code>double</code> precision.
71       * @return the Y coordinate of the upper-left corner of
72       * the framing rectangle.
73       * @since 1.2
74       */
75      public abstract double getY();
76  
77      /**
78       * Returns the width of the framing rectangle in
79       * <code>double</code> precision.
80       * @return the width of the framing rectangle.
81       * @since 1.2
82       */
83      public abstract double getWidth();
84  
85      /**
86       * Returns the height of the framing rectangle
87       * in <code>double</code> precision.
88       * @return the height of the framing rectangle.
89       * @since 1.2
90       */
91      public abstract double getHeight();
92  
93      /**
94       * Returns the smallest X coordinate of the framing
95       * rectangle of the <code>Shape</code> in <code>double</code>
96       * precision.
97       * @return the smallest X coordinate of the framing
98       *          rectangle of the <code>Shape</code>.
99       * @since 1.2
100      */
101     public double getMinX() {
102         return getX();
103     }
104 
105     /**
106      * Returns the smallest Y coordinate of the framing
107      * rectangle of the <code>Shape</code> in <code>double</code>
108      * precision.
109      * @return the smallest Y coordinate of the framing
110      *          rectangle of the <code>Shape</code>.
111      * @since 1.2
112      */
113     public double getMinY() {
114         return getY();
115     }
116 
117     /**
118      * Returns the largest X coordinate of the framing
119      * rectangle of the <code>Shape</code> in <code>double</code>
120      * precision.
121      * @return the largest X coordinate of the framing
122      *          rectangle of the <code>Shape</code>.
123      * @since 1.2
124      */
125     public double getMaxX() {
126         return getX() + getWidth();
127     }
128 
129     /**
130      * Returns the largest Y coordinate of the framing
131      * rectangle of the <code>Shape</code> in <code>double</code>
132      * precision.
133      * @return the largest Y coordinate of the framing
134      *          rectangle of the <code>Shape</code>.
135      * @since 1.2
136      */
137     public double getMaxY() {
138         return getY() + getHeight();
139     }
140 
141     /**
142      * Returns the X coordinate of the center of the framing
143      * rectangle of the <code>Shape</code> in <code>double</code>
144      * precision.
145      * @return the X coordinate of the center of the framing rectangle
146      *          of the <code>Shape</code>.
147      * @since 1.2
148      */
149     public double getCenterX() {
150         return getX() + getWidth() / 2.0;
151     }
152 
153     /**
154      * Returns the Y coordinate of the center of the framing
155      * rectangle of the <code>Shape</code> in <code>double</code>
156      * precision.
157      * @return the Y coordinate of the center of the framing rectangle
158      *          of the <code>Shape</code>.
159      * @since 1.2
160      */
161     public double getCenterY() {
162         return getY() + getHeight() / 2.0;
163     }
164 
165     /**
166      * Returns the framing {@link Rectangle2D}
167      * that defines the overall shape of this object.
168      * @return a <code>Rectangle2D</code>, specified in
169      * <code>double</code> coordinates.
170      * @see #setFrame(double, double, double, double)
171      * @see #setFrame(Point2D, Dimension2D)
172      * @see #setFrame(Rectangle2D)
173      * @since 1.2
174      */
175     @Transient
176     public Rectangle2D getFrame() {
177         return new Rectangle2D.Double(getX(), getY(), getWidth(), getHeight());
178     }
179 
180     /**
181      * Determines whether the <code>RectangularShape</code> is empty.
182      * When the <code>RectangularShape</code> is empty, it encloses no
183      * area.
184      * @return <code>true</code> if the <code>RectangularShape</code> is empty;
185      *          <code>false</code> otherwise.
186      * @since 1.2
187      */
188     public abstract boolean isEmpty();
189 
190     /**
191      * Sets the location and size of the framing rectangle of this
192      * <code>Shape</code> to the specified rectangular values.
193      *
194      * @param x the X coordinate of the upper-left corner of the
195      *          specified rectangular shape
196      * @param y the Y coordinate of the upper-left corner of the
197      *          specified rectangular shape
198      * @param w the width of the specified rectangular shape
199      * @param h the height of the specified rectangular shape
200      * @see #getFrame
201      * @since 1.2
202      */
203     public abstract void setFrame(double x, double y, double w, double h);
204 
205     /**
206      * Sets the location and size of the framing rectangle of this
207      * <code>Shape</code> to the specified {@link Point2D} and
208      * {@link Dimension2D}, respectively.  The framing rectangle is used
209      * by the subclasses of <code>RectangularShape</code> to define
210      * their geometry.
211      * @param loc the specified <code>Point2D</code>
212      * @param size the specified <code>Dimension2D</code>
213      * @see #getFrame
214      * @since 1.2
215      */
216     public void setFrame(Point2D loc, Dimension2D size) {
217         setFrame(loc.getX(), loc.getY(), size.getWidth(), size.getHeight());
218     }
219 
220     /**
221      * Sets the framing rectangle of this <code>Shape</code> to
222      * be the specified <code>Rectangle2D</code>.  The framing rectangle is
223      * used by the subclasses of <code>RectangularShape</code> to define
224      * their geometry.
225      * @param r the specified <code>Rectangle2D</code>
226      * @see #getFrame
227      * @since 1.2
228      */
229     public void setFrame(Rectangle2D r) {
230         setFrame(r.getX(), r.getY(), r.getWidth(), r.getHeight());
231     }
232 
233     /**
234      * Sets the diagonal of the framing rectangle of this <code>Shape</code>
235      * based on the two specified coordinates.  The framing rectangle is
236      * used by the subclasses of <code>RectangularShape</code> to define
237      * their geometry.
238      *
239      * @param x1 the X coordinate of the start point of the specified diagonal
240      * @param y1 the Y coordinate of the start point of the specified diagonal
241      * @param x2 the X coordinate of the end point of the specified diagonal
242      * @param y2 the Y coordinate of the end point of the specified diagonal
243      * @since 1.2
244      */
245     public void setFrameFromDiagonal(double x1, double y1,
246                                      double x2, double y2) {
247         if (x2 < x1) {
248             double t = x1;
249             x1 = x2;
250             x2 = t;
251         }
252         if (y2 < y1) {
253             double t = y1;
254             y1 = y2;
255             y2 = t;
256         }
257         setFrame(x1, y1, x2 - x1, y2 - y1);
258     }
259 
260     /**
261      * Sets the diagonal of the framing rectangle of this <code>Shape</code>
262      * based on two specified <code>Point2D</code> objects.  The framing
263      * rectangle is used by the subclasses of <code>RectangularShape</code>
264      * to define their geometry.
265      *
266      * @param p1 the start <code>Point2D</code> of the specified diagonal
267      * @param p2 the end <code>Point2D</code> of the specified diagonal
268      * @since 1.2
269      */
270     public void setFrameFromDiagonal(Point2D p1, Point2D p2) {
271         setFrameFromDiagonal(p1.getX(), p1.getY(), p2.getX(), p2.getY());
272     }
273 
274     /**
275      * Sets the framing rectangle of this <code>Shape</code>
276      * based on the specified center point coordinates and corner point
277      * coordinates.  The framing rectangle is used by the subclasses of
278      * <code>RectangularShape</code> to define their geometry.
279      *
280      * @param centerX the X coordinate of the specified center point
281      * @param centerY the Y coordinate of the specified center point
282      * @param cornerX the X coordinate of the specified corner point
283      * @param cornerY the Y coordinate of the specified corner point
284      * @since 1.2
285      */
286     public void setFrameFromCenter(double centerX, double centerY,
287                                    double cornerX, double cornerY) {
288         double halfW = Math.abs(cornerX - centerX);
289         double halfH = Math.abs(cornerY - centerY);
290         setFrame(centerX - halfW, centerY - halfH, halfW * 2.0, halfH * 2.0);
291     }
292 
293     /**
294      * Sets the framing rectangle of this <code>Shape</code> based on a
295      * specified center <code>Point2D</code> and corner
296      * <code>Point2D</code>.  The framing rectangle is used by the subclasses
297      * of <code>RectangularShape</code> to define their geometry.
298      * @param center the specified center <code>Point2D</code>
299      * @param corner the specified corner <code>Point2D</code>
300      * @since 1.2
301      */
302     public void setFrameFromCenter(Point2D center, Point2D corner) {
303         setFrameFromCenter(center.getX(), center.getY(),
304                            corner.getX(), corner.getY());
305     }
306 
307     /**
308      * {@inheritDoc}
309      * @since 1.2
310      */
311     public boolean contains(Point2D p) {
312         return contains(p.getX(), p.getY());
313     }
314 
315     /**
316      * {@inheritDoc}
317      * @since 1.2
318      */
319     public boolean intersects(Rectangle2D r) {
320         return intersects(r.getX(), r.getY(), r.getWidth(), r.getHeight());
321     }
322 
323     /**
324      * {@inheritDoc}
325      * @since 1.2
326      */
327     public boolean contains(Rectangle2D r) {
328         return contains(r.getX(), r.getY(), r.getWidth(), r.getHeight());
329     }
330 
331     /**
332      * {@inheritDoc}
333      * @since 1.2
334      */
335     public Rectangle getBounds() {
336         double width = getWidth();
337         double height = getHeight();
338         if (width < 0 || height < 0) {
339             return new Rectangle();
340         }
341         double x = getX();
342         double y = getY();
343         double x1 = Math.floor(x);
344         double y1 = Math.floor(y);
345         double x2 = Math.ceil(x + width);
346         double y2 = Math.ceil(y + height);
347         return new Rectangle((int) x1, (int) y1,
348                                       (int) (x2 - x1), (int) (y2 - y1));
349     }
350 
351     /**
352      * Returns an iterator object that iterates along the
353      * <code>Shape</code> object's boundary and provides access to a
354      * flattened view of the outline of the <code>Shape</code>
355      * object's geometry.
356      * <p>
357      * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types will
358      * be returned by the iterator.
359      * <p>
360      * The amount of subdivision of the curved segments is controlled
361      * by the <code>flatness</code> parameter, which specifies the
362      * maximum distance that any point on the unflattened transformed
363      * curve can deviate from the returned flattened path segments.
364      * An optional {@link AffineTransform} can
365      * be specified so that the coordinates returned in the iteration are
366      * transformed accordingly.
367      * @param at an optional <code>AffineTransform</code> to be applied to the
368      *          coordinates as they are returned in the iteration,
369      *          or <code>null</code> if untransformed coordinates are desired.
370      * @param flatness the maximum distance that the line segments used to
371      *          approximate the curved segments are allowed to deviate
372      *          from any point on the original curve
373      * @return a <code>PathIterator</code> object that provides access to
374      *          the <code>Shape</code> object's flattened geometry.
375      * @since 1.2
376      */
377     public PathIterator getPathIterator(AffineTransform at, double flatness) {
378         return new FlatteningPathIterator(getPathIterator(at), flatness);
379     }
380 
381     /**
382      * Creates a new object of the same class and with the same
383      * contents as this object.
384      * @return     a clone of this instance.
385      * @exception  OutOfMemoryError            if there is not enough memory.
386      * @see        java.lang.Cloneable
387      * @since      1.2
388      */
389     public Object clone() {
390         try {
391             return super.clone();
392         } catch (CloneNotSupportedException e) {
393             // this shouldn't happen, since we are Cloneable
394             throw new InternalError(e);
395         }
396     }
397 }