Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPISEGMENTS
 
BOOL GpiOpenSegment(hps, idSegment)
HPS hps;           /* presentation-space handle */
LONG idSegment;    /* segment identifier        */
 
The GpiOpenSegment function opens the segment specified by the idSegment
parameter. The function creates a new segment if a segment having the
specified identifier does not already exist. Otherwise, it opens the
segment. Once a segment is opened or created, the system stores an element
in the segment for each subsequent primitive and attribute function, up to
the next call to the GpiCloseSegment function. If the segment previously
existed, the system either replaces the old elements with the new or inserts
the new elements, depending on the segment editing mode.
 
The function can create a segment when the drawing mode is set to either
DM_RETAIN or DM_DRAWANDRETAIN but can open an existing segment only when the
drawing mode is DM_RETAIN. (The GpiOpenSegment function can also create a
segment when the drawing mode is DM_DRAW, but subsequent elements are not
stored.)
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
idSegment  Specifies the segment identifier. The segment identifier must be
           a positive integer. If the identifier is unique──that is, has not
           been used before with the presentation space──the function
           creates a new segment. Zero is reserved for unnamed segments.
 
Return Value
 
The return value is GPI_OK if the function is successful or GPI_ERROR if an
error occurred.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_ALREADY_IN_SRG
     PMERR_AREA_INCOMPLETE
     PMERR_DYNAMIC_SEG_ZERO_INV
     PMERR_IMAGE_INCOMPLETE
     PMERR_INV_HPS
     PMERR_INV_MICROPS_FUNCTION
     PMERR_INV_MODE_FOR_OPEN_DYN
     PMERR_INV_MODE_FOR_REOPEN_SEG
     PMERR_INV_SEG_NAME
     PMERR_PATH_INCOMPLETE
     PMERR_PS_BUSY
     PMERR_UNCHAINED_SEG_ZERO_INV
 
Comments
 
If the segment identifier is zero, the function creates an unnamed segment.
An unnamed segment is like any other segment except it cannot be referenced
by identifiers in subsequent segment functions. For example, an unnamed
segment cannot be drawn directly since the GpiDrawSegment function requires
a segment identifier, but the unnamed segment can be drawn if it is added to
the picture chain. GpiOpenSegment creates a new unnamed segment for each
call specifying the zero identifier. Any number of unnamed segments can be
created, and the unnamed segments continue to exist until all segments are
deleted.
 
The GpiOpenSegment function assigns segment attributes to each new segment.
The initial segment attributes are set by the GpiSetInitialSegmentAttrs
function. If the initial attributes specify a dynamic segment, the segment
can be created only in DM_RETAIN drawing mode.
 
Only one segment per presentation space can be open at a time.
 
Example
 
This example uses the GpiOpenSegment to create a new segment. The segment is
subsequently drawn by using the GpiDrawSegment function.
 
POINTL ptlStart = { 0, 0 };
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };
 
GpiOpenSegment(hps, 1L);            /* opens the segment             */
GpiMove(hps, &ptlStart);            /* moves to starting point (0,0) */
GpiPolyLine(hps, 3L, ptlTriangle);  /* draws triangle                */
GpiCloseSegment(hps);               /* closes the segment            */
 
GpiDrawSegment(hps, 1L);
 
See Also
 
GpiCloseSegment, GpiErrorSegmentData, GpiSetInitialSegmentAttrs,
GpiSetSegmentAttrs, GpiSetViewingTransformMatrix, WinGetLastError
 
                                      ♦