Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

49    Rectangles

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 ^TOP^

PointType Struct ^TOP^

Purpose

The PointType structure defines a point within a window or on the screen.

Prototype

typedef struct PointType {
Coord x;
Coord y;
} PointType;

Fields

X
Horizontal coordinate.
Y
Vertical coordinate.

RectangleType Struct ^TOP^

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 ^TOP^

RctCopyRectangle Function ^TOP^

Purpose

Copy the source rectangle to the destination rectangle.

Declared In

Rect.h

Prototype

void RctCopyRectangle(
   constRectangleType*srcRectP,
   RectangleType*dstRectP
)

Parameters

srcRectP
A pointer to the rectangle to be copied.
dstRectP
A pointer to the destination rectangle.

See Also

RctSetRectangle()

RctGetIntersection Function ^TOP^

Purpose

Determine the intersection of two rectangles.

Declared In

Rect.h

Prototype

void RctGetIntersection (
   constRectangleType*r1P,
   constRectangleType*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 Function ^TOP^

Purpose

Move all of the boundaries of a rectangle by a specified offset.

Declared In

Rect.h

Prototype

void RctInsetRectangle (
   RectangleType*rP,
   CoordinsetAmt
)

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 Function ^TOP^

Purpose

Move the top and left boundaries of a rectangle by the specified values.

Declared In

Rect.h

Prototype

void RctOffsetRectangle (
   RectangleType*rP,
   CoorddeltaX,
   CoorddeltaY
)

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 Function ^TOP^

Purpose

Determine if a point lies within a rectangle's boundaries.

Declared In

Rect.h

Prototype

Boolean RctPtInRectangle (
   Coordx,
   Coordy,
   constRectangleType*rP
)

Parameters

x
The x coordinate of the point.
y
The y coordinate of the point.
rP
The rectangle.

Returns

Returns true if the point (x, y) lies within the boundaries of rectangle r, false otherwise.

RctSetRectangle Function ^TOP^

Purpose

Sets a rectangle's values.

Declared In

Rect.h

Prototype

void RctSetRectangle (
   RectangleType*rP,
   Coordleft,
   Coordtop,
   Coordwidth,
   Coordheight
)

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()