Functions and Directives

Function GraSpline() Foundation

Draws spline (curve).

Syntax
GraSpline( [<oPS>], <aPoints>, [<lPenPos>] ) --> lSuccess
Parameters
<oPS>
The argument <oPS> specifies the presentation space in which the spline is drawn. 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 either 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().
<aPoints> := { {<nX1>,<nY1>} ,..., {<nXN>,<nYN>} }
<aPoints> is an array whose elements each contain a two element array. Each two element array specifies the coordinates for a point through which the spline is drawn. For each element of <aPoints>, the first element <nX> of its subarray specifies the x coordinate and the second element <nY> specifies the y coordinate. The unit for the coordinates depends on the coordinate system defined for the presentation space. If no presentation space is specified, the values for the coordinates are given in pixels, which is the unit for a window. The origin for the coordinates (the point {0,0}) is at the lower left.
<lPenPos>
If the parameter <lPenPos> has the value .T. (true), the spline begins at the current pen position. This causes the spline to be defined with one more point (the starting point) than specified in <aPoints>. The default value for <lPenPos> is .T. (true).
Return

The return value of GraSpline() is .T. (true) if the spline was drawn, otherwise it is .F. (false). If the return value equals .F., the cause of error can be determined by GraError().

Description

The function GraSpline() draws a curve using a specific algorithm, which is a Bezier spline. This algorithm requires that the number of specified points minus 1 must be divisible by 3 or the spline cannot be drawn. The following code determines whether the array meets this condition for GraSpline():

IF lPenPos 
   lCanDrawSpline := ( Len(aPoints) % 3  == 0 ) 
ELSE 
   lCanDrawSpline := ( ( Len(aPoints)-1 ) % 3  == 0 ) 
ENDIF 

The parameter <lPenPos> specifies whether the current pen position should be used as the origin for the spline. By default a spline begins with the current pen position. If <lPenPos> is not specified or has the value .T. (true), the expression Len(aPoints) must be a multiple of 3. If <lPenPos> is .F. (false) the expression Len(aPoints)-1 must be a multiple of 3.

Examples
Drawing a curve

// In the example a spline is drawn with 13 support points. 
// For comparison these points are identified with markers 
// and connected by lines 

#include "Gra.ch" 

PROCEDURE Main 
   LOCAL aPoints, i 

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

   aPoints := { {  30, 314 }, ;        // support points for spline 
                {  80, 106 }, ; 
                { 130, 110 }, ; 
                { 180, 164 }, ; 
                { 230, 172 }, ; 
                { 280, 257 }, ; 
                { 330, 203 }, ; 
                { 380, 274 }, ; 
                { 430,  58 }, ; 
                { 480, 109 }, ; 
                { 530, 144 }, ; 
                { 580, 250 }, ; 
                { 630, 138 }  ; 
              } 

   graSpline( NIL, aPoints, .F. )      // draw spline 

   GraMarker( NIL, aPoints[1] )        // mark first point 

   FOR i:=2 TO 13                      // mark other points 
      GraLine( , , aPoints[i] )        // and connect with lines 
      GraMarker( , aPoints[i] ) 
   NEXT 

   Inkey(0)                            // wait for key press 

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.