Functions and Directives Functions and Directives

Function SetClipRect() Foundation

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

Syntax
SetClipRect( [<aRectangle>] ) --> aOldRectangle
Parameters
<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.
Return

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

Description

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.

Examples
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. 

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

   CLS 
   @ 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 ) 

RETURN
Feedback

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.