Function GraSegOpen() Foundation

Begins the definition of a graphic segment.

GraSegOpen( [<oPS>], [<nMode>], [<nSegmentID>] ) --> nSegmentID
The argument <oPS> specifies the presentation space where a graphic segment 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(). A "Micro PS" cannot be used for this function.
The parameter <nMode> specifies one of the two #define constants GRA_SEG_MODIFIABLE or GRA_SEG_NIL. The default value is GRA_SEG_MODIFIABLE, which indicates that a segment can later be changed. If GRA_SEG_NIL is specified, the segment cannot be changed and it is also not registered for the function GraSegFind(). A segment receives the segment ID 0 in the mode GRA_SEG_NIL and can only be displayed when no segment ID is specified to GraSegDraw().
If a graphic segment is opened in the mode GRA_SEG_MODIFIABLE and closed by the GraSegClose() function, it can be re-opened by passing the return value of the initial GraSegOpen() call as third parameter. This is the numeric ID of the segment.

GraSegOpen() returns a numeric value by which the graphic segment is later identified. If the constant GRA_SEG_NIL is used for <nMode>, the return value is always 0.


The function GraSegOpen() begins the definition for a graphic segment. A segment is created using graphic primitives such as GraLine(), GraArc(), GraSpline() or GraStringAt() and must be terminated by the function GraSegClose(). A segment records all graphic primitives which are executed between GraSegOpen() and GraSegClose(). A segment can then be drawn on the screen repeatedly without further calls to the graphic primitives. The drawing of a segment occurs using the function GraSegDraw().

When GraSegOpen() is called, the current attribute settings for graphic primitives are not stored in the new segment. When a segment is to store colors or line attributes, for example, the attributes must be re-defined after the segment is opened.

A graphic segment is similar to a graphic path. But, multiple operations can be performed with a segment while only one can be performed with a path. For many operations, like scaling or rotation, a segment must be identified through its numeric segment ID returned by GraSegOpen().

That is analogous to the opening of a file with FOpen().

The functions GraSegOpen() and GraSegClose() cannot be nested. After GraSegOpen(), a call to the function GraSegClose() must occur so that graphic primitives can again be used for normal drawing without being recorded in a segment. In addition, it is not possible to create graphic segments as part of a graphic path (a call to GraSegOpen() within GraPathBegin() ... GraPathEnd() is illegal).


Within a presentation space many segments can exist with the segment ID 0, each segment ID not equal to zero exists only once. The maximum number of segments for a presentation space is limited to 16378 (16kB).

Display modes for graphic segments

The drawing or output of a graphic segment occurs in a presentation space which represents an abstract drawing surface (see XbpPresSpace()). The presentation space defines the display mode for graphic segments via the method :drawMode(). As an alternative, the display mode can be set by the function GraSegDrawMode() (see GraSegDrawMode()). In the default display mode GRA_DM_DRAWANDRETAIN, a graphic segment is already visible when the function GraSegClose() is called.

Drawing with graphic segments

// The example shows the basic procedures for the 
// generation and display of graphic segments and demonstrates 
// the effect of both display modes GRA_DM_DRAWANDRETAIN and 

   LOCAL nSegmentA , nSegmentB 

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


   nSegmentA := GraSegOpen()        // create & display segment A 
      GraArc( NIL, { 95,215},  52,,,, GRA_FILL ) 
      GraBox( NIL, { 40,160}, {150,270}, GRA_OUTLINE ) 

   WAIT "Segment A is created and displayed" 

   GraSegDrawMode( NIL, GRA_DM_RETAIN ) 

   nSegmentB := GraSegOpen()        // create segment B 
      GraArc( NIL, {390,215}, 130,,,, GRA_OUTLINE ) 
      GraBox( NIL, {300,120}, {480,310}, GRA_FILL ) 

   WAIT "Segment B is created" 

   GraSegDraw( NIL, nSegmentB )     // display segment B 

   WAIT "Segment B is displayed" 
   CLS                              // erase everything 

   WAIT "Both segments will be redisplayed" 

   GraSegDraw( NIL, nSegmentA ) 
   GraSegDraw( NIL, nSegmentB ) 



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.