GpiSetViewingLimits

This function establishes a clipping rectangle in model space.

Syntax

GpiSetViewingLimits(hps, prclLimits)

Parameters

hps (HPS) - input

Presentation-space handle.

prclLimits (PRECTL) - input

Viewing limits in model space.

Return Code

rc (BOOL) - returns

Success indicator.

• TRUE Successful completion
• FALSE Error occurred.

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_COORDINATE (0x205B)

An invalid coordinate value was specified.

Remarks

Viewing limits can be set within a segment, and apply to all subsequent primitives in the segment and any segments it calls. They can be changed at any time within the segment and they are not subject to segment or model transformations. Limits specified in called segments override those set by the limits of the root segment.

The limits are reset to their default value at the start of each root segment, subject to the fast-chaining attribute, like primitive attributes. The initial default value is no clipping; this can be changed with GpiSetDefViewingLimits.

The boundaries are inclusive, so that points on them are not clipped (removed). If either the left boundary of prclLimits is greater than the right, or the bottom greater than the top, a NULL rectangle is defined. All points are clipped.

Attribute mode (see GpiSetAttrMode) has no effect on this function.

The viewing limits are converted under the current viewing and default viewing transformations to a clipping rectangle in the page. This remains in force until changed by a subsequent GpiSetViewingLimits function. Clipping actually takes place to the intersection of the viewing limits, the clip path, the clip region, the graphics field, and the client area on the device.

Graphic Elements and Orders

Element Type: OCODE_GSVW

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to AM_NOPRESERVE. Order: Set Viewing Window

Element Type: OCODE_GPSVW

This element type is generated if the attribute mode is set to AM_PRESERVE. Order: Push and Set Viewing Window

Example Code

In this example the model space clipping region width is reduced to 400x400.

#define INCL_GPITRANSFORMS
#include <OS2.H>

HPS hps;      /* Presentation-space */
              /* handle. */

BOOL fSuccess;
RECTL rclLimits = { /* viewing limits. */
                    10,10,
                    410,410
                   };

fSuccess = GpiSetViewingLimits(hps, &rclLimits);

Related Functions

• GpiQueryViewingLimits
• GpiSetDefViewingLimits
• GpiSetGraphicsField