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

27    Rectangle Reference

User Interface

Exploring Palm OS®

This chapter provides reference material for the rectangles API, declared in the header files Rect.h and CmnRectTypes.h. It is divided into the following sections:

Rectangle Structures and Types
Rectangle Functions and Macros

Rectangle Structures and Types ^TOP^

AbsRectType Struct ^TOP^

Purpose

Defines a rectangle using four points rather than a top-left coordinate and an extent.

Declared In

CmnRectTypes.h

Prototype

typedef struct AbsRectType {
   Coord left;
   Coord top;
   Coord right;
   Coord bottom;
} AbsRectType

Fields

left
x coordinate of the left side of the rectangle.
top
y coordinate of the top of the rectangle.
right
x coordinate of the right side of the rectangle.
bottom
y coordinate of the bottom of the rectangle.

Comments

The new drawing model defines rectangles by defining left, top, right, and bottom points as this structure does. The Window Manager drawing model defines rectangles using the RectangleType structure.

See Also

AbsToRect(), RectToAbs(), FAbsRectType

PointType Struct ^TOP^

Purpose

Defines a point within a window or on the screen.

Declared In

CmnRectTypes.h

Prototype

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

Fields

x
Horizontal coordinate.
y
Vertical coordinate.

RectangleType Struct ^TOP^

Purpose

Defines a rectangular portion of a window or of the screen. A RectanglePtr defines a pointer to a RectangleType structure.

Declared In

CmnRectTypes.h

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.

Comments

The Window Manager uses rectangles of this type to define regions of the screen. The new drawing model defines rectangles by defining left, top, right, and bottom point like the AbsRectType structure.

See Also

AbsToRect(), RectToAbs()

Rectangle Functions and Macros ^TOP^

AbsToRect Macro ^TOP^

Purpose

Converts an AbsRectType to a RectangleType structure.

Declared In

CmnRectTypes.h

Prototype

#define AbsToRect (
   a,
    r
)

Parameters

a
Pointer to an AbsRectType structure.
r
Pointer to a RectangleType structure.

Returns

Nothing.

See Also

RectToAbs()

RctCopyRectangle Macro ^TOP^

Purpose

Copies the source rectangle to the destination rectangle.

Declared In

Rect.h

Prototype

#define RctCopyRectangle (
   s,
    d
)

Parameters

s
A pointer to the RectangleType to be copied.
d
A pointer to the destination RectangleType.

Returns

Nothing.

See Also

RctSetRectangle()

RctGetIntersection Function ^TOP^

Purpose

Determines 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 RectangleType.
r2P
A pointer to the other source rectangle.
r3P
Upon return, points to a rectangle representing the intersection of r1P and r2P.

Returns

Nothing.

Comments

If the rectangles r1P and r2P do not intersect, r3P contains a rectangle whose top-left coordinate is the maximum of r1P and r2P's top-left coordinates and whose extent is 0.

RctInsetRectangle Function ^TOP^

Purpose

Moves 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 a RectangleType.
insetAmt
Number of coordinates to move the boundaries. This can be a negative number.
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.

Returns

Nothing.

Comments

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.

See Also

RctOffsetRectangle()

RctOffsetRectangle Macro ^TOP^

Purpose

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

Declared In

Rect.h

Prototype

#define RctOffsetRectangle (
   rP,
    dx,
    dy
)

Parameters

rP
A pointer to a RectangleType.
dx
Number of coordinates to move the left boundary. This can be a negative number.
dy
Number of coordinates to move the top boundary. This can be a negative number.

Returns

Nothing.

Comments

This macro adds dx to the x value of the top-left coordinate of rP and dy to the y value. The width and height are unchanged. Thus, this function shifts the position of the rectangle by the dx and dy amounts.

See Also

RctInsetRectangle()

RctPtInRectangle Function ^TOP^

Purpose

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

Declared In

Rect.h

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.

Returns

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

RctSetRectangle Macro ^TOP^

Purpose

Sets a rectangle's values.

Declared In

Rect.h

Prototype

#define RctSetRectangle (
   rP,
    l,
    t,
    w,
    h
)

Parameters

rP
A pointer to a RectangleType to be set.
l
The x value for the top-left coordinate of the rectangle.
t
The y value for the top-left coordinate of the rectangle.
w
The rectangle's width.
h
The rectangle's height.

Returns

Nothing.

See Also

RctCopyRectangle()

RectToAbs Macro ^TOP^

Purpose

Converts a RectangleType to an AbsRectType structure.

Declared In

CmnRectTypes.h

Prototype

#define RectToAbs (
   r,
    a
)

Parameters

r
Pointer to a RectangleType structure.
a
Pointer to an AbsRectType structure.

Returns

Nothing.

See Also

AbsToRect()