net.rim.device.api.ui
Class XYRect

java.lang.Object
  |
  +--net.rim.device.api.ui.XYRect

public final class XYRect

extends Object

Represents a two dimensional rectangle.

Typically these objects are used to represent a drawing extent. It's handy to remember that the top left corner of the rectangle is considered the origin point, and that the size of the rectangle is determine by a width of pixels to the right, and a height of pixels below the point of origin.

This means, therefore, that if you use two XYPoint objects to construct a rectangle, the second point (assumed to be below and to the right of the first), the second point is actually used to measure the number of pixels (height and width) from the origin. This places the second point one pixel outside the bottom right corner of the rectangle.

Warning! It is possible, but certainly not adviseable to create a rectangle with a negative width, negative height, or both.

Note that it is also possible to create an empty rectangle: one with a height or zero, width of zero, or both. This is permissible, and sometimes useful.

Field Summary

int	height
int	width
int	x
int	y

Constructor Summary

XYRect()
Constructs a rectangle object, but does not initialize it.

XYRect(int x, int y, int width, int height)
Constructs a specified rectangle.

XYRect(XYPoint topLeft, XYPoint bottomRight)
Constructs a rectangle from two points.

XYRect(XYRect rect)
Constructs a copy of a rectangle.

Method Summary

boolean	contains(int x, int y, int width, int height) Determines if this rectangle entirely contains specified coordinates.
boolean	contains(XYPoint point) Determines if this rectangle contains specified point.
boolean	contains(XYRect rect) Determines if this rectangle entirely contains another rectangle.
void	intersect(XYRect rect) Intersects this rectangle with another rectangle.
void	set(int x, int y, int width, int height) Set this rectangle to have a new extent.
void	set(XYRect rect) Set this rectangle to have the same extent as another rectangle.
void	setLocation(int x, int y) Move this rectangle to new location in the plane.
void	setLocation(XYPoint topLeft) Move this rectangle to new location based on provided point.
void	setSize(int width, int height) Resize this rectangle.
void	translate(int horizontal, int vertical) Translate this rectangle to new location in plane.
void	translate(XYPoint point) Translate this rectangle to new location in plane using a point as a reference.
void	union(int ox, int oy, int owidth, int oheight) Unite this rectangle with specified coordinates.
void	union(XYRect rect) Unite this rectangle with another rectangle.
int	X2() Retrieves position of rectangle's right edge within the plane.
int	Y2() Retrieves position of rectangle's bottom edge within the plane.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

x

public int x

y

public int y

width

public int width

height

public int height

Constructor Detail

XYRect

public XYRect()

Constructs a rectangle object, but does not initialize it.

XYRect

public XYRect(XYPoint topLeft,
              XYPoint bottomRight)

Constructs a rectangle from two points.

Use this constructor to build a rectangle from to XYPoint objects.

Warning! You must ensure that the bottomRight actually describes a point that is below and to the right of the first, topLeft parameter. It is possible, but not adviseable to create a rectangle with a negative height or width. bottomRight point that is on the same horizontal axis and/or same vertical axis as the topLeft point: in this case, the create rectangle is simply empty.

Parameters:

topLeft - Point marking origin of rectangle (top left corner).

bottomRight - Point describing height and width of rectangle.

XYRect

public XYRect(XYRect rect)

Constructs a copy of a rectangle.

Provide an existing rectangle to this contructor to build a new rectangle of identical size.

Parameters:

rect - Rectangle to copy.

XYRect

public XYRect(int x,
              int y,
              int width,
              int height)

Constructs a specified rectangle.

Pass a point of origin, width, and height to build a rectangle within the plane.

Parameters:

x - Horizontal location of rectangle's origin.

y - Vertical location of rectangle's origin.

width - Distance in pixels to the right edge of the rectangle.

height - Distance in pixels to the bottom edge of the rectangle.

Method Detail

intersect

public void intersect(XYRect rect)

Intersects this rectangle with another rectangle.

Invoke this method to change the extent of this rectangle to pixels shared in common with another rectangle you provide.

If the regions are disjoint this method produces a zero-width and zero-height region. This method then sets the origin to a point (within the original rectangle) closest to the other rectangle.

Parameters:

rect - Rectangle to intersect with this one.

Since:

JDE 3.6

union

public void union(int ox,
                  int oy,
                  int owidth,
                  int oheight)

Unite this rectangle with specified coordinates.

Invoke this method to change the extent of this rectangle to unite it with coordinates you provide (origin and width and height of a new, virtual rectangle).

Parameters:

ox - Left edge of the new area to unite with this rectangle.

oy - Top edge of the new area to unite with this rectangle.

owidth - Distance in pixels to the right edge of the new area.

oheight - Distance in pixels to the bottom edge of the new area.

Since:

JDE 3.6

union

public void union(XYRect rect)

Unite this rectangle with another rectangle.

Invoke this method to change the extent of this rectangle to unite it with another rectangle you provide.

Parameters:

rect - Rectangle to unite with this rectangle.

Since:

JDE 3.6

set

public void set(XYRect rect)

Set this rectangle to have the same extent as another rectangle.

Parameters:

rect - Rectangle representing the new coordinates for this rectangle.

Since:

JDE 3.6

set

public void set(int x,
                int y,
                int width,
                int height)

Set this rectangle to have a new extent.

Parameters:

x - New left edge for this rectangle.

y - New top edge for this rectangle.

width - New distance (in pixels) to right edge of this rectangle.

height - New distance (in pixels) to bottom edge of this rectangle.

Since:

JDE 3.6

setLocation

public void setLocation(int x,
                        int y)

Move this rectangle to new location in the plane.

Parameters:

x - New left edge for this rectangle.

y - New top edge for this rectangle.

Since:

JDE 3.6

setLocation

public void setLocation(XYPoint topLeft)

Move this rectangle to new location based on provided point.

Parameters:

topLeft - Point describing new left edge and new top edge for this rectangle.

Since:

JDE 3.6

setSize

public void setSize(int width,
                    int height)

Resize this rectangle.

Parameters:

width - New distance (in pixels) from left to right edge of this rectangle.

height - New distance (in pixels) from top to bottom edge of this rectangle.

Since:

JDE 3.6

translate

public void translate(int horizontal,
                      int vertical)

Translate this rectangle to new location in plane.

Invoke this method to move this rectangle within the plane by specifying a horizontal and vertical distance.

Parameters:

horizontal - Number of pixels to move this rectangle's left edge along the horizontal axis.

vertical - Number of pixels to move this rectangle's top edge along the vertical axis.

Since:

JDE 3.6

translate

public void translate(XYPoint point)

Translate this rectangle to new location in plane using a point as a reference.

Parameters:

point - Horizontal position of parameter point used as distance to move this rectangle's left edge along the horizontal axis; the vertical position of parameter point used as distance to move this rectangle's top edge along the vertical axis.

Since:

JDE 3.6

contains

public boolean contains(int x,
                        int y,
                        int width,
                        int height)

Determines if this rectangle entirely contains specified coordinates.

Invoke this method to determine if this rectangle entirely contains a virtual retangle described by your parameters.

Parameters:

x - Left edge of the virtual rectangle.

y - Top edge of the virtual rectangle.

width - Distance in pixels to right edge of virtual rectangle.

height - Distance in pixels to bottom edge of virtual rectangle.

Returns:

True if this rectangle entirely contains the virtual rectangle described by your parameters; otherwise, false.

Since:

JDE 3.6

contains

public boolean contains(XYPoint point)

Determines if this rectangle contains specified point.

Parameters:

point - Point that may be contained within this rectangle.

Returns:

True if this rectangle contains your provided point; otherwise, false.

Since:

JDE 3.6

contains

public final boolean contains(XYRect rect)

Determines if this rectangle entirely contains another rectangle.

Parameters:

rect - Rectangle that may be contained within this rectangle.

Returns:

True if this rectangle entirely contains your provided rectangle; otherwise, false.

Since:

JDE 3.6

X2

public final int X2()

Retrieves position of rectangle's right edge within the plane.

Returns:

Position along horizontal axis of right edge of this rectangle.

Y2

public final int Y2()

Retrieves position of rectangle's bottom edge within the plane.

Returns:

Position along vertical axis of bottom edge of this rectangle.