Function GraSegOpen() | Xbase++

Begins the definition of a graphic segment.

GraSegOpen( [<oPS>], [<nMode>], [<nSegmentID>] ) --> nSegmentID

<oPS>

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.

<nMode>

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).

Limitations

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 
// GRA_DM_RETAIN. 

PROCEDURE Main 
   LOCAL nSegmentA , nSegmentB 

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

   GraSegDrawMode( NIL, GRA_DM_DRAWANDRETAIN ) 

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

   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 ) 
   GraSegClose() 

   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 ) 

   Inkey(0) 

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 GraSegOpen() Foundation