< Home < Developers < Development Support < Documentation

## 45 Rectangles

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 45 Rectangles Rectangle Data Structures PointType RectangleType Rectangle Functions RctCopyRectangle RctGetIntersection RctInsetRectangle RctOffsetRectangle RctPtInRectangle RctSetRectangle |  |  |  | This chapter provides reference material for the rectangles API, declared in the header file Rect.h. It is divided into the following sections: Rectangle Data Structures Rectangle Functions ## Rectangle Data Structures ## PointType The PointType structure defines a point within a window or on the screen.
    typedef struct PointType {
      Coord x;
      Coord y;
    } PointType;
#### Field Descriptions #####
x | Horizontal coordinate.
--- | ---
y | Vertical coordinate.
## RectangleType The RectangleType structure defines a rectangular portion of a window or of the screen.
    typedef struct RectangleType {
      PointType  topLeft;
      PointType  extent;
    } RectangleType;
    typedef RectangleType *RectanglePtr;
#### Field Descriptions #####
topLeft | Coordinates of the upper-left corner of the rectangle relative to the window or screen in which the rectangle resides.
--- | ---
extent | Width (extent.x) and height (extent.y) of the rectangle.
## Rectangle Functions ## RctCopyRectangle #### Purpose Copy the source rectangle to the destination rectangle. #### Prototype void RctCopyRectangle (const RectangleType* srcRectP, RectangleType* dstRectP) #### Parameters #####
srcRectP | A pointer to the rectangle to be copied.
#####
dstRectP | A pointer to the destination rectangle.
#### See Also RctSetRectangle ## RctGetIntersection #### Purpose Determine the intersection of two rectangles. #### Prototype void RctGetIntersection (const RectangleType* r1P, const RectangleType* r2P, RectangleType* r3P) #### Parameters #####
r1P | A pointer to a source rectangle.
#####
r2P | A pointer to the other source rectangle.
#####
r3P | Upon return, points to a rectangle representing the intersection of r1 and r2.
#### Comments The rectangle type RectangleType, which is pointed to by RectanglePtr, stores the coordinates for the top-left corner of the rectangle plus the rectangle's width and height. This function returns in the r3 parameter a pointer to the rectangle that represents the intersection of the first two rectangles. If the rectangles r1 and r2 do not intersect, r3 contains a rectangle whose top-left coordinate is the maximum of r1 and r2's top-left coordinates and whose extent varies based on the location of the two rectangles. #### Compatibility On releases prior to Palm OS® 3.5, if rectangles r1 and r2 don't intersect, r3 contains a rectangle that begins at coordinates (0,0 and has 0 width and 0 height. On Palm OS 3.5 and later, if the two rectangles don't intersect then r3 contains a rectangle in which one or both of the extent coordinates is zero. ## RctInsetRectangle #### Purpose Move all of the boundaries of a rectangle by a specified offset. #### Prototype void RctInsetRectangle (RectangleType* rP, Coord insetAmt) #### Parameters #####
rP | A pointer to the rectangle.
#####
insetAmt | Number of pixels to move the boundaries. This can be a negative number.
#### Comments The rectangle type RectangleType, which is pointed to by RectanglePtr, stores the coordinates for the top-left corner of the rectangle plus the rectangle's width and height. This function adds insetAmt to the x and y values of the top-left coordinate and then adjusts the width and the height accordingly so that all of the sides of the rectangle are contracted or expanded by the same amount. A positive insetAmt creates a smaller rectangle that is contained inside the old rectangle's boundaries. A negative insetAmt creates a larger rectangle that surrounds the old rectangle. #### See Also RctOffsetRectangle ## RctOffsetRectangle #### Purpose Move the top and left boundaries of a rectangle by the specified values. #### Prototype void RctOffsetRectangle (RectangleType* rP, Coord deltaX, Coord deltaY) #### Parameters #####
rP | A pointer to the rectangle.
#####
deltaX | Number of pixels to move the left boundary. This can be a negative number.
#####
deltaY | Number of pixels to move the top boundary. This can be a negative number.
#### Comments The rectangle type RectangleType, which is pointed to by RectanglePtr, stores the coordinates for the top-left corner of the rectangle plus the rectangle's width and height. This function adds deltaX to the x value of the top-left coordinate and deltaY to the y value. The width and height are unchanged. Thus, this function shifts the position of the rectangle by the deltaX and deltaY amounts. #### See Also RctInsetRectangle ## RctPtInRectangle #### Purpose Determine if a point lies within a rectangle's boundaries. #### Prototype Boolean RctPtInRectangle (Coord x, Coord y, const RectangleType* rP) #### Parameters #####
x | The x coordinate of the point.
#####
y | The y coordinate of the point.
#####
rP | The rectangle.
#### Result Returns true if the point (x, y) lies within the boundaries of rectangle r, false otherwise. ## RctSetRectangle #### Purpose Sets a rectangle's values. #### Prototype void RctSetRectangle (RectangleType* rP, Coord left, Coord top, Coord width, Coord height) #### Parameters #####
rP | A pointer to the rectangle to be set.
#####
left | The x value for the top-left coordinate of the rectangle.
#####
top | The y value for the top-left coordinate of the rectangle.
#####
width | The rectangle's width.
#####
height | The rectangle's height.
#### See Also RctCopyRectangle |