GrePolyLine

GrePolyLine draws a sequence of one or more lines starting at the current (X,Y) position. As each line is drawn, its end point becomes the start point for the next line. Upon completion, the current (X,Y) position is the end point of the last line.

For performance reasons, all presentation drivers should support this function when drawing a polyline to a single clipping rectangle. When the clip region is more complex, the handling routine can forward the call to the graphics engine using the pointer supplied in the dispatch table when the presentation driver was enabled. The engine will clip each line and return it to the presentation driver as a call to GreDrawLinesInPath.

GrePolyLine is called by the function GpiPolyLine. GrePolyLine is also used by many of the complex object-rendering routines within the graphics engine.


 * Simulation support: None. This function is mandatory for all drivers.

Syntax
GrePolyLine(hdc, paptlPoint, cPoints, pInstance, lFunction);

Parameters

 * hdc (HDC) - input :Device context handle.


 * paptlPoint (PPOINTL) - input :Pointer to an array of (X,Y) points.


 * Pointer to an array of cPoints (X,Y) pairs containing the (X,Y) coordinates of the end points for the lines.


 * cPoints (LONG) - input : Number of (X,Y) pairs in points array.
 * When this is passed as 0, the handling routine takes no action except to return Successful.


 * pInstance (PVOID) - input : Pointer to instance data.


 * lFunction (ULONG) - input : High-order WORD=flags; low-order WORD=NGrePolyLine.

Returns

 * rc (LONG) - returns : Return Code.

On completion, the handling routine must return an integer (cHits) indicating, where appropriate, whether correlation hits were detected:


 * GPI_OK: Successful
 * GPI_HITS: Successful with correlate hit (returned by display drivers when the correlate flag is on, and a hit is detected)
 * GPI_ERROR: Error

Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:


 * PMERR_BASE_ERROR
 * PMERR_BITMAP_NOT_SELECTED
 * PMERR_COORDINATE_OVERFLOW
 * PMERR_DEV_FUNC_NOT_INSTALLED
 * PMERR_HDC_BUSY
 * PMERR_INV_COLOR_DATA
 * PMERR_INV_COLOR_INDEX
 * PMERR_INV_COORD_SPACE
 * PMERR_INV_HDC
 * PMERR_INV_IN_AREA
 * PMERR_INV_IN_PATH
 * PMERR_INV_LENGTH_OR_COUNT
 * PMERR_INV_PICK_APERTURE_POSN
 * PMERR_INV_RECT
 * PMERR_PATH_LIMIT_EXCEEDED
 * PMERR_PATH_UNKNOWN

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Sample

 * 1) define INCL_GRE_LINES
 * 2) include 

HDC       hdc;         /*  Device context handle. */ PPOINTL   paptlPoint;  /*  Pointer to an array of (X,Y) points. */ LONG      cPoints;     /*  Number of (X,Y) pairs in points array. */ PVOID     pInstance;   /*  Pointer to instance data. */ ULONG     lFunction;   /*  High-order WORD=flags; low-order WORD=NGrePolyLine. */ LONG      rc;          /*  Return Code. */

rc = GrePolyLine(hdc, paptlPoint, cPoints, pInstance, lFunction);

Remarks
When COM_TRANSFORM is not set, the function expects the array of points to be in screen coordinates.

When the COM_AREA or COM_PATH flag is set, this function is part of an area or path definition. In either case, the handling routine would usually pass the call back to the graphics engine for processing by the default handling routine. The call would not be passed back to the graphics engine if the presentation driver had hooked all of the area and path functions.

When this function is used to draw a closed figure, the handling routine must not draw the last point of the last (closure) line. The handling routine can call back to the graphics engine to do any necessary clipping.