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, but does not initialize it.
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
 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.
 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.
 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
getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

height

public int height
Height of rect.

width

public int width
Width of rect.

x

public int x
Horizontal position of top left point.

y

public int y
Vertical position of top left point.
Constructor Detail

XYRect

public XYRect()
Constructs a new XYRect instance, but does not initialize it.

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.

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. 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.
Method Detail

add

public void add(XYEdges edges)
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:
JDE 4.2.0

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:
JDE 4.0.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(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.
Since:
JDE 4.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:
JDE 4.0.0

reset

public void reset()
Resets all fields to 0.
Since:
JDE 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:
JDE 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.



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.