GpiDrawSegment
This function draws the specified segment.
Syntax
GpiDrawSegment(hps, lSegment)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- lSegment (LONG) - input
- Segment to be drawn; it must be greater than 0.
Return Value
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion
- FALSE
- Error occurred.
Remarks
The drawing operation is controlled by the calls set by the draw controls (see GpiSetDrawControl), except for the correlate control. If there is not a segment open at the time of the draw, and this function is followed by primitives or attributes, without first opening a segment, the processing is as described for GpiCloseSegment.
If a segment is already open at the time of the draw, GpiCloseSegment processing is not performed at the completion of the draw (except that any unclosed path or area is abandoned with an error). In this instance, if the open segment is the segment specified in lSegment, and no dynamic segments had to be drawn, then attributes and other parameters are in the correct state to continue drawing in any drawing mode.
Depending on the setting of DCTL_DYNAMIC (see GpiSetDrawControl), all of the dynamic segments in the chain may be removed before, and drawn after, the specified segment is drawn. (Note that if the specified segment is itself dynamic, it is only drawn in this way.) This function differs from the other GpiDraw... calls, in that the segment to be drawn need not be a chained segment.
It may be necessary to ensure that attributes, model transform, current position, and viewing limits are reset to their default values, before processing the segment. This can be done either by ensuring that the segment does not have the ATTR_FASTCHAIN attribute (see GpiSetInitialSegmentAttrs), or by issuing GpiResetPS before the GpiDrawSegment. The latter method also resets the clip path to no clipping, which may also be necessary.
It is an error to issue this function while any of these brackets are open:
- Area bracket
- Path bracket
- Element bracket.
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_SEG_NOT_FOUND (0x2100)
- The specified segment identifier did not exist.
- PMERR_INV_SEG_NAME (0x20C8)
- An invalid segment identifier was specified.
Example Code
#define INCL_GPISEGMENTS /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ LONG lSegment; /* Segment to be drawn; it must be greater than 0. */ BOOL rc; /* Success indicator. */ rc = GpiDrawSegment(hps, lSegment);
This example uses the GpiDrawSegment function to draw segment 4.
#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, 4L); /* open the segment */
GpiMove(hps, &ptlStart); /* move to start point (0, 0) */
GpiPolyLine(hps, 3L, ptlTriangle); /* draw triangle */
GpiCloseSegment(hps); /* close the segment */
.
.
.
GpiDrawSegment(hps, 4L); /* draw segment #4 */