Function GraPathClip() | Xbase++

Functions and Directives Functions and Directives

Defines graphic path as a clipping path.

GraPathClip( [<oPS>], [<lClip>], [<nClipMode>] ) --> lSuccess

<oPS>

The argument <oPS> specifies the presentation space in which a graphic clipping path is defined. If the current window is an XbpCrt window, <oPS> is optional. If it is NIL, the return value of SetAppWindow():presSpace() is used. In all other cases <oPS> is not optional. It must be created using XbpPresSpace():new() or a "Micro PS" must be requested from an Xbase Part using the method :lockPS(). After graphic output the Micro PS must be released with :unlockPS().

<lClip>

<lClip> is a logical value which must be .T. (true) to activate the clipping mechanism for the last defined path. If <lClip> is .F. (false), the clipping is turned off and output outside the path is again possible.

<nClipMode> specifies the mode for the clipping mechanism. The value accepted in this parameter can contain a region operator combined with a modifier value. The file GRA.CH contains symbolic contants that can be used to specify the clip mode. The respective #define constants must be added together.

The region operator determines how overlapping regions in the path are to be handled. This becomes significant only with complex paths that consist of several mutually overlapping areas.

Constant	Description
GRA_PATH_CLIP_ALTERNATE *)	Use every other polygon
GRA_PATH_CLIP_WINDING	Use every filled region
Default value

In addition to the region operator, one of the following modifier values can be specified. The modifier determines how the path is combined with the clipping region already set for the presentation space.

Constant	Description
GRA_PATH_CLIP_INCL *)	New clip path is intersection of path and current clipping region
GRA_PATH_CLIP_EXCL	New clip path is current clipping region with areas defined in path excluded
GRA_PATH_CLIP_COMBINE	New clip path is the union of current clipping region and the area in the path
Default value

The return value of GraPathClip() is .T. (true) when the path was defined as a clipping path, otherwise it is .F. (false). If the return value is .F., the cause of error can be determined with GraError().

When a clip path is active, output in the applicable presentation space is limited to the area within the clip path. Everything outside the border of the clip path is not visible. As long as the clip path is active, no output is made outside of the path. This applies to all functions which have screen output, like QOut() or Alert(), along with the graphic functions.

The clip path must be deactivated with GraPathClip( [<oPS>], .F.), so that output outside of the clip path is again possible.

Clipping with GraPathClip()

// In the example, a clipping path is created which consists 
// of two concentric circles. The output of character strings 
// occurs within the path. 

PROCEDURE Main 
   LOCAL i, cString 

   SetColor("N/W")                  // fill window with pale gray 
   CLS 

   GraPathBegin()                   // define graphic path 
      GraArc( , {150,200},  50 ) 
      GraArc( , {150,200}, 100 ) 
   GraPathEnd() 

   GraPathClip( , .T.)              // turn on clipping 

   cString := "Xbase++ Clip-Path Test in two concentric circles" 

   FOR i:=1 TO 11                   // display string 
      graStringAt ( NIL, {50, 320-20*i }, cString ) 
   NEXT 

   GraPathClip( , .F.)              // turn off clipping 
   GraArc( , {150,200},  50 )       // outline path 
   GraArc( , {150,200}, 100 ) 

   Inkey(0)                         // wait for key press 
RETURN

Function GraPathClip() Foundation