GpiCloseSegment

This function closes the current segment.

Syntax

GpiCloseSegment (hps)

Parameters

hps (HPS) - input

Presentation-space handle.

Returns

rc (BOOL) - returns

Success indicator.

• TRUE - Successful completion
• FALSE - Error occurred.

==Errors?? Possible returns from WinGetLastError

PMERR_INV_HPS (0x207F)

An invalid presentation-space handle was specified.

PMERR_PS_BUSY (0x20F4)

An attempt was made to access the presentation space from more than one thread simultaneously.

PMERR_INV_MICROPS_FUNCTION (0x20A1)

An attempt was made to issue a function that is invalid in a micro presentation space.

PMERR_NOT_IN_SEG (0x20E3)

An attempt was made to end a segment using GpiCloseSegment while not in a segment bracket.

PMERR_PATH_INCOMPLETE (0x20EC)

An attempt was made to open or close a segment either directly or during segment drawing, or to issue GpiAssociate while there is an open path bracket.

PMERR_AREA_INCOMPLETE (0x2005)

One of the following has occurred: o A segment has been opened, closed, or drawn.

• GpiAssociate was issued while an area bracket was open.
• A drawn segment has opened an area bracket and ended without closing it.

Remarks

Closing a segment does not delete the segment or affect the graphics primitives that are drawn.

Any attributes that have been preserved (see the AM_PRESERVE option of GpiSetAttrMode) are popped (restored) when the GpiCloseSegment function is issued in draw or draw-and-retain modes, and at the end of the segment when the segment is subsequently drawn in draw-and-retain or retain modes (see GpiSetDrawingMode).

If an area or path is open when a segment is closed, the area or path is terminated. When the drawing mode is draw or draw-and-retain, a warning is given, but the close processing continues. No warning is given for retain mode. If a retained segment with an open area or path is drawn, an error occurs.

If an element bracket is open when a segment is closed, the element bracket is first closed automatically.

If this function is followed by primitives or attributes, without first opening a segment, the following may or may not have been reset to their default values:

• Current attribute values and arc parameters
• Current tag
• Current model transform
• Current position
• Current clip path and viewing limits.

Any such quantity can be assumed to contain its default value only if it is known either that it has not been changed from the default, or that last time it was changed, it was set to its default value. An application should not be written to depend on the values of these quantities immediately after GpiCloseSegment.

Subsequent primitives, not preceded by an GpiOpenSegment function, are not retained, irrespective of the current drawing mode.

The current viewing transform, however, is guaranteed to be reset to unity for primitives outside segments.

Example Code

Declaration:

#define INCL_GPISEGMENTS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS     hps;  /*  Presentation-space handle. */
BOOL    rc;   /*  Success indicator. */

rc = GpiCloseSegment(hps);

This example uses the GpiCloseSegment function to close a segment. The GpiOpenSegment opens the segment; GpiMove and GpiPolyLine draw a triangle.

#define INCL_GPISEGMENTS        /* Segment functions            */
#include <os2.h>

HPS hps;                /* presentation space handle            */
POINTL ptlStart = { 0, 0 }; /* first vertex                     */
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices  */

GpiOpenSegment(hps, 1L);            /* open the segment          */
GpiMove(hps, &ptlStart);            /* move to start point (0,0) */
GpiPolyLine(hps, 3L, ptlTriangle);  /* draw triangle             */
GpiCloseSegment(hps);               /* close the segment         */

Related Functions

Prerequisite Functions

• GpiOpenSegment

Related Functions

• GpiCallSegmentMatrix
• GpiCorrelateSegment
• GpiDeleteSegment
• GpiDeleteSegments
• GpiDrawSegment
• GpiErrorSegmentData
• GpiQueryInitialSegmentAttrs
• GpiQuerySegmentAttrs
• GpiQuerySegmentNames
• GpiQuerySegmentPriority
• GpiSetInitialSegmentAttrs
• GpiSetSegmentAttrs
• GpiSetSegmentPriority