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
AbsRectType Struct
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
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
RectangleType Struct
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
Rectangle Functions and Macros
AbsToRect Macro
Purpose
Converts an AbsRectType
to a RectangleType
structure.
Declared In
CmnRectTypes.h
Prototype
#define AbsToRect (a
,r
)
Parameters
Returns
See Also
RctCopyRectangle Macro
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
See Also
RctGetIntersection Function
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
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
Purpose
Moves 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 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 negativeinsetAmt
creates a larger rectangle that surrounds the old rectangle.
Returns
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 Macro
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
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
RctPtInRectangle Function
Purpose
Determines if a point lies within a rectangle's boundaries.
Declared In
Rect.h
Prototype
Boolean RctPtInRectangle ( Coordx
, Coordy
, const RectangleType*rP
)
Parameters
Returns
true
if the point (x
, y
) lies within the boundaries of rectangle r
, false
otherwise.
RctSetRectangle Macro
Purpose
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
See Also
RectToAbs Macro
Purpose
Converts a RectangleType
to an AbsRectType
structure.
Declared In
CmnRectTypes.h
Prototype
#define RectToAbs (r
,a
)