# Using Rect and Point Structures

The userint.h include file defines two structures, Rect and Point. You use these structures to specify locations and areas in Cartesian coordinate systems, such as those in canvas controls, table controls and bitmaps. Many canvas and table control functions use these structures.

The Rect structure specifies the location and size of a rectangle. It is defined as follows:

typedef struct
{

int top;
int left;
int height;
int width;
} Rect;

A Point structure specifies the location of a point. The point can be a pixel, as is the case when programming with canvas controls or bitmaps, or it can be a cell, when programming with table controls. It is defined as follows:

typedef struct
{

int x;
int y;
} Point;

Functions and Macros for Making Rects and Points

You might want to create a Rect or Point only to pass it to a function. You can avoid creating a variable for this operation using one of the following functions:

Rect MakeRect (int top, int left, int height, int width);

Point MakePoint (int x, int y);

MakePoint creates a Point in the following example:

CanvasDrawPoint (panel, ctrl, MakePoint (30, 40));

You can also use these functions to initialize variables, as in the following example:

Rect r = MakeRect (10, 20, 100, 130);

The Rect height and width have special values. Also, some macros exist for creating commonly used rectangles. The documentation for each function indicates when these values and macros are applicable. Refer to the table below.

Values and Macros for Rect Structures

Name | Value or Definition | Description
VAL_TO_EDGE | 1 | Set the Rect width (or height) to the distance from the Rect left (or top) to the right (or bottom) edge of the object.
VAL_KEEP_SAME_SIZE | 2 | When copying objects such as bitmaps, make the destination object the same size as the source object.
VAL_EMPTY_RECT | MakeRect (0, 0, 0, 0) | An empty rectangle.
VAL_ENTIRE_OBJECT | MakeRect (0, 0, VAL_TO_EDGE, VAL_TO_EDGE) | Make the Rect the size of the object, for example, the canvas or bitmap.
VAL_TABLE_ROW_RANGE (r) | MakeRect ((r), 1, 1, VAL_TO_EDGE) | A specific row of table cells.
VAL_TABLE_COLUMN_RANGE (c) | MakeRect (1, (c), 1, VAL_TO_EDGE) | A specific column of table cells.
VAL_TABLE_ENTIRE_RANGE | MakeRect (1, 1, VAL_TO_EDGE, VAL_TO_EDGE) | A range consisting of all the cells in a table.
VAL_TABLE_SINGLE_CELL_RANGE (r, c) | MakeRect ((r), (c), 1, 1) | A range consisting of a single, specific table cell.

Functions for Modifying Rects and Points

You use the following functions to set or modify the values in a Rect or Point structure:

- RectSet sets each of the four values of an existing Rect structure.
- RectSetFromPoints sets a Rect so that it defines the smallest rectangle that encloses two points.
- RectSetBottom sets the height of a Rect so that the bottom is a given value. The bottom is not enclosed by the rectangle.
- RectSetRight sets the height of a Rect so that the right edge is a given value.
  The right edge is not enclosed by the rectangle.
- RectSetCenter sets the top and left of a Rect so that it is centered around a given value, while keeping the same size.
- RectOffset modifies the top and left of a Rect so as to shift the location of the rectangle.
- RectMove sets the top and left of Rect to a given Point.
- RectGrow modifies the values in a Rect so that the rectangle grows or shrinks around its current center point.
- PointSet sets the two values in an existing Point structure.

Functions for Comparing or Obtaining Values from Rects and Points

You use the following functions to compare or obtain values from a Rect or Point structure:

- RectBottom obtains the location of the bottom of a rectangle.
- RectRight obtains the location of the right edge of a rectangle.
- RectCenter obtains the location of the center of a rectangle.
- RectEqual determines if two rectangles are identical.
- RectEmpty determines if a rectangle is empty.
- RectContainsPoint determines if a rectangle encloses a given point.
- RectContainsRect determines if a rectangle completely encloses another rectangle.
- RectSameSize determines if two rectangles are the same size.
- RectUnion sets a Rect to the smallest rectangle that encloses two given rectangles.
- RectIntersection sets a Rect to the largest rectangle that is enclosed by two given rectangles.
- PointEqual determines whether two points are at the same location.
- PointPinnedToRect modifies a Point structure, if necessary, to ensure that it is within a given rectangle.