GpiSetBackColor

Set background colours

Syntax

GpiSetBackColor(hps, lColor)

Parameters

hps (HPS) - input

Presentation-space handle.

lColor (LONG) - input

Background color.

It can be either an index value, if the color table is in index mode, or an RGB value, if the color table is in RGB mode; for a loadable color table, values 0 through n correspond to the color index (or RGB) values.

Constants:

CLR_FALSE - All color planes are zeros.

CLR_TRUE - All color planes are ones.

CLR_DEFAULT - Set to default value; this is the natural background color for the device; for a display, it is the default window color (SYSCLR_WINDOW: see "WinSetSysColors" in the Presentation Manager Programming Reference); for a printer, it is the paper color; the default can be changed by setting new system colors from the control panel for the display, or by selecting a paper color for a printer (if allowed by the device driver), or set explicitly with GpiSetDefAttrs.

CLR_WHITE - White (default color table, or index=RGB loaded color table); for a loaded, realized, color table, it is the nearest available color to white.

CLR_BLACK - Black (default color table, or index=RGB loaded color table); for a loaded, realized, color table, it is the nearest available color to black.

CLR_BACKGROUND - Reset color, used by GpiErase; this is the natural background color for the device; for a display, it is the default window color (SYSCLR_WINDOW: see "WinSetSysColors" in the Presentation Manager Programming Reference); see WinSetSysColors) for the default color table; for a printer, it is the paper color; for a loaded color table, it is color index 0; for an RGB color table, it is color 000000 (black).

CLR_BLUE - Blue (default color table).

CLR_RED - Red (default color table).

CLR_PINK - Pink (default color table).

CLR_GREEN - Green (default color table).

CLR_CYAN - Cyan (default color table).

CLR_YELLOW - Yellow (default color table).

CLR_NEUTRAL - Neutral (default color table); a device-dependent color, that for the default color table provides a contrasting color to CLR_BACKGROUND; for a display, it is the default window text color (SYSCLR_WINDOWTEXT: see "WinSetSysColors" in the Presentation Manager Programming Reference); for a printer, it is a color that contrasts with the paper color; for a loaded color table, it is color index 7; in RGB mode it is interpreted as color 000007.

CLR_DARKGRAY - Dark gray (default color table).

CLR_DARKBLUE - Dark blue (default color table).

CLR_DARKRED - Dark red (default color table).

CLR_DARKPINK - Dark pink (default color table).

CLR_DARKGREEN - Dark green (default color table).

CLR_DARKCYAN - Dark cyan (default color table).

CLR_BROWN - Brown (default color table).

CLR_PALEGRAY - Pale gray (default color table); for a loadable color table, values 0 through n correspond to the color index (or RGB) values.

Returns

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_BACKGROUND_COL_ATTR (0x2044): An invalid background color attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask.

Remarks

Note that if the background mix is BM_LEAVEALONE (the default setting), the background color is not seen.

An attempt to set a negative color value, other than one for which a constant is defined, causes the error PMERR_INV_COLOR_ATTR to be logged. Other color values are allowed, although an error is generated when the color value is needed for drawing if it is invalid for the color table in use at that time (see GpiCreateLogColorTable).

For details of how colors are handled on monochrome devices, also see GpiCreateLogColorTable.

The attribute mode determines whether the current value of the background color attribute is preserved. If it is, the values of the background color attribute, for each primitive type, are preserved, and a single GpiPop function restores them.

This function must not be used within a path or area bracket.

Graphic Elements and Orders

Element Type: OCODE_GSBICOL; This element type is generated if the attribute mode (see GpiSetAttrMode) is set to AM_NOPRESERVE.; Order: Set Background Indexed Color

Element Type: OCODE_GPSBICOL; This element type is generated if the attribute mode is set to AM_PRESERVE.; Order: Push and Set Background Indexed Color

Example Code

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

HPS     hps;     /*  Presentation-space handle. */
LONG    lColor;  /*  Background color. */
BOOL    rc;      /*  Success indicator. */

rc = GpiSetBackColor(hps, lColor);

This is an example of a function used to repaint the window when a WM_PAINT message is issued.

 

#define INCL_GPIPRIMITIVES
#include <OS2.H>

void ClientPaint( HWND hwnd )
{
  POINTL  pt;
  HPS     hps;                      /* Presentation space handle */
  RECTL   rcl;                      /* Window rectangle          */
  long    clrText;

  /* Obtain a cache PS and set color
     and background mix attributes   */
  hps = WinBeginPaint( hwnd, (HPS)NULLHANDLE, (PRECTL)&rcl );
  GpiSetColor( hps, clrText );
  GpiSetBackColor( hps, CLR_BACKGROUND ); /* set background
                                                to white.        */
  GpiSetBackMix( hps, BM_OVERPAINT );
}

Related Functions