Function GraPathBegin() | Xbase++

Begins definition of a graphic path.

GraPathBegin( [<oPS>] ) --> lSuccess

<oPS>

The argument <oPS> specifies the presentation space in which the graphic path is initialized. 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().

The return value of GraPathBegin() is .T. (true) if the path was initialized, otherwise it is .F. (false). If the return value is .F., the cause of error can be determined with GraError().

The function GraPathBegin() initializes a graphic path. A path is formed with graphic primitives like GraLine(), GraArc(), GraSpline() or GraStringAt() and must be closed with the function GraPathEnd(). The graphic primitives executed between GraPathBegin() and GraPathEnd() define the border for a path which can be formed in a variety of ways. During the path definition no output occurs. The defined path is made visible using the functions GraPathFill() and GraPathOutline() after calling the function GraPathEnd().

A graphic path is always used when complex structured areas are outlined or filled. An example of such a complex area is a character string whose letters are filled with a pattern. A graphic path can consist of any number of enclosed areas (each letter in a string is an area, all the letters form the graphic path which is filled or outlined). If characters are used in the definition of a graphics path, they must be provided by a vector font because bitmap fonts do not use graphic primitives to display characters.

The functions GraPathBegin() and GraPathEnd() cannot be nested. After a call to GraPathBegin(), a call to GraPathEnd() must occur so that graphic primitives can again be used for normal drawing rather than being interpreted as part of a path definition. The graphic path is made visible using a path operation such as GraPathFill() or GraPathOutline(). For each presentation space, only a single graphic path is supported, which is discarded as soon as a path operation like "Fill" or "Outline" is executed.

In order to use a path definition more than once, the path must be defined within a graphic segment. By calling GraSegDraw(), the path is recreated and a path operation can again be executed.

Graphic paths are also used for defining a clipping path. A clipping path limits the output of graphic primitives to a specifically defined area (see GraPathClip()).

Drawing with graphic paths


// In the example, a font is created which is used for the 
// definition of a graphic path. A path is then filled with 
// a pattern and a second path is outlined. 

#include "Gra.ch" 
#include "Xbp.ch" 

PROCEDURE Main 
   LOCAL oFont, aAttr 
                                    // create font 
   #ifdef __OS2__ 
      oFont := XbpFont():new():create( "36.Helv.normal" ) 
   #else 
      oFont := XbpFont():new():create( "36.Arial.normal" ) 
   #endif 

   GraSetFont(,oFont)               // install font 

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

   aAttr := Array( GRA_AA_COUNT )   // determine fill pattern 
   aAttr [ GRA_AA_SYMBOL ] := GRA_SYM_DIAG2 
   GraSetAttrArea( NIL, aAttr ) 

   GraPathBegin()                   // open first path 
   GraStringAt( NIL, { 50,150 }, "Graphic path filled" ) 
   GraPathEnd()                     // close first path 
   GraPathFill()                    // fill path 

   GraPathBegin()                   // open second path 
   GraStringAt( NIL, { 10, 50 }, "Graphic path outlined" ) 
   GraPathEnd()                     // close second path 
   GraPathOutline()                 // outline path 

   Inkey(0)                         // wait for key press 

RETURN

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.

Function GraPathBegin() Foundation