GpiPolyLine: Difference between revisions

Latest revision as of 02:16, 24 November 2025

This function draws a series of straight lines starting at the current position and connecting the points specified.

Syntax

GpiPolyLine(hps, lCount, aptlPoints)

Parameters

hps (HPS) - input: Presentation-space handle.
lCount (LONG) - input: Number of points.; Must not be negative. Zero is valid but causes no output.
aptlPoints (PPOINTL) - input: Array of points.

Return Value

lHits (LONG) - returns

Correlation and error indicators.

GPI_OK: Successful

GPI_HITS: Correlate hits

GPI_ERROR: Error.

Remarks

On completion, current position is set to the last point. The maximum number of lines allowed in a polyline is device dependent, but is always greater than 3 500 for GPIF_LONG format spaces and always greater than 7 200 for GPIF_SHORT format spaces (see the PS_FORMAT of GpiCreatePS for the meaning of this format).

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_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.
PMERR_INV_COORDINATE (0x205B): An invalid coordinate value was specified.
PMERR_INV_NESTED_FIGURES (0x20A8): Nested figures have been detected within a path definition.

Graphic Elements and Orders

Element Type: OCODE_GCLINE

Note that GpiLine also generates this element type.

Order: Line at Current Position

As many of these orders are generated as is necessary to hold the specified points.

Example Code

This example uses the GpiPolyLine function to draw a triangle.

#define INCL_GPIPRIMITIVES /* GPI primitive functions */
#include <os2.h>

HPS hps; /* presentation space handle*/
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices */

GpiMove(hps, &ptlTriangle[2]); /* moves to end point (0, 0)*/
GpiPolyLine(hps, 3L, ptlTriangle); /* draws triangle */

Related Functions

@@ Line 5: / Line 5: @@
 ==Parameters==
-; hps ([[HPS]]) - input
+; hps ([[HPS]]) - input: Presentation-space handle.
-: Presentation-space handle.
+; lCount ([[LONG]]) - input: Number of points.
-; lCount ([[LONG]]) - input
-: Number of points.
 : Must not be negative. Zero is valid but causes no output.
+; aptlPoints ([[PPOINTL]]) - input: Array of points.
-; aptlPoints ([[PPOINTL]]) - input
-: Array of points.
 ==Return Value==
-; lHits ([[LONG]]) - returns
+; lHits ([[LONG]]) - returns: Correlation and error indicators.
-: Correlation and error indicators.
+::GPI_OK: Successful
-:; GPI_OK
+::GPI_HITS: Correlate hits
-:: Successful
+::GPI_ERROR: Error.
-:; GPI_HITS
-:: Correlate hits
-:; GPI_ERROR
-:: Error.
 ==Remarks==
@@ Line 31: / Line 22: @@
 ==Errors==
 Possible returns from WinGetLastError:
-; PMERR_INV_HPS (0x207F)
+; PMERR_INV_HPS (0x207F): An invalid presentation-space handle was specified.
-: 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_PS_BUSY (0x20F4)
+; PMERR_INV_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.
-: An attempt was made to access the presentation space from more than one thread simultaneously.
+; PMERR_INV_COORDINATE (0x205B): An invalid coordinate value was specified.
-; PMERR_INV_LENGTH_OR_COUNT (0x2092)
+; PMERR_INV_NESTED_FIGURES (0x20A8): Nested figures have been detected within a path definition.
-: An invalid length or count parameter was specified.
-; PMERR_INV_COORDINATE (0x205B)
-: An invalid coordinate value was specified.
-; PMERR_INV_NESTED_FIGURES (0x20A8)
-: Nested figures have been detected within a path definition.
 ==Graphic Elements and Orders==
-Element Type: OCODE_GCLINE
+;Element Type: OCODE_GCLINE
 Note that [[GpiLine]] also generates this element type.
 Order: Line at Current Position
 As many of these orders are generated as is necessary to hold the specified points.
 ==Example Code==
-<PRE>
-#define INCL_GPIPRIMITIVES /* Or use INCL_GPI, INCL_PM, Also in COMMON section */
-#include &lt;os2.h&gt;
-HPS     hps;          /* Presentation-space handle. */
-LONG    lCount;       /* Number of points. */
-PPOINTL aptlPoints;   /* Array of points. */
-LONG    lHits;        /* Correlation and error indicators. */
-lHits = GpiPolyLine(hps, lCount, aptlPoints);
-</PRE>
 This example uses the GpiPolyLine function to draw a triangle.
 <pre>
 #define INCL_GPIPRIMITIVES /* GPI primitive functions */
-#include &lt;os2.h&gt;
+#include <os2.h>
 HPS hps; /* presentation space handle*/