GpiBox

This function draws a rectangular box with the current position and a specified position at diagonally opposite corners.

Syntax

GpiBox(hps, lControl, pptlPoint, lHRound, lVRound)

Parameters

hps (HPS) - input

Presentation-space handle.

lControl (LONG) - input

Outline and fill control.

Specifies if the interior of the box is to be filled, and if the outline is to be drawn. This parameter can have one of the following values:

• DRO_FILL Fill interior
• DRO_OUTLINE Draw outline
• DRO_OUTLINEFILL Draw outline and fill interior.

pptlPoint (PPOINTL) - input

Corner point.

The coordinates of the corner that is diagonally opposite to the current position.

lHRound (LONG) - input

Corner-rounding control.

Horizontal length of the full axis of the ellipse that is used for rounding at each corner.

lVRound (LONG) - input

Corner-rounding control.

Vertical length of the full axis of the ellipse that is used for rounding at each corner.

Return Code

lHits (LONG) - returns

Correlation and error indicators.

• GPI_OK Successful
• GPI_HITS Correlate hits
• GPI_ERROR Error.

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_BOX_CONTROL (0x2049) An invalid control parameter was specified with GpiBox.
• PMERR_INV_COORDINATE (0x205B) An invalid coordinate value was specified.
• PMERR_INV_BOX_ROUNDING_PARM (0x204A) An invalid corner rounding control parameter was specified with GpiBox.

Remarks

The sides of the box are parallel to the world coordinate x- and y-axes.

The four corners of the box can be rounded with a quarter ellipse. The size of this ellipse is specified by lHRound and lVRound. If lHRound equals lVRound, the corners of the box are rounded with a quarter circle.

If either lHRound or lVRound is zero, no rounding occurs.

If the current position is (x0,y0) and pptlPoint is set to (x1,y1), the box is drawn from (x0,y0) to (x1,y0) to (x1,y1) to (x0,y1) to (x0,y0). The direction of drawing is significant in area winding mode; see GpiBeginArea.

The current position is unchanged by this function.

Either the outline of the box, or its interior, or both, can be drawn.

If this function occurs within an area or path definition, it generates a complete closed figure (DRO_OUTLINE must be specified). It must not occur within any other figure definition.

If correlation is in force, a hit always results if the pick aperture intersects the box boundary. However, if the pick aperture lies wholly within the box, a hit only occurs if the interior is being drawn (DRO_FILL or DRO_OUTLINEFILL).

Graphic Elements and Orders

Element Type

OCODE_GCBOX

Order: Box at Given Position

Example Code

This example calls GpiBox to draw a series of rounded boxes, one inside another.

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

HPS hps; /* presentation space handle */
POINTL ptl = { 100, 100 };
SHORT i;

for (i = 0; i < 5; i++)
    GpiBox(hps, /* handle to a presentation space */
          DRO_OUTLINE, /* draw the box outline */
          &ptl, /* address of the corner */
          i * 10L, /* horizontal corner radius */
          i * 10L); /* vertical corner radius */

Related Functions

• GpiPop
• GpiQueryCurrentPosition
• GpiSetAttrMode
• GpiSetAttrs
• GpiSetBackColor
• GpiSetBackMix
• GpiSetColor
• GpiSetDefAttrs
• GpiSetMix
• GpiSetCurrentPosition
• GpiSetLineJoin
• GpiSetLineType
• GpiSetLineWidth
• GpiSetLineWidthGeom