Programming Guide:xppguide

Graphic paths Foundation

A graphic path is very similar to a graphic segment. It is initiated using the function GraPathBegin() and terminated using GraPathEnd(). Graphic primitives which are called between these two functions describe the graphic path. The graphic path is defined in a manner similar to the definition of a graphic segment but it has an entirely different purpose: it defines the borders of an area.

After a graphic path is defined, the area described by it can be made visible by any one of three path operations. An overview of path operations is presented in the next table:

Functions for graphic paths
Function Description
GraPathBegin() Initiates definition of graphic path
GraPathEnd() Terminates definition of graphic path
GraPathFill() Fills graphic path
GraPathOutline() Outlines graphic path
GraPathClip() Specifies graphic path as a clipping path

Graphic primitives that are called between GraPathBegin() and GraPathEnd() define the outline of an area that forms the graphic path. The primitives are not drawn and remain hidden. The defined area can then be filled with a color and/or pattern using GraPathFill(). The attributes for areas set with GraSetAttrArea() are used. The border of the defined area can be drawn using GraPathOutline() which makes the primitives visible. In this case, the line attributes set with GraSetAttrLine() are used.

After one of the two path operations (GraPathFill() or GraPathOutline()) are executed, the graphic path is discarded and is no longer available. When an area is to be outlined as well as filled, a graphic path can be defined within a graphic segment. The path can then be redefined using GraSegDraw(). Example:

nSegmentID := GraSegOpen()             // open segment 

   GraPathBegin()                      // initiate path 
   /* execute graphic primitives */ 
   GraPathEnd()                        // end path 

GraSegClose()                          // close segment 

GraPathFill()                          // fill area 

GraSegDraw( , nSegmentID )             // redefine path 

GraPathOutline()                       // outline path 

Unlike GraPathOutline(), the path operation GraPathFill() requires that the area described by the path be closed. If this is not the case, the entire window is filled by GraPathFill().

A special path operation is performed using GraPathClip(). Anything drawn in the window is limited to the area defined by the graphic path. Output outside this area is not possible while the clipping path is set. This includes all graphic functions as well as the functions available in hybrid mode, like QOut() and Alert(). The clipping path is activated using GraPathClip(, .T.) and must be deactivated using GraPathClip(, .F.).

Graphic paths

This illustration shows some of the ways in which graphic paths can be used. On the left a clip path is defined by two concentric circles (using the function GraArc()). Within the clip path, a character string is drawn several times using GraStringAt(). The "paper airplane" consists of only seven points. The points are connected to each other using GraLine() and the graphic paths are defined and then outlined and filled with various patterns. Three fill patterns are used to illustrate the separate graphic paths, (the two "wings" are one graphic path). The text "Alaska" is drawn between GraPathBegin() and GraPathEnd() and then filled with a pattern using GraPathFill(). This shows that a graphic path itself can consist of several individually enclosed areas. Each letter forms a separate closed area.


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.