Jalaj P. Jha Technical & Miscellaneous Ramblings

Windows API functions for Rectangle

Rectangle is a shape that you see the most when working in Windows. The Windows you see are all shaped as rectangle, the controls placed in the forms are contained within a rectagle. Hence it's no wonder for Windows to have a number of API functions related to Rectangle.

The structure of Rectangle is defined as

Type RECT
    Left As Long
    Top As Long
    Right As Long
    Bottom As Long
End Type

Once defined an object of type RECT can be created as

Dim objRect As RECT

An object of type RECT can be initialised as an empty rectangle using the function SetRectEmpty. The function takes pointer to a RECT structure and returns Zero if function succeeds otherwise returns a non-zero number.

Declare Function SetRectEmpty Lib "user32" (lpRect As RECT) As Long

SetRectEmpty objRect

The coordinates can be set using the SetRect function which takes for input the poiner to the RECT structure and the co-ordinates Left, Top, Right and Bottom. If the function succeeds the return value is non-zero otherwise zero.

Declare Function SetRect Lib "user32" (lpRect As RECT, ByVal X1 As Long, _
    ByVal Y1 As Long, ByVal X2 As Long, ByVal Y2 As Long) As Long

SetRect objRect, 100, 100, 600, 400

The co-ordinates can also be set using codes as below, but the above function is more preferable as it replaces four assignment statements.

objRect.Left = 100
objRect.Top = 100
objRect.Right = 600
objRect.Bottom = 400

To determine if a rectangle is empty or not IsRectEmpty can be used which takes pointer to a RECT structure. If the rectangle is empty the return value is Zero otherwise non-zero.

Declare Function IsRectEmpty Lib "user32" (lpRect As RECT) As Long

lRectStatus = IsRectEmpty(objRect)

OffsetRect function can be used to move a rectangle to specified horizontal and/or vertical offsets. The function takes for input the pointer to RECT Structure, the horizontal and the vertical offsets. Return value is non-zero if function succeeds otherwise zero.

Declare Function OffsetRect Lib "user32" (lpRect As RECT, ByVal x As Long, ByVal y As Long) As Long

OffsetRect objRect, 100, 100

InflateRect function increases or decreases the size of a rectangle. It takes for input the pointer to RECT structure, the increment in horizontal direction and increment in vertical direction. Return value is non-zero if the function succeeds and zero if it fails. The increments if given as negative values decrease the size of rectangle.

Declare Function InflateRect Lib "user32" (lpRect As RECT, ByVal x As Long, ByVal y As Long) As Long

InflateRect objRect, 100, 100

A point to note here is that the increase or decrease to the size of rectangle actually caused is double the values given as the parameter as the operation done by the function is similar to assignments below

objRect.Left = objRect.Left - x
objRect.Right = objRect.Right + x
objRect.Top = objRect.Top - y
objRect.Bottom = objRect.Bottom + y

Windows also have API functions that perform operations on two RECT structures.

CopyRect function copies the co-ordinates of one rectangle to another. It takes for input pointer to the destination RECT and the pointer to source RECT. The return value is non-zero if function succeeds and zero if it fails.

Declare Function CopyRect Lib "user32" (lpDestRect As RECT, lpSourceRect As RECT) As Long

Dim objRect1 As RECT
Dim objRect2 As RECT

CopyRect objRect1, objRect2

EqualRect function can be used to check if the two rectangles are equal or not. It takes for input pointer to the two RECT structures. The return value is non-zero if function succeeds and zero if it fails.

Declare Function EqualRect Lib "user32" (lpRect1 As RECT, lpRect2 As RECT) As Long

lRetval = EqualRect(objRect1, objRect2)

The Union operation can be performed on two rectangles using UnionRect function to form a third rectangle which contains both the source rectangles. It takes for input the destination rectangle and the two source rectangles. If the destination rectangle so formed is an empty rectangle then the return value is zero otherwise non-zero.

Declare Function UnionRect Lib "user32" (lpDestRect As RECT, lpSrc1Rect As RECT, lpSrc2Rect As RECT) As Long

Dim objDestRect As RECT

Dim objSrcRect1 As RECT
Dim objSrcRect2 As RECT

UnionRect objDestRect, objSrcRect1, objSrcRect2

IntersectRect function takes for input the destination rectangle and two source rectangles. The destination rectangle on execution of function contains a rectangle which is common to both the source rectangles. If the destination rectangle is empty the return value is non-zero otherwise zero.

Declare Function IntersectRect Lib "user32" (lpDestRect As RECT, lpSrc1Rect As RECT, lpSrc2Rect As RECT) As Long

IntersectRect objDestRect, objSrcRect1, objSrcRect2

SubtractRect function forms the destination rectangle by subtracting the second rectangle from the first one. If the function succeeds the return value is non-zero otherwise zero. The destination rectangle is equal to the first rectangle if the second rectangle does not completely overlap the first one in either x or y direction.

Declare Function SubtractRect Lib "user32" (lpDestRect As RECT, lpSrc1Rect As RECT, lpSrc2Rect As RECT) As Long

SubtractRect objDestRect, objSrcRect1, objSrcRect2

Another related structure is the POINT structure, which is the x and y co-ordinates of a given point. It is defined as under

Type POINTAPI
    x As Long
    y As Long
End Type

No we haven't moved from our original topic! there is a API function PtInRect which checks if a specified point lies on the rectangle or not. It takes for input the pointer to a RECT structure and a pointer to a POINTAPI structure and return non-zero if the point lies in the given rectangle otherwise a zero.

Declare Function PtInRect Lib "user32" (lpRect As RECT, pt As POINTAPI) As Long

Dim objRect as RECT
Dim objPoint as POINTAPI

SetRect objRect, 100, 100, 600, 400
objPoint.x = 200
objPoint.y = 200

If PtInRect(objRect, objPoint) = 0 Then
    MsgBox "Point lies outside the rectangle"
Else
    MsgBox "Point is within the rectangle"
End If

That's all with the functions that manipulates a RECT structure.