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
PointType Struct
Purpose
The PointType
structure defines a point within a window or on the screen.
Prototype
typedef struct PointType { Coord x; Coord y; } PointType;
Fields
RectangleType Struct
Purpose
The RectangleType
structure defines a rectangular portion of a window or of the screen.
Prototype
typedef struct RectangleType { PointType topLeft; PointType extent; } RectangleType;
typedef RectangleType *RectanglePtr;
Fields
-
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 Function
Purpose
Copy the source rectangle to the destination rectangle.
Declared In
Rect.h
Prototype
void RctCopyRectangle( const RectangleType *srcRectP, RectangleType *dstRectP )
Parameters
See Also
RctGetIntersection Function
Purpose
Determine the intersection of two rectangles.
Declared In
Rect.h
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
andr2
.
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 Function
Purpose
Move all of the boundaries of a rectangle by a specified offset.
Declared In
Rect.h
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 Function
Purpose
Move the top and left boundaries of a rectangle by the specified values.
Declared In
Rect.h
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
RctPtInRectangle Function
Purpose
Determine if a point lies within a rectangle's boundaries.
Declared In
Rect.h
Prototype
Boolean RctPtInRectangle ( Coord x, Coord y, const RectangleType *rP )
Parameters
Returns
Returns true
if the point (x
, y
) lies within the boundaries of rectangle r
, false
otherwise.
RctSetRectangle Function
Purpose
Declared In
Rect.h
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.