WinDrawBorder

This function draws the borders and interior of a rectangle.

Syntax

WinDrawBorder(hps, prcl, cx, cy, clrFore, clrBack, flCmd)

Parameters

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

prcl (PRECTL) - Input: Bounding rectangle for the border.; The rectangle is in device coordinates.; The border is drawn within the rectangle. Along the bottom and left edges of the rectangle, the edges of the border coincide with the rectangle edges. Along the top and right edges of the rectangle, the border is drawn one device unit inside the rectangle edges.; Note:: The value of each field in this structure must be in the range -32 768 through 32 767. The data type WRECT can also be used, if supported by the language.

cx (LONG) - Input: Width of border rectangle vertical sides.; This is the width of the left and right sides in device coordinates.

cy (LONG) - Input: Width of border rectangle horizontal sides.; This is the width of the top and bottom sides in device coordinates.

clrFore (LONG) - Input: Color of edge of border.; Not used if DB_AREAATTRS is specified.

clrBack (LONG) - Input: Color of interior of border.; Not used if DB_AREAATTRS is specified.

flCmd (ULONG) - Input

Flags controlling the way in which the border is drawn.

Some of the DB_* flags are mutually exclusive. Only one of these four can be significant:

DB_PATCOPY (default)

DB_PATINVERT

DB_DESTINVERT

DB_AREAMIXMODE

Possible values are described in the following list:

DB_ROP: A group of flags that specify the mix to be used, for both the border and the interior.

DB_PATCOPY: Use the ROP_PATCOPY raster operation (see `GpiBitBlt` in the Graphics Programming Interface Programming Reference). This is a copy of the pattern to the destination.

DB_PATINVERT: Use the ROP_PATINVERT raster operation (see `GpiBitBlt` in the Graphics Programming Interface Programming Reference). This is an exclusive-OR of the pattern with the destination.

DB_DESTINVERT: Use the ROP_DESTINVERT raster operation (see `GpiBitBlt` in the Graphics Programming Interface Programming Reference). This inverts the destination.

DB_AREAMIXMODE: Map the current area foreground mix attribute into a Bitblt raster operation (see `GpiBitBlt` in the Graphics Programming Interface Programming Reference). The area background mix mode is ignored.

DB_INTERIOR: The area contained within the given rectangle, and not included within the borders (as given by cx and cy), is drawn.

DB_AREAATTRS:

If this is specified:

For any border, the pattern used is the pattern as currently defined in the area attribute.

For any interior, the pattern used is the same as if GpiSetAttrs for the area attributes is made with the background color of the area attribute being passed for the foreground color, and the foreground color of the area attribute being passed as the background color.

If this is not specified (default):

For any border, the pattern used is the same as if GpiSetAttrs for the area attributes is made with a foreground color of clrFore, and a background color of clrBack.

For any interior, the pattern used is the same as if GpiSetAttrs for the area attributes is made with a foreground color of clrBack, and a background color of clrFore.

DB_STANDARD: cx and cy are multiplied by the system SV_CXBORDER and SV_CYBORDER constants to produce the widths of the vertical and horizontal sides of the border.

DB_DLGBORDER: A standard dialog border is drawn, in the active titlebar color if DB_PATCOPY is specified, or the inactive titlebar color if DB_PATINVERT is specified. Other DB_ROP options, and DB_AREAATTRS, are ignored. DB_ROP and DB_AREAATTRS are also ignored for the interior. The interior is drawn in the color specified by clrBack.

Returns

rc (BOOL) - Returns

Success indicator.

TRUE: : Successful completion.
FALSE: : Error occurred.

Remarks

A border is a rectangular frame, normally used around the edge of a window. This function should only be used in draw mode (DM_DRAW), to a screen device context; hps can be either a micro-presentation space or a normal presentation space (see `GpiCreatePS` in the Graphics Programming Interface Programming Reference). DB_DESTINVERT inverts the destination. If DB_AREAMIXMODE is given, the foreground mix mode from the area attribute is mapped into an equivalent ROP_ value (see `GpiBitBlt` in the Graphics Programming Interface Programming Reference). The area background mix mode is ignored. Either or both cx or cy can be zero. If both are zero, the interior is still drawn. If either the x borders overlap or the y borders overlap, the border is drawn as a single rectangle with no interior.

Errors

Possible returns from WinGetLastError:

PMERR_INVALID_FLAG (0x1019): An invalid bit was set for a parameter. Use constants defined by PM for options, and do not set any reserved bits.
PMERR_INV_DRAW_BORDER_OPTION (0x2068): An invalid option parameter was specified with WinDrawBorder.

Example Code

#define INCL_WINWINDOWMGR /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HPS   hps;     /* Presentation-space handle. */
PRECTL prcl;    /* Bounding rectangle for the border. */
LONG  cx;      /* Width of border rectangle vertical sides. */
LONG  cy;      /* Width of border rectangle horizontal sides. */
LONG  clrFore; /* Color of edge of border. */
LONG  clrBack; /* Color of interior of border. */
ULONG flCmd;   /* Flags controlling the way in which the border is drawn. */
BOOL  rc;      /* Success indicator. */

rc = WinDrawBorder(hps, prcl, cx, cy, clrFore,
                   clrBack, flCmd);

This example uses WinDrawBorder to draw the border (width of 5) and interior of a 300x200 rectangle anchored at (0,0), and using the area's current attributes for both the border and interior colors.

#define INCL_WINWINDOWMGR       /* Window Manager Functions     */
#include <os2.h>

HPS   hps;          /* presentation-space handle         */
BOOL    fSuccess;     /* success indicator                 */
RECTL   prclRectangle={0,0,300,200}; /* border rectangle      */
LONG    lVertSideWidth=5; /* Width of border rectangle vertical
                             sides                             */
LONG    lHorizSideWidth=5;/* Width of border rectangle horizontal
                             sides                             */
ULONG   flCmd;        /* draw flags                        */

/* use current area attributes */
flCmd = DB_AREAATTRS;

fSuccess = WinDrawBorder(hps, &prclRectangle, lVertSideWidth,
                          lHorizSideWidth, 0L, 0L, flCmd);

Related Functions