SETCOLORTABLE

short Escape(hdc, SETCOLORTABLE, sizeof(COLORTABLE_STRUCT),lpInData,lpColor)

The SETCOLORTABLE printer escape sets an RGB color-table entry. If the device cannot supply the exact color, the function sets the entry to the closest possible approximation of the color.

Parameters

hdc

HDC Identifies the device context.

lpInData

COLORTABLE_STRUCT FAR * Points to a structure that contains the index and RGB value of the color-table entry. For more information about the COLORTABLE_STRUCT structure, see the following Comments section.

lpColor

LPDWORD Points to the long integer that is to receive the RGB color value selected by the device driver to represent the requested color value.

Return Value

The return value specifies the outcome of the escape. This value is positive if the escape is successful. Otherwise, it is negative.

Comments

The COLORTABLE_STRUCT structure has the following form:

struct COLORTABLE_STRUCT {
    WORD  Index;
    DWORD rgb;
};

Following are the members of the COLORTABLE_STRUCT structure:

Index

Specifies the color-table index. Color-table entries start at zero for the first entry.

rgb

Specifies the desired RGB color value.

The color table for a device is a shared resource; changing the system display color for one window changes it for all windows. Only application developers who have a thorough knowledge of the display driver should use this escape.

The SETCOLORTABLE escape has no effect on devices with fixed color tables.

This escape is intended for use by both printer and display drivers. However, the EGA and VGA color drivers do not support it.

This escape changes the palette used by the display driver. However, because the color-mapping algorithms for the driver will probably no longer work with a different palette, an extension has been added to this function.

If the color index pointed to by the lpInData parameter is 0XFFFF, the driver is to leave all color-mapping functionality to the calling application. The application must use the proper color-mapping algorithm and take responsibility for passing the correctly mapped physical color to the driver (instead of the logical RGB color) in such device-driver functions as RealizeObject and ColorInfo.

For example, if the device supports 256 colors with palette indexes of 0 through 255, an application determines which index contains the color that it wants to use in a certain brush. It then passes this index in the low-order byte of the doubleword logical color passed to the RealizeObject device-driver function. The driver uses this color exactly as passed instead of performing its usual color-mapping algorithm. If the application wants to reactivate the driver's color-mapping algorithm (that is, if it restores the original palette when switching from its window context), then the color index pointed to by lpInData should be 0xFFFE.