Rectangles
 

 < 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

srcRectPA pointer to the rectangle to be copied.
dstRectPA 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

r1PA pointer to a source rectangle.
r2PA pointer to the other source rectangle.
r3PUpon 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

rPA pointer to the rectangle.
insetAmtNumber 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

rPA pointer to the rectangle.
deltaXNumber of pixels to move the left boundary. This can be a negative number.
deltaYNumber 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

xThe x coordinate of the point.
yThe y coordinate of the point.
rPThe 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

rPA pointer to the rectangle to be set.
leftThe x value for the top-left coordinate of the rectangle.
topThe y value for the top-left coordinate of the rectangle.
widthThe rectangle's width.
heightThe rectangle's height.

See Also

RctCopyRectangle