GrePolyShortLine

GrePolyShortLine draws a series of shortlines. The current (X,Y) position is not changed. A polyshortline is a linked list of shortlines.

This function must be supported by all presentation drivers except those that hook GrePolyLine and all of the GreArcxxx functions that are simulated by handling routines in the graphics engine. All function calls to GrePolyShortLine come from either GrePolyLine or the GreArcxxx functions. GrePolyShortLine might be accessed from any of the curve-rendering functions. However, it is not guaranteed that curve rendering will call GrePolyShortLine.

Simulation support

None. This function is mandatory for all drivers.

Syntax

 GrePolyShortLine(hdc, psl, pInstance, lFunction);

Parameters

hdc (HDC) - input

Device context handle.

psl (PSHORTLINE) - input

Pointer to SHORTLINE structure.

The shortlines are defined in a list of linked SHORTLINE structures:

slh SHORTLINEHEADER structure:

• ulStyle Line style.
• ulFormat Line format.
• ptlStart (X,Y) position of start (the start position is included in the line).
• ptlStop (X,Y) position of end (the end position is not included in the line).
• lxLeft Left edge of bounding rectangle.
• lxRight Right edge of bounding rectangle.
• pslhNext Pointer to next shortline.
• pslhPrev Pointer to previous shortline.

The boundaries of the rectangle are inclusive at the start points of the lines, and exclusive at the stop points regardless of the direction.

This structure is a discrete representation of a curve that starts at point (x0,y0) and ends at point (x1,y1). For each of the (y1-y0+1) rows, there is exactly one X value contained in the X array. The final point in the series is not drawn.

ax Steps. This is an array of X-coordinates in absolute values. There is one coordinate value for each shortline.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGrePolyShortLine.

Return Code

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_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

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

Remarks

The function renders each SHORTLINE structure in the list until a NULL pslhNext is encountered. Coordinates are passed as screen coordinates and are already completely clipped.

Declaration

#define INCL_GRE_LINES
#include <os2.h>

HDC           hdc;        /*  Device context handle. */
PSHORTLINE    psl;        /*  Pointer to SHORTLINE structure. */
PVOID         pInstance;  /*  Pointer to instance data. */
ULONG         lFunction;  /*  High-order WORD=flags; low-order WORD=NGrePolyShortLine. */
LONG          rc;         /*  Return Code. */

rc = GrePolyShortLine(hdc, psl, pInstance, lFunction);