Function GraSegDraw() | Xbase++

Functions and Directives Functions and Directives

Draws one or more graphic segments.

GraSegDraw( [<oPS>], [<nSegmentID>], ;
            [<aMatrix>], [<nMode>] ) --> lSuccess

<oPS>

The argument <oPS> specifies the presentation space where a graphic segment 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 using XbpPresSpace():new(). A "Micro PS" cannot be used for this function.

The parameter <nSegmentID> must contain a numeric value which identifies the segment drawn. Each graphic segment receives a numeric code as the return value of the function GraSegOpen(). This value is used for <nSegmentID>. If <nSegmentID> equals NIL, all graphic segments are redisplayed.

The parameter <aMatrix> is a three dimensional array which contains a transformation matrix. Graphic transformations are calculated by the functions GraRotate(), GraScale() or GraTranslate(). <aMatrix> is the array passed to one of these functions which holds the result of the transformation.

<nMode>

The following table lists #define constants used for the optional parameter <nMode>:

Constant	Description
GRA_TRANSFORM_REPLACE	Temporarily replaces the existing transformation with <aMatrix>. The transformation is reset before GraSegDraw() returns
GRA_TRANSFORM_ADD	Temporarily adds <aMatrix> to the existing transformation. The transformation is reset before GraSegDraw() returns
GRA_DRAW_BUFFERED	Draws the segment into an off-screen buffer which is then copied to the screen. Using buffered draws helps reducing flicker caused by graphic primitives overwriting each other. If <oPS> is associated with something else than a window device, this constant is ignored.
The default value is GRA_TRANSFORM_REPLACE.

The return value of GraSegDraw() is .T. (true) when the graphic segment or segments were drawn, otherwise it is .F. (false). If the return value equals .F., the cause of error can be determined using GraError().

Graphic segments are made visible with the function GraSegDraw(). The definition of a graphic segment occurs between the function calls GraSegOpen() ad GraSegClose(). A graphic segment is identified by its numeric segment ID which is the return value of GraSegOpen(). The graphic segment records or stores the calls to graphic primitives and can display them repeatedly.

The function GraSegDraw() is a powerful graphic function since it can process a transformation matrix. Using this function, it is possible to display a (complex) graphic segment more than once at different coordinates or in various sizes without further calls to the graphic primitives.

GraSegDraw() can also recreate a graphic path if the path definition occurs between the function calls GraSegOpen() and GraSegClose(). If several operations must be executed using a graphic path, the path should be defined within a segment. After a path operation, a call to GraSegDraw() is enough to recreate the graphic path.

The opposite, however, is not possible. A graphic segment cannot be created or drawn within a graphic path definition.

Drawing a graphic segment

// The example shows the basic procedures for the definition 
// and the repeated display of a graphic segment. 

#include "Gra.ch" 

PROCEDURE Main 
   LOCAL nSegment 

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

   nSegment := GraSegOpen()         // create & display segment 
   GraArc( NIL, { 95,215},  50,,,,    GRA_FILL ) 
   GraBox( NIL, { 40,160}, {150,270}, GRA_OUTLINE ) 
   GraArc( NIL, {390,215}, 130,,,,    GRA_OUTLINE ) 
   GraBox( NIL, {300,120}, {480,310}, GRA_FILL ) 
   GraSegClose() 

   WAIT "Segment is displayed" 

   SetColor("N/R")                  // fill window with red 
   CLS 

   GraSegDraw( NIL, nSegment )      // redraw segment 

   WAIT "Segment is displayed" 

   SetColor("N/G")                  // fill window with green 
   CLS 

   GraSegDraw( NIL, nSegment )      // redraw segment 

   WAIT "Segment is displayed" 

RETURN

Function GraSegDraw() Foundation