GpiDrawChain
This function draws the segments that are in the segment chain.
Syntax
GpiDrawChain(hps)
Parameters
- hps (HPS) - input
- Presentation-space handle.
Return Value
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion
- FALSE
- Error occurred.
Remarks
The segments drawn are all of the retained segments that have the ATTR_CHAINED segment attribute (see GpiSetInitialSegmentAttrs), together with all of the unchained segments that are called from them.
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 last one drawn (and no dynamic segments had to be drawn), attributes and other parameters are in the correct state to continue drawing in any drawing mode.
Dynamic segments are not drawn if they are found while processing the segment chain. However, depending on the setting of DCTL_DYNAMIC (see GpiSetDrawControl), they may be removed before, and drawn after, the operation.
It may be necessary to ensure that attributes, model transform, current position, and viewing limits are reset to their default values, before processing the chain. This can be done by ensuring that the first segment to be drawn does not have the ATTR_FASTCHAIN attribute (see GpiSetInitialSegmentAttrs), or by issuing GpiResetPS before the GpiDrawChain. 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.
Example Code
#define INCL_GPISEGMENTS /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ BOOL rc; /* Success indicator. */ rc = GpiDrawChain(hps);
This function uses GpiDrawChain to draw the two chained segments.
#define INCL_GPISEGMENTS /* Segment functions */ #include <os2.h> BOOL fSuccess; /* success indicator */ HPS hps; /* presentation-space handle */ /* The chaining attribute is switched on */ GpiSetInitialSegmentAttrs(hps, ATTR_CHAINED, ATTR_ON); /* two chained segments are defined */ GpiOpenSegment(hps, 1L); . . GpiCloseSegment(hps); GpiOpenSegment(hps, 2L); . . GpiCloseSegment(hps); /* draw the segment chain */ fSuccess = GpiDrawChain(hps);