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 advisable 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 of zero, width of zero, or both. This is permissible, and sometimes useful.

Field Summary
int	height Height of rect.
int	width Width of rect.
int	x Horizontal position of top left point.
int	y Vertical position of top left point.

Constructor Summary

XYRect()
Constructs a new XYRect instance and sets all fields to 0.

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

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

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

Method Summary
int	X2() Retrieves position of rectangle's right edge within the plane.
int	Y2() Retrieves position of rectangle's bottom edge within the plane.
void	add(XYEdges edges) Adds edges to this rectangle.
boolean	contains(int x, int y) Determines if this rectangle entirely contains specified point.
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.
boolean	equals(Object obj) Determines if provided object has the same dimensions as this rectangle.
int	hashCode() Returns the hash code based on XYRect.
void	intersect(XYRect rect) Intersects this rectangle with another rectangle.
boolean	intersects(XYRect rect) Determines if this rectangle intersects another rectangle.
void	reset() Resets all fields to 0.
void	set(int x, int y, int width, int height) Sets this rectangle to have a new extent.
void	set(XYRect rect) Sets this rectangle to have the same extent as another rectangle.
void	setLocation(int x, int y) Moves this rectangle to new location in the plane.
void	setLocation(XYPoint topLeft) Moves this rectangle to new location based on provided point.
void	setSize(int width, int height) Resizes this rectangle.
void	subtract(XYEdges edges) Substracts edges to this rectangle.
void	translate(int horizontal, int vertical) Translates this rectangle to new location in plane.
void	translate(XYPoint point) Translates this rectangle to new location in plane using a point as a reference.
void	union(int ox, int oy, int owidth, int oheight) Unites this rectangle with specified coordinates.
void	union(XYRect rect) Unites this rectangle with another rectangle.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

x

public int x

Horizontal position of top left point.

y

public int y

Vertical position of top left point.

width

public int width

Width of rect.

height

public int height

Height of rect.

Constructor Detail

XYRect

public XYRect()

Constructs a new XYRect instance and sets all fields to 0.

XYRect

public XYRect(XYPoint topLeft,
              XYPoint bottomBound)

Constructs a rectangle from two points.

Use this constructor to build a rectangle from two 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 advisable to create a rectangle with a negative height or width.

However, it certainly is permissable (and sometimes useful) to provide a bottomRight point that is on the same horizontal axis and/or same vertical axis as the topLeft point: in this case, the created rectangle is simply empty.

Parameters:

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

bottomBound - Point one below and one to the right of the bottom right corner of the rectangle (that is, this point describes the height and width of the rectangle relative to the provided top-left point).

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

add

public void add(XYEdges edges)
         throws NullPointerException

Adds edges to this rectangle. The result is this will be larger by expanding each edge by the specified amount.

Throws:

NullPointerException - If null parameter is provided.

Since:

BlackBerry API 4.2.0

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.

contains

public boolean contains(int x,
                        int y)

Determines if this rectangle entirely contains specified point.

Parameters:

x - X-coordinate of point.

y - Y-coordinate of point.

Returns:

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

Since:

BlackBerry API 4.0.0

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.

contains

public 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.

equals

public boolean equals(Object obj)

Determines if provided object has the same dimensions as this rectangle.

Overrides:

equals in class Object

Parameters:

obj - Object to compare to this rectangle.

Returns:

True if provided object is an XYRect and has the same dimensions as this one; otherwise, false.

See Also:

Boolean.hashCode(), Hashtable

Since:

BlackBerry API 4.0.0

hashCode

public int hashCode()

Returns the hash code based on XYRect.

Overrides:

hashCode in class Object

Returns:

hash code for this XYRect

See Also:

Object.equals(java.lang.Object), Hashtable

Since:

BlackBerry API 5.0.0

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.

intersects

public boolean intersects(XYRect rect)

Determines if this rectangle intersects another rectangle.

Since:

BlackBerry API 4.0.0

reset

public void reset()

Resets all fields to 0.

Since:

BlackBerry API 4.6.0

set

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

Sets 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.

set

public void set(XYRect rect)

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

Parameters:

rect - Rectangle representing the new coordinates for this rectangle.

setLocation

public void setLocation(int x,
                        int y)

Moves this rectangle to new location in the plane.

Parameters:

x - New left edge for this rectangle.

y - New top edge for this rectangle.

setLocation

public void setLocation(XYPoint topLeft)

Moves this rectangle to new location based on provided point.

Parameters:

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

setSize

public void setSize(int width,
                    int height)

Resizes 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.

subtract

public void subtract(XYEdges edges)

Substracts edges to this rectangle. The result is this will be smaller by contracting each edge by the specified amount.

Throws:

NullPointerException - If null parameter is provided.

Since:

BlackBerry API 4.2.0

translate

public void translate(int horizontal,
                      int vertical)

Translates 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.

translate

public void translate(XYPoint point)

Translates 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.

union

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

Unites 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.

union

public void union(XYRect rect)

Unites 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.

X2

public 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 int Y2()

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

Returns:

Position along vertical axis of bottom edge of this rectangle.