public class Rectangle extends Object
Rectangle
specifies an area in a coordinate space that is
enclosed by the Rectangle
object's upper-left point
(x,y)
in the coordinate space, its width, and its height.
A Rectangle
object's width
and
height
are public
fields. The constructors
that create a Rectangle
, and the methods that can modify
one, do not prevent setting a negative value for width or height.
A Rectangle
whose width or height is exactly zero has location
along those axes with zero dimension, but is otherwise considered empty.
The isEmpty()
method will return true for such a Rectangle
.
Methods which test if an empty Rectangle
contains or intersects
a point or rectangle will always return false if either dimension is zero.
Methods which combine such a Rectangle
with a point or rectangle
will include the location of the Rectangle
on that axis in the
result as if the #add(Point)
method were being called.
Methods which affect only the location of a Rectangle
will
operate on its location regardless of whether or not it has a negative
or zero dimension along either axis.
Note that a Rectangle
constructed with the default no-argument
constructor will have dimensions of 0x0
and therefore be empty.
That Rectangle
will still have a location of (0,0)
and
will contribute that location to the union and add operations.
Code attempting to accumulate the bounds of a set of points should
therefore initially construct the Rectangle
with a specifically
negative width and height or it should use the first point in the set
to construct the Rectangle
.
For example:
Rectangle bounds = new Rectangle(0, 0, -1, -1); for (int i = 0; i < points.length; i++) { bounds.add(points[i]); }or if we know that the points array contains at least one point:
Rectangle bounds = new Rectangle(points[0]); for (int i = 1; i < points.length; i++) { bounds.add(points[i]); }
This class uses 32-bit integers to store its location and dimensions.
Frequently operations may produce a result that exceeds the range of
a 32-bit integer.
The methods will calculate their results in a way that avoids any
32-bit overflow for intermediate results and then choose the best
representation to store the final results back into the 32-bit fields
which hold the location and dimensions.
The location of the result will be stored into the x
and
y
fields by clipping the true result to the nearest 32-bit value.
The values stored into the width
and height
dimension
fields will be chosen as the 32-bit values that encompass the largest
part of the true result as possible.
Generally this means that the dimension will be clipped independently
to the range of 32-bit integers except that if the location had to be
moved to store it into its pair of 32-bit fields then the dimensions
will be adjusted relative to the "best representation" of the location.
If the true result had a negative dimension and was therefore
non-existant along one or both axes, the stored dimensions will be
negative numbers in those axes.
If the true result had a location that could be represented within
the range of 32-bit integers, but zero dimension along one or both
axes, then the stored dimensions will be zero in those axes.
Modifier and Type | Field and Description |
---|---|
int |
height
The height of the
Rectangle . |
int |
width
The width of the
Rectangle . |
int |
x
The X coordinate of the upper-left corner of the
Rectangle . |
int |
y
The Y coordinate of the upper-left corner of the
Rectangle . |
Constructor and Description |
---|
Rectangle()
Constructs a new
Rectangle whose upper-left corner
is at (0, 0) in the coordinate space, and whose width and
height are both zero. |
Rectangle(BaseBounds b)
Constructs a new
Rectangle , initialized to match
the values of the specified Rectangle . |
Rectangle(int width,
int height)
Constructs a new
Rectangle whose upper-left corner
is at (0, 0) in the coordinate space, and whose width and
height are specified by the arguments of the same name. |
Rectangle(int x,
int y,
int width,
int height)
Constructs a new
Rectangle whose upper-left corner is
specified as
(x,y) and whose width and height
are specified by the arguments of the same name. |
Rectangle(Rectangle r)
Constructs a new
Rectangle , initialized to match
the values of the specified BaseBounds . |
Modifier and Type | Method and Description |
---|---|
void |
add(int newx,
int newy)
Adds a point, specified by the integer arguments
newx,newy
to the bounds of this Rectangle . |
void |
add(Rectangle r)
Adds a
Rectangle to this Rectangle . |
boolean |
contains(int cx,
int cy)
Checks whether or not this
Rectangle contains the
point at the specified location (cx,cy) . |
boolean |
contains(int cx,
int cy,
int cw,
int ch)
Checks whether this
Rectangle entirely contains
the Rectangle
at the specified location (cx,cy) with the
specified dimensions (cw,ch) . |
boolean |
contains(Rectangle r)
Checks whether or not this
Rectangle entirely contains
the specified Rectangle . |
boolean |
equals(Object obj)
Checks whether two rectangles are equal.
|
void |
grow(int h,
int v)
Resizes the
Rectangle both horizontally and vertically. |
int |
hashCode() |
Rectangle |
intersection(Rectangle r) |
void |
intersectWith(Rectangle r) |
boolean |
isEmpty() |
void |
setBounds(BaseBounds b) |
void |
setBounds(int x,
int y,
int width,
int height)
Sets the bounding
Rectangle of this
Rectangle to the specified
x , y , width ,
and height . |
void |
setBounds(Rectangle r)
Sets the bounding
Rectangle of this Rectangle
to match the specified Rectangle . |
RectBounds |
toRectBounds() |
String |
toString()
Returns a
String representing this
Rectangle and its values. |
void |
translate(int dx,
int dy)
Translates this
Rectangle the indicated distance,
to the right along the X coordinate axis, and
downward along the Y coordinate axis. |
public int x
Rectangle
.public int y
Rectangle
.public int width
Rectangle
.public int height
Rectangle
.public Rectangle()
Rectangle
whose upper-left corner
is at (0, 0) in the coordinate space, and whose width and
height are both zero.public Rectangle(BaseBounds b)
Rectangle
, initialized to match
the values of the specified Rectangle
.r
- the Rectangle
from which to copy initial values
to a newly constructed Rectangle
public Rectangle(Rectangle r)
Rectangle
, initialized to match
the values of the specified BaseBounds
. Since BaseBounds has
float values, the Rectangle will be created such that the bounding rectangle
of the specified BaseBounds would always lie within the bounding box
specified by this Rectangle.r
- the BaseBounds
from which to copy initial values
to a newly constructed Rectangle
public Rectangle(int x, int y, int width, int height)
Rectangle
whose upper-left corner is
specified as
(x,y)
and whose width and height
are specified by the arguments of the same name.x
- the specified X coordinatey
- the specified Y coordinatewidth
- the width of the Rectangle
height
- the height of the Rectangle
public Rectangle(int width, int height)
Rectangle
whose upper-left corner
is at (0, 0) in the coordinate space, and whose width and
height are specified by the arguments of the same name.width
- the width of the Rectangle
height
- the height of the Rectangle
public void setBounds(Rectangle r)
Rectangle
of this Rectangle
to match the specified Rectangle
.
This method is included for completeness, to parallel the
setBounds
method of Component
.
r
- the specified Rectangle
#getBounds
,
Component.setBounds(java.awt.Rectangle)
public void setBounds(int x, int y, int width, int height)
Rectangle
of this
Rectangle
to the specified
x
, y
, width
,
and height
.
This method is included for completeness, to parallel the
setBounds
method of Component
.
x
- the new X coordinate for the upper-left
corner of this Rectangle
y
- the new Y coordinate for the upper-left
corner of this Rectangle
width
- the new width for this Rectangle
height
- the new height for this Rectangle
#getBounds
,
Component.setBounds(int, int, int, int)
public void setBounds(BaseBounds b)
public boolean contains(int cx, int cy)
Rectangle
contains the
point at the specified location (cx,cy)
.cx
- the specified X coordinatecy
- the specified Y coordinatetrue
if the point
(cx,cy)
is inside this
Rectangle
;
false
otherwise.public boolean contains(Rectangle r)
Rectangle
entirely contains
the specified Rectangle
.r
- the specified Rectangle
true
if the Rectangle
is contained entirely inside this Rectangle
;
false
otherwisepublic boolean contains(int cx, int cy, int cw, int ch)
Rectangle
entirely contains
the Rectangle
at the specified location (cx,cy)
with the
specified dimensions (cw,ch)
.cx
- the specified X coordinatecy
- the specified Y coordinatecw
- the width of the Rectangle
ch
- the height of the Rectangle
true
if the Rectangle
specified by
(cx, cy, cw, ch)
is entirely enclosed inside this Rectangle
;
false
otherwise.public void intersectWith(Rectangle r)
public void translate(int dx, int dy)
Rectangle
the indicated distance,
to the right along the X coordinate axis, and
downward along the Y coordinate axis.dx
- the distance to move this Rectangle
along the X axisdy
- the distance to move this Rectangle
along the Y axisRectangle.setLocation(int, int)
,
Rectangle.setLocation(java.awt.Point)
public RectBounds toRectBounds()
public void add(int newx, int newy)
newx,newy
to the bounds of this Rectangle
.
If this Rectangle
has any dimension less than zero,
the rules for non-existant
rectangles apply.
In that case, the new bounds of this Rectangle
will
have a location equal to the specified coordinates and
width and height equal to zero.
After adding a point, a call to contains
with the
added point as an argument does not necessarily return
true
. The contains
method does not
return true
for points on the right or bottom
edges of a Rectangle
. Therefore, if the added point
falls on the right or bottom edge of the enlarged
Rectangle
, contains
returns
false
for that point.
If the specified point must be contained within the new
Rectangle
, a 1x1 rectangle should be added instead:
r.add(newx, newy, 1, 1);
newx
- the X coordinate of the new pointnewy
- the Y coordinate of the new pointpublic void add(Rectangle r)
Rectangle
to this Rectangle
.
The resulting Rectangle
is the union of the two
rectangles.
If either Rectangle
has any dimension less than 0, the
result will have the dimensions of the other Rectangle
.
If both Rectangle
s have at least one dimension less
than 0, the result will have at least one dimension less than 0.
If either Rectangle
has one or both dimensions equal
to 0, the result along those axes with 0 dimensions will be
equivalent to the results obtained by adding the corresponding
origin coordinate to the result rectangle along that axis,
similar to the operation of the #add(Point)
method,
but contribute no further dimension beyond that.
If the resulting Rectangle
would have a dimension
too large to be expressed as an int
, the result
will have a dimension of Integer.MAX_VALUE
along
that dimension.
r
- the specified Rectangle
public void grow(int h, int v)
Rectangle
both horizontally and vertically.
This method modifies the Rectangle
so that it is
h
units larger on both the left and right side,
and v
units larger at both the top and bottom.
The new Rectangle
has (x - h, y - v)
as its upper-left corner,
width of (width + 2h)
,
and a height of (height + 2v)
.
If negative values are supplied for h
and
v
, the size of the Rectangle
decreases accordingly.
The grow
method will check for integer overflow
and underflow, but does not check whether the resulting
values of width
and height
grow
from negative to non-negative or shrink from non-negative
to negative.
h
- the horizontal expansionv
- the vertical expansionpublic boolean isEmpty()
public boolean equals(Object obj)
The result is true
if and only if the argument is not
null
and is a Rectangle
object that has the
same upper-left corner, width, and height as
this Rectangle
.
Copyright © 2020. All rights reserved.