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.