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

#define INCL_GRE_LINES
#include <os2.h>

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.