GpiSetClipPath

This function selects a path as the current clip path.

Syntax

GpiSetClipPath(hps, lPath, lOptions);

Parameters

hps (HPS) - input

Presentation-space handle.

lPath (LONG) - input

Path control flag.

0 The current clip path stops being the current clip path; the current clip path is to be reset to an infinite one (that is, no clipping).

1 The path that has been defined is to be intersected with the current clip path.

lOptions (LONG) - input

Options.

This contains fields of option bits. For each field, one value should be selected (unless the default is suitable). These values can then be ORed together to generate the parameter.

How to construct the path interior (see also GpiBeginArea):

SCP_ALTERNATE Constructs interior in alternate mode (the default).

SCP_WINDING Constructs interior in winding mode. This value must be selected if the path has been modified using GpiModifyPath.

Relationship to current clip path:

SCP_AND Intersects the specified path with the current clip path. This must be specified if lPath is 1.

SCP_RESET Resets the clip path to an infinite clip path (the default). This must be specified or defaulted if lPath is 0.

Include or exclude path:

SCP_INCL Includes this path in the clip path (the default).

SCP_EXCL Excludes this path in the clip path.

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_CLIP_PATH_OPTIONS (0x2051)

An invalid options parameter was specified with GpiSetClipPath.

PMERR_PATH_UNKNOWN (0x20EE)

An attempt was made to perform a path function on a path that did not exist.

Calling Sequence

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

HPS     hps;       /*  Presentation-space handle. */
LONG    lPath;     /*  Path control flag. */
LONG    lOptions;  /*  Options. */
BOOL    rc;        /*  Success indicator. */

rc = GpiSetClipPath(hps, lPath, lOptions);

Example Source Code

This function selects a path as the current clip path.

#define INCL_GPIPATHS
#include <OS2.H>


HPS     hps;    /* Presentation space handle     */



GpiSetClipPath(hps,
               0L,    /* The current clip path    */
                      /* stops being the          */
                      /* current clip path; the   */
                      /* current clip path is to  */
                      /* be reset to an infinite  */
                      /* one (that is, no         */
                      /* clipping)                */
               SCP_ALTERNATE);
                      /* Construct interior in    */
                      /* alternate mode.          */

Remarks

The clip path (bound in device coordinates when the path is defined) is used for all subsequent drawing.

Any open figures within the path are closed automatically.

The boundaries of the area defined by the path are considered to be part of the interior, so that a point on the boundary is not clipped.

The clip path is reset to no clipping (no path selected) at the start of a root segment (subject to the fast chaining segment attribute), or when a GpiResetPS function is issued.

After a path is selected as the clip path, it cannot be reused for any other purpose. When it is superseded as the clip path, it is discarded.

Graphic Elements and Orders

Element Type: OCODE_GSCPTH

Order: Set Clip Path

Related Functions

• GpiBeginPath
• GpiEndPath
• GpiExcludeClipRectangle
• GpiFillPath
• GpiIntersectClipRectangle
• GpiModifyPath
• GpiOffsetClipRegion
• GpiOutlinePath
• GpiPathToRegion
• GpiStrokePath
• GpiQueryClipBox
• GpiQueryClipRegion
• GpiSetClipPath
• GpiSetClipRegion