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