1 /* Rectangle.java -- represents a graphics rectangle
2 Copyright (C) 1999, 2000, 2001, 2002 Free Software Foundation
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
41 import java
.awt
.geom
.Rectangle2D
;
42 import java
.io
.Serializable
;
45 * This class represents a rectangle and all the interesting things you
46 * might want to do with it. Note that the coordinate system uses
47 * the origin (0,0) as the top left of the screen, with the x and y
48 * values increasing as they move to the right and down respectively.
50 * <p>It is valid for a rectangle to have negative width or height; but it
51 * is considered to have no area or internal points. Therefore, the behavior
52 * in methods like <code>contains</code> or <code>intersects</code> is
53 * undefined unless the rectangle has positive width and height.
55 * <p>There are some public fields; if you mess with them in an inconsistent
56 * manner, it is your own fault when you get NullPointerException,
57 * ArrayIndexOutOfBoundsException, or invalid results. Also, this class is
60 * @author Warren Levy (warrenl@cygnus.com)
61 * @author Aaron M. Renn (arenn@urbanophile.com)
62 * @author Eric Blake (ebb9@email.byu.edu)
64 * @status updated to 1.4
66 public class Rectangle
extends Rectangle2D
implements Shape
, Serializable
69 * Compatible with JDK 1.0+.
71 private static final long serialVersionUID
= -4345857070255674764L;
74 * The X coordinate of the top-left corner of the rectangle.
76 * @see #setLocation(int, int)
78 * @serial the x coordinate
83 * The Y coordinate of the top-left corner of the rectangle.
85 * @see #setLocation(int, int)
87 * @serial the y coordinate
92 * The width of the rectangle.
94 * @see #setSize(int, int)
101 * The height of the rectangle.
103 * @see #setSize(int, int)
110 * Initializes a new instance of <code>Rectangle</code> with a top
111 * left corner at (0,0) and a width and height of 0.
118 * Initializes a new instance of <code>Rectangle</code> from the
119 * coordinates of the specified rectangle.
121 * @param r the rectangle to copy from
122 * @throws NullPointerException if r is null
125 public Rectangle(Rectangle r
)
134 * Initializes a new instance of <code>Rectangle</code> from the specified
137 * @param x the X coordinate of the top left corner
138 * @param y the Y coordinate of the top left corner
139 * @param width the width of the rectangle
140 * @param height the height of the rectangle
142 public Rectangle(int x
, int y
, int width
, int height
)
147 this.height
= height
;
151 * Initializes a new instance of <code>Rectangle</code> with the specified
152 * width and height. The upper left corner of the rectangle will be at
155 * @param width the width of the rectangle
156 * @param height the height of the rectange
158 public Rectangle(int width
, int height
)
161 this.height
= height
;
165 * Initializes a new instance of <code>Rectangle</code> with a top-left
166 * corner represented by the specified point and the width and height
167 * represented by the specified dimension.
169 * @param p the upper left corner of the rectangle
170 * @param d the width and height of the rectangle
171 * @throws NullPointerException if p or d is null
173 public Rectangle(Point p
, Dimension d
)
182 * Initializes a new instance of <code>Rectangle</code> with a top left
183 * corner at the specified point and a width and height of zero.
185 * @param p the upper left corner of the rectangle
187 public Rectangle(Point p
)
194 * Initializes a new instance of <code>Rectangle</code> with an
195 * upper left corner at the origin (0,0) and a width and height represented
196 * by the specified dimension.
198 * @param d the width and height of the rectangle
200 public Rectangle(Dimension d
)
207 * Get the X coordinate of the upper-left corner.
209 * @return the value of x, as a double
217 * Get the Y coordinate of the upper-left corner.
219 * @return the value of y, as a double
227 * Get the width of the rectangle.
229 * @return the value of width, as a double
231 public double getWidth()
237 * Get the height of the rectangle.
239 * @return the value of height, as a double
241 public double getHeight()
247 * Returns the bounds of this rectangle. A pretty useless method, as this
248 * is already a rectangle; it is included to mimic the
249 * <code>getBounds</code> method in Component.
251 * @return a copy of this rectangle
252 * @see #setBounds(Rectangle)
255 public Rectangle
getBounds()
257 return new Rectangle(this);
261 * Returns the high-precision bounds of this rectangle. A pretty useless
262 * method, as this is already a rectangle.
264 * @return a copy of this rectangle
265 * @see #setBounds(Rectangle)
268 public Rectangle2D
getBounds2D()
270 return new Rectangle(x
, y
, width
, height
);
274 * Updates this rectangle to match the dimensions of the specified
277 * @param r the rectangle to update from
278 * @throws NullPointerException if r is null
279 * @see #setBounds(int, int, int, int)
282 public void setBounds(Rectangle r
)
284 setBounds (r
.x
, r
.y
, r
.width
, r
.height
);
288 * Updates this rectangle to have the specified dimensions.
290 * @param x the new X coordinate of the upper left hand corner
291 * @param y the new Y coordinate of the upper left hand corner
292 * @param width the new width of this rectangle
293 * @param height the new height of this rectangle
296 public void setBounds(int x
, int y
, int width
, int height
)
298 reshape (x
, y
, width
, height
);
302 * Updates this rectangle to have the specified dimensions, as rounded to
305 * @param x the new X coordinate of the upper left hand corner
306 * @param y the new Y coordinate of the upper left hand corner
307 * @param width the new width of this rectangle
308 * @param height the new height of this rectangle
311 public void setRect(double x
, double y
, double width
, double height
)
315 this.width
= (int) width
;
316 this.height
= (int) height
;
320 * Updates this rectangle to have the specified dimensions.
322 * @param x the new X coordinate of the upper left hand corner
323 * @param y the new Y coordinate of the upper left hand corner
324 * @param width the new width of this rectangle
325 * @param height the new height of this rectangle
326 * @deprecated use {@link #setBounds(int, int, int, int)} instead
328 public void reshape(int x
, int y
, int width
, int height
)
333 this.height
= height
;
337 * Returns the location of this rectangle, which is the coordinates of
338 * its upper left corner.
340 * @return the point where this rectangle is located
341 * @see #setLocation(Point)
344 public Point
getLocation()
346 return new Point(x
,y
);
350 * Moves the location of this rectangle by setting its upper left
351 * corner to the specified point.
353 * @param p the point to move the rectangle to
354 * @throws NullPointerException if p is null
355 * @see #getLocation()
358 public void setLocation(Point p
)
360 setLocation (p
.x
, p
.y
);
364 * Moves the location of this rectangle by setting its upper left
365 * corner to the specified coordinates.
367 * @param x the new X coordinate for this rectangle
368 * @param y the new Y coordinate for this rectangle
371 public void setLocation(int x
, int y
)
377 * Moves the location of this rectangle by setting its upper left
378 * corner to the specified coordinates.
380 * @param x the new X coordinate for this rectangle
381 * @param y the new Y coordinate for this rectangle
382 * @deprecated use {@link #setLocation(int, int)} instead
384 public void move(int x
, int y
)
391 * Translate the location of this rectangle by the given amounts.
393 * @param dx the x distance to move by
394 * @param dy the y distance to move by
395 * @see #setLocation(int, int)
397 public void translate(int dx
, int dy
)
404 * Returns the size of this rectangle.
406 * @return the size of this rectangle
407 * @see #setSize(Dimension)
410 public Dimension
getSize()
412 return new Dimension(width
, height
);
416 * Sets the size of this rectangle based on the specified dimensions.
418 * @param d the new dimensions of the rectangle
419 * @throws NullPointerException if d is null
423 public void setSize(Dimension d
)
425 setSize (d
.width
, d
.height
);
429 * Sets the size of this rectangle based on the specified dimensions.
431 * @param width the new width of the rectangle
432 * @param height the new height of the rectangle
435 public void setSize(int width
, int height
)
437 resize (width
, height
);
441 * Sets the size of this rectangle based on the specified dimensions.
443 * @param width the new width of the rectangle
444 * @param height the new height of the rectangle
445 * @deprecated use {@link #setSize(int, int)} instead
447 public void resize(int width
, int height
)
450 this.height
= height
;
454 * Tests whether or not the specified point is inside this rectangle.
455 * According to the contract of Shape, a point on the border is in only if
456 * it has an adjacent point inside the rectangle in either the increasing
459 * @param p the point to test
460 * @return true if the point is inside the rectangle
461 * @throws NullPointerException if p is null
462 * @see #contains(int, int)
465 public boolean contains(Point p
)
467 return contains (p
.x
, p
.y
);
471 * Tests whether or not the specified point is inside this rectangle.
472 * According to the contract of Shape, a point on the border is in only if
473 * it has an adjacent point inside the rectangle in either the increasing
476 * @param x the X coordinate of the point to test
477 * @param y the Y coordinate of the point to test
478 * @return true if the point is inside the rectangle
481 public boolean contains(int x
, int y
)
483 return inside (x
, y
);
487 * Checks whether all points in the given rectangle are contained in this
490 * @param r the rectangle to check
491 * @return true if r is contained in this rectangle
492 * @throws NullPointerException if r is null
493 * @see #contains(int, int, int, int)
496 public boolean contains(Rectangle r
)
498 return contains (r
.x
, r
.y
, r
.width
, r
.height
);
502 * Checks whether all points in the given rectangle are contained in this
505 * @param x the x coordinate of the rectangle to check
506 * @param y the y coordinate of the rectangle to check
507 * @param w the width of the rectangle to check
508 * @param h the height of the rectangle to check
509 * @return true if the parameters are contained in this rectangle
512 public boolean contains(int x
, int y
, int w
, int h
)
514 return width
> 0 && height
> 0 && w
> 0 && h
> 0
515 && x
>= this.x
&& x
+ w
<= this.x
+ this.width
516 && y
>= this.y
&& y
+ h
<= this.y
+ this.height
;
520 * Tests whether or not the specified point is inside this rectangle.
522 * @param x the X coordinate of the point to test
523 * @param y the Y coordinate of the point to test
524 * @return true if the point is inside the rectangle
525 * @deprecated use {@link #contains(int, int)} instead
527 public boolean inside(int x
, int y
)
529 return width
> 0 && height
> 0
530 && x
>= this.x
&& x
< this.x
+ width
531 && y
>= this.y
&& y
< this.y
+ height
;
535 * Tests whether or not the specified rectangle intersects this rectangle.
536 * This means the two rectangles share at least one internal point.
538 * @param r the rectangle to test against
539 * @return true if the specified rectangle intersects this one
540 * @throws NullPointerException if r is null
543 public boolean intersects(Rectangle r
)
545 return r
.width
> 0 && r
.height
> 0 && width
> 0 && height
> 0
546 && r
.x
< x
+ width
&& r
.x
+ r
.width
> x
547 && r
.y
< y
+ height
&& r
.y
+ r
.height
> y
;
551 * Determines the rectangle which is formed by the intersection of this
552 * rectangle with the specified rectangle. If the two do not intersect,
553 * an empty rectangle will be returned (meaning the width and/or height
554 * will be non-positive).
556 * @param r the rectange to calculate the intersection with
557 * @return a new rectangle bounding the intersection
558 * @throws NullPointerException if r is null
560 public Rectangle
intersection(Rectangle r
)
562 Rectangle res
= new Rectangle();
563 intersect(this, r
, res
);
568 * Returns the smallest rectangle that contains both this rectangle
569 * and the specified rectangle.
571 * @param r the rectangle to compute the union with
572 * @return the smallest rectangle containing both rectangles
573 * @throws NullPointerException if r is null
575 public Rectangle
union(Rectangle r
)
577 Rectangle res
= new Rectangle();
583 * Modifies this rectangle so that it represents the smallest rectangle
584 * that contains both the existing rectangle and the specified point.
585 * However, if the point falls on one of the two borders which are not
586 * inside the rectangle, a subsequent call to <code>contains</code> may
589 * @param x the X coordinate of the point to add to this rectangle
590 * @param y the Y coordinate of the point to add to this rectangle
592 public void add(int x
, int y
)
594 add((double) x
, (double) y
);
598 * Modifies this rectangle so that it represents the smallest rectangle
599 * that contains both the existing rectangle and the specified point.
600 * However, if the point falls on one of the two borders which are not
601 * inside the rectangle, a subsequent call to <code>contains</code> may
604 * @param p the point to add to this rectangle
605 * @throws NullPointerException if p is null
607 public void add(Point p
)
609 add((double) p
.x
, (double) p
.y
);
613 * Modifies this rectangle so that it represents the smallest rectangle
614 * that contains both the existing rectangle and the specified rectangle.
616 * @param r the rectangle to add to this rectangle
617 * @throws NullPointerException if r is null
618 * @see #union(Rectangle)
620 public void add(Rectangle r
)
622 union(this, r
, this);
626 * Expands the rectangle by the specified amount. The horizontal
627 * and vertical expansion values are applied both to the X,Y coordinate
628 * of this rectangle, and its width and height. Thus the width and
629 * height will increase by 2h and 2v accordingly.
631 * @param h the horizontal expansion value
632 * @param v the vertical expansion value
634 public void grow(int h
, int v
)
643 * Tests whether or not this rectangle is empty. An empty rectangle
644 * has a non-positive width or height.
646 * @return true if the rectangle is empty
648 public boolean isEmpty()
650 return width
<= 0 || height
<= 0;
654 * Determine where the point lies with respect to this rectangle. The
655 * result will be the binary OR of the appropriate bit masks.
657 * @param x the x coordinate to check
658 * @param y the y coordinate to check
659 * @return the binary OR of the result
666 public int outcode(double x
, double y
)
670 result
|= OUT_LEFT
| OUT_RIGHT
;
673 else if (x
> this.x
+ width
)
676 result
|= OUT_BOTTOM
| OUT_TOP
;
677 else if (y
< this.y
) // Remember that +y heads top-to-bottom.
679 else if (y
> this.y
+ height
)
680 result
|= OUT_BOTTOM
;
685 * Determines the rectangle which is formed by the intersection of this
686 * rectangle with the specified rectangle. If the two do not intersect,
687 * an empty rectangle will be returned (meaning the width and/or height
688 * will be non-positive).
690 * @param r the rectange to calculate the intersection with
691 * @return a new rectangle bounding the intersection
692 * @throws NullPointerException if r is null
695 public Rectangle2D
createIntersection(Rectangle2D r
)
697 // Favor runtime type of other rectangle.
698 Rectangle2D res
= r
.getBounds2D();
699 intersect(this, r
, res
);
704 * Returns the smallest rectangle that contains both this rectangle
705 * and the specified rectangle.
707 * @param r the rectangle to compute the union with
708 * @return the smallest rectangle containing both rectangles
709 * @throws NullPointerException if r is null
712 public Rectangle2D
createUnion(Rectangle2D r
)
714 // Favor runtime type of other rectangle.
715 Rectangle2D res
= r
.getBounds2D();
721 * Tests this rectangle for equality against the specified object. This
722 * will be true if an only if the specified object is an instance of
723 * Rectangle2D with the same coordinates and dimensions.
725 * @param obj the object to test against for equality
726 * @return true if the specified object is equal to this one
728 public boolean equals(Object obj
)
730 // NOTE: No special hashCode() method is required for this class,
731 // as this equals() implementation is functionally equivalent to
732 // super.equals(), which does define a proper hashCode().
734 if (! (obj
instanceof Rectangle2D
))
736 Rectangle2D r
= (Rectangle2D
) obj
;
737 return r
.getX() == x
&& r
.getY() == y
738 && r
.getWidth() == width
&& r
.getHeight() == height
;
742 * Returns a string representation of this rectangle. This is in the form
743 * <code>getClass().getName() + "[x=" + x + ",y=" + y + ",width=" + width
744 * + ",height=" + height + ']'</code>.
746 * @return a string representation of this rectangle
748 public String
toString()
750 return getClass().getName() + "[x=" + x
+ ",y=" + y
+ ",width=" + width
751 + ",height=" + height
+ ']';