GpiSetPaletteEntries

This function changes the entries in a palette.

Syntax

GpiSetPaletteEntries(hpal, ulFormat, ulStart, ulCount, aulTable)

Parameters

hpal (HPAL) - input

Palette handle.

ulFormat (ULONG) - input

Format of entries in the table.

LCOLF_CONSECRGB

Array of RGB values, corresponding to color indexes ulStart upwards. Each entry is 4 bytes long.

This is currently the only valid value for this parameter.

ulStart (ULONG) - input

Starting index.

ulCount (ULONG) - input

Count of elements in aulTable.

This must be greater than or equal to 0.

aulTable (PULONG) - input

Start of the application data area.

This contains the palette definition data. The format depends on the value of ulFormat.

Each color value is a 4-byte integer, with a value of

(F * 16777216) + (R * 65536) + (G * 256) + B

where:

F is a flag byte, which can take the following values (these can be ORed together if required):

• PC_RESERVED This index is an animating index. This means that the application might frequently change the RGB value, so the system should not map the logical index of the palette of another application to the entry in the physical palette used for this color.
• PC_EXPLICIT The low-order word of the logical color table entry designates a physical palette entry. This allows an application to show the contents of the device palette as realized for other logical palettes. This does not prevent the color in the entry from being changed for any reason.

R is red intensity value

G is green intensity value

B is blue intensity value. The maximum intensity for each primary is 255.

Returns

rc (BOOL) - returns

Success indicator.

• TRUE - Successful completion
• FALSE - Error occurred.

Errors

Possible returns from WinGetLastError:

PMERR_INV_HPAL (0x2111)

An invalid color palette handle was specified.

PMERR_INV_LENGTH_OR_COUNT (0x2092)

An invalid length or count parameter was specified.

PMERR_INV_COLOR_DATA (0x2054)

Invalid color table definition data was specified with GpiCreateLogColorTable.

PMERR_INV_COLOR_FORMAT (0x2055)

An invalid format parameter was specified with GpiCreateLogColorTable.

PMERR_INV_COLOR_START_INDEX (0x2058)

An invalid starting index parameter was specified with a logical color table or color query function.

PMERR_INSUFFICIENT_MEMORY (0x203E)

The operation terminated through insufficient memory.

PMERR_PALETTE_BUSY (0x2112)

An attempt has been made to reset the owner of a palette when it was busy.

PMERR_INV_IN_AREA (0x2085)

An attempt was made to issue a function invalid inside an area bracket. This can be detected while the actual drawing mode is draw or draw-and-retain or during segment drawing or correlation functions.

Example Code

This example changes the entries in a palette.

#define INCL_GPILOGCOLORTABLE
#include <OS2.H>

HPAL hpal;  /* palette handle */
UINT R, G, B;
typedef struct ENTRY
{
ULONG index;
ULONG pal_def;
}Entry;

struct TABLE
{
Entry entry1;
Entry entry2;
Entry entry3;
}Table;
BYTE F = PC_RESERVED;

/* In our table, there are 3 8-byte entries. The first 4 bytes */
/* of each entry represent the index and the second 4 bytes of */
/* each entry represent the value of the following formula:    */
/*                                                             */
/*    (F * 16777216) + (R * 65536) + (G * 256) + B             */
/*                                                             */
/* which is the palette definition.                            */
/* where F is the flag PC_RESERVED and R,G,B are the red,      */
/* green, and blue intensity values respectively.              */

F = 10; R = 10; G = 10;
Table.entry1.pal_def = (F * 16777216)+(R * 65536)+(G * 256) + B;
Table.entry1.index = 0L;

F = 25; R = 25; G = 25;
Table.entry2.pal_def = (F * 16777216)+(R * 65536)+(G * 256) + B;
Table.entry2.index = 1L;

F = 40; R = 40; G = 40;
Table.entry3.pal_def = (F * 16777216)+(R * 65536)+(G * 256) + B;
Table.entry3.index = 2L;

GpiSetPaletteEntries(hpal,
                     LCOLF_CONSECRGB, /* Array of RGB values,   */
                                      /* corresponding to color */
                                      /* indexes lStart         */
                                      /* upwards. Each entry    */
                                      /* is 4 bytes long.       */
                     0L,              /* start at zero.         */
                     3L,              /* elements in table.     */
       &Table.entry1.index);          /* first element in table. */

Remarks

The changes made by this function do not become apparent until WinRealizePalette is called, even for animating indices. Changes can be made more rapidly using GpiAnimatePalette with animating indices, assuming that the hardware being used supports this.

GpiSetPaletteEntries can be called at any time to change a logical palette, and the physical palette of the device will incorporate the changes as best it can; however, the system cannot guarantee that a change will be realized in the hardware palette, since realization depends on whether the associated window is in the foreground and on the number of available hardware palette entries.

All presentation spaces that have this palette selected into them (see GpiSelectPalette), are updated with the effects of this function.

If a palette is selected into a presentation space that is associated with a device context of type OD_METAFILE or OD_METAFILE_NOQUERY only the final color values are recorded in the metafile. This means that, while metafiling, this function must only be used for incremental additions to the color table.

It is an error if a palette is selected into a presentation space that is within an area or path definition when this function is issued.