GpiModifyPath

This function modifies the specified path.

Syntax

GpiModifyPath(hps, lPath, lMode);

Parameters

hps (HPS) - input: Presentation-space handle.

lPath (LONG) - input: Path identifier.

Identifier of the path to be modified; it must be 1.

lMode (LONG) - input: Modification required.

This must be:

MPATH_STROKE: Convert the path to one describing the envelope of a wide line.

Returns

rc (BOOL) - returns: Success indicator.

TRUE - Successful completion
FALSE - Error occurred.

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_PATH_ID (0x20AE): An invalid path identifier parameter was specified.

PMERR_INV_MODIFY_PATH_MODE (0x20A6): An invalid mode parameter was specified with GpiModifyPath.

PMERR_PATH_UNKNOWN (0x20EE): An attempt was made to perform a path function on a path that did not exist.

PMERR_COORDINATE_OVERFLOW (0x2014): An internal coordinate overflow error occurred. This can occur if coordinates or matrix transformation elements (or both) are invalid or too large.

Calling Sequence

This function modifies the specified path.

#define INCL_GPIPATHS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS     hps;    /*  Presentation-space handle. */
LONG    lPath;  /*  Path identifier. */
LONG    lMode;  /*  Modification required. */
BOOL    rc;     /*  Success indicator. */

rc = GpiModifyPath(hps, lPath, lMode);

Example Source Code

This example uses the GpiModifyPath function to modify the given path. The GpiFillPath function then draws the path.

#define INCL_GPIPATHS           /* GPI Path functions           */
#include <os2.h>

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

GpiBeginPath(hps, 1L);                       /* creates path    */
GpiMove(hps, &ptlStart);
GpiPolyLine(hps, 3L, ptlTriangle);
GpiEndPath(hps);

GpiModifyPath(hps,
              1L,
              MPATH_STROKE);     /* modifies path for wide line */
GpiFillPath(hps, 1L, FPATH_ALTERNATE);   /* draws the wide line */

Remarks

This function converts the path to one describing the envelope of a wide line stroked using the current geometric wide-line attribute (see GpiSetLineWidthGeom). Note that this and GpiStrokePath are the only calls that can cause geometric wide lines to be constructed.

The envelope includes the effects of line joins, and line ends, according to the current values of these attributes (see GpiSetLineJoin and GpiSetLineEnd). Note these points:

A line may be joined to an arc, for example. The common point is handled according to the line-join attribute, rather than applying line ends at each end.
Any open figures within the path are not closed automatically.
If a figure is closed using GpiCloseFigure, the joining rules are followed, rather than the ending rules, at the start and end point.
The envelope takes account of any crossings, so that a character such as a stroked "X" does not have a hole in the middle when subsequently drawn in exclusive-OR mode.

After this function, the only calls that can be performed on the path are GpiFillPath, specifying the FPATH_WINDING option, or GpiSetClipPath, specifying the SCP_WINDING option.

Graphic Elements and Orders

Element Type: OCODE_GMPTH

Order: Modify Path

Related Functions

GpiBeginPath
GpiEndPath
GpiFillPath
GpiOutlinePath
GpiPathToRegion
GpiPop
GpiSetAttrMode
GpiSetAttrs
GpiSetBackColor
GpiSetBackMix
GpiSetClipPath
GpiSetColor
GpiSetDefAttrs
GpiSetLineEnd
GpiSetLineJoin
GpiSetLineType
GpiSetLineWidth
GpiSetLineWidthGeom
GpiSetMix
GpiSetPattern
GpiSetPatternRefPoint
GpiSetPatternSet
GpiStrokePath