GpiSetColor

Sets the color for all subsequently drawn graphics primitives.

Syntax

GpiSetColor(hps, lColor)

Parameters

hps (HPS) - input

Presentation-space handle.

lColor (LONG) - input

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.

The possible values include:

• • • CLR_FALSE - All color planes are 0s.
    • CLR_TRUE - All color planes are 1s.
    • CLR_DEFAULT - Set to default value. This is a device-dependent color which, for the default color table, provides a contrasting color to CLR_BACKGROUND For a display, it is the default window text color (SYSCR_WINDOWTEXT: see WinSetSysColors in the Presentation Manager Programming Reference). For a printer, it is a color that contrasts with 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. It can also be set explicitly, using 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) for the default color table. For a printer, it is the paper color. For a loaded palette, which overrides a loaded color table, it is the first entry in the palette. 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).

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_COLOR_ATTR (0x2053)

An invalid color attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask.

Remarks

The current values for each primitive type are updated. The attribute mode (see GpiSetAttrMode) determines whether the current values of the individual color attributes are preserved. If so, they are restored by a single GpiPop function.

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 not valid for the color table in use at that time (see GpiCreateLogColorTable).

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

Example Code

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

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

rc = GpiSetColor(hps, lColor);

This example draws a blue line.

 

#define INCL_GPIPRIMITIVES
#include <OS2.H>


HPS     hps;    /* Presentation space handle     */
POINTL ptl1, ptl2;

      GpiSetColor(hps, CLR_BLUE);
      GpiMove( hps, &ptl1 );                /* Move to start point            */
      GpiLine( hps, &ptl2 );                /* Draw new line                  */

Graphic Elements and Orders

Element Type

OCODE_GSICOL

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to AM_NOPRESERVE.

Order: Set Indexed Color

Element Type

OCODE_GPSICOL

This element type is generated if the attribute mode is set to AM_PRESERVE.

Order: Push and Set Indexed Color

Related Functions

• GpiQueryColor
• GpiSetAttrMode
• GpiSetAttrs
• GpiSetBackColor
• GpiSetBackMix
• GpiSetDefAttrs
• GpiSetMix