Function SetClipRect() Foundation

Sets or retrieves the clipping area in a text mode window.

SetClipRect( [<aRectangle>] ) --> aOldRectangle
<aRectangle> := { <nTop>, <nLeft>, <nBottom>, <nRight> }
The optional argument <aRectangle> is an array with four numeric elements. They indicate the screen coordinates of the rectangle that defines the clipping area on the screen.

The function returns an array with four elements. These are the current coordinates of the clipping area before the function is called.


If an application is designed for text mode, output can be limited to an area on the screen that is defined by the coordinates specified with <aRectangle>. The origin of the coordinate system is then set to the coordinates <nTop> and <nLeft>. Also, the maximum number of rows and columns usable for screen output is limited by the coordinates <nBottom> and <nRight>. The clipping area must be activated by calling EnableClipRect( .T. ). After this, screen output outside the clipping area is no longer possible. This applies to all functions and commands used for text mode screen output, for example, functions like QOut() and Achoice() or commands like @..SAY and @...BOX.

The functions SetClipRect() and EnableClipRect() are used together with the VCrt class to program text mode window and menu systems that can be executed in full screen mode as well as in a XbpCrt window.

Clipping of screen output in text mode

// This example demonstrates the effect of an activated clipping 
// rectangle. Two screen outputs are displayed at identical 
// coordinates. Due to SetClipRect(), the second output is shifted 
// 5 rows down and 5 columns to the left. 

   LOCAL aRect := { 5, 5, MaxRow()-5, MaxCol()-5 } 

   @ 4, 3 SAY "Output without SetClipRect()" 
   @ 5, 3 SAY "MaxRow() ="+PadL( MaxRow(), 3 ) 
   @ 6, 3 SAY "MaxCol() ="+PadL( MaxCol(), 3 ) 

   SetClipRect( aRect ) 
   EnableClipRect( .T. ) 

   @ 4, 3 SAY "Output with SetClipRect()" 
   @ 5, 3 SAY "MaxRow() ="+PadL( MaxRow(), 3 ) 
   @ 6, 3 SAY "MaxCol() ="+PadL( MaxCol(), 3 ) 


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.