How to Set and Restore a Clipping Region in QuickBASIC (44134)

SUMMARY

This article explains how to use the SetClip toolbox library (MBLC) routine to establish a clipping region in Microsoft QuickBASIC Version 1.00 for the Apple Macintosh.

To use SetClip, you pass to it a handle of a region that already exists. SetClip copies the given region. It does not use the actual region you pass to it. The clipping region and the copied region are two different resources. This means that any changes you make to the copied region do not affect the clipping region.

Using the DisposeRgn library routine on the copied region does not reset the clipping region. Once the clip region is set, its definition remains constant until it is redefined with another CALL to SetClip. If you want to restore graphics output to the whole window, you must reset the clipping region to include the entire window region. An example of how to do this is shown below.

MORE INFORMATION

Before you can create a clip region, you must create the region from which to copy. To create a region, do the following:

Create a region with the NewRgn routine.
Access the region with OpenRgn.
After it has been opened, define the region with any graphics routine that creates a closed figure (circle, square, oval, etc.).
Close the region.

It is at this point that you pass the handle of the new region to SetClip. After you are finished with the region, use DisposeRgn to discard it.

SetClip is discussed on Pages 166-167 of "Inside Macintosh" Volume I, (by Apple Computer, Inc., published by Addison-Wesley, 1985). Clipping regions are discussed in the "Microsoft QuickBASIC For Apple Macintosh: Language Reference" on Pages 429-430.

Code Example

ScreenWidth% = SYSTEM(5)
ScreenHeight% = SYSTEM(6)
centerX% = ScreenWidth% / 2
centerY% = ScreenHeight% / 2
x1% = CenterX% - 40 : x2% = CenterX% + 40
y1% = CenterY% - 40 : y2% = CenterY% + 40

' Set a small, square clip region
CALL SetClipRegion(x1%, y1%, x2%, y2%)

'Draw lines to show the boundaries of the clip region
'Lines are drawn only within the clip region
FOR n = 1 TO 100
  LINE (1, n * 4)-(ScreenWidth%, n * 4)
NEXT n

' Restore the clip region to the entire window
CALL SetClipRegion(1, 1, ScreenWidth%, ScreenHeight%)

' Draw Circles to show the current clip region
FOR i = 1 TO 30
  CIRCLE (50, 50), i * 5
NEXT i

LOCATE 10, 1
INPUT "HIT RETURN TO EXIT THE PROGRAM", A$
END

SUB SetClipRegion(x1%, y1%, x2%, y2%) STATIC
     R& = 0 : SetRect c%(0), x1%, y1%, x2%, y2%
     NewRgn R& : OpenRgn
     FRAMERECT VARPTR(c%(0))
     CloseRgn R&
     SetClip R&
     DisposeRgn R&
END SUB