GpiDrawFrom
This function draws a section of the segment chain.
Syntax
GpiDrawFrom(hps, lFirstSegment, lLastSegment)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- lFirstSegment (LONG) - input
- First segment to be drawn; it must be greater than 0.
- lLastSegment (LONG) - input
- Last segment to be drawn; it must be greater than 0.
Return Value
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion
- FALSE
- Error occurred.
Remarks
Drawing starts at the segment identified by lFirstSegment and includes all chained segments (those with the ATTR_CHAINED segment attribute, see GpiSetInitialSegmentAttrs), and the segments called from them, up to, and including, the segment identified by lLastSegment. 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 terminated 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. If this happens, then all dynamic segments are involved, whether they occur within the range specified or not.
It may be necessary to ensure that attributes, model transform, current position, and viewing limits are reset to their default values, before processing the segments. This can be done either by ensuring that the first segment to be drawn does not have the ATTR_FASTCHAIN attribute (see GpiSetInitialSegmentAttrs), or by issuing GpiResetPS before the GpiDrawFrom. 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.
If lFirstSegment does not exist, or is not in the segment chain, an error is raised. If the lLastSegment does not exist, or is not in the chain, or is chained before the lFirstSegment, no error is raised, and processing continues to the end of the chain.
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_SEG_NOT_CHAINED (0x20FF)
- An attempt was made to issue GpiDrawFrom, GpiCorrelateFrom or GpiQuerySegmentPriority for a segment that was not chained.
- 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 lFirstSegment; /* First segment to be drawn; it must be greater than 0. */ LONG lLastSegment; /* Last segment to be drawn; it must be greater than 0. */ BOOL rc; /* Success indicator. */ rc = GpiDrawFrom(hps, lFirstSegment, lLastSegment);
This example uses the GpiDrawFrom function to draw all segments in the picture chain between and including the segments 1 and 4.
#define INCL_GPISEGMENTS /* Segment functions */ #include <os2.h> HPS hps; /* presentation space handle */ GpiDrawFrom(hps, 1L, 4L);