GpiQueryLogColorTable

This function returns the logical color table.

Syntax

GpiQueryLogColorTable(hps, flOptions, lStart, lCount, alArray)

Parameters

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

flOptions (ULONG) - input

Specifies options.

LCOLOPT_INDEX: B'1' The index is to be returned for each RGB value.; Other flags are reserved and must be B'0'.

lStart (LONG) - input: Starting index for which data is to be returned.; This must be greater than or equal to zero.

lCount (LONG) - input: Count of elements.; Number of elements available in alArray. It must be greater or equal to 0.

alArray (PLONG) - output: Array in which the information is returned.; If the LCOLOPT_INDEX flag is B'0', it is an array of RGB values (each value is as defined for GpiCreateLogColorTable), starting with the specified index, and ending either when there are no further loaded entries in the table, or when alArray has been exhausted. If the logical color table is not loaded with a contiguous set of indexes, QLCT_NOTLOADED is returned as the RGB value for any index values, outside the default range, that have not been explicitly loaded.; If the LCOLOPT_INDEX flag is B'1', it is an array of alternating color indexes and RGB values, in the order index1, RGB value1, index2, RGB value2,... An even number of elements is always returned. If the logical color table is not loaded with a contiguous set of indexes, any index values that are not loaded are skipped.

Return Value

lRetCount (LONG) - returns

Number of elements returned and error indicators.

QLCT_RGB: Table in RGB mode, no elements returned
>0: Number of elements returned
QLCT_ERROR: Error.

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_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.
PMERR_INV_COLOR_OPTIONS (0x2057): An invalid options parameter was specified with a logical color table or color query function.
PMERR_INV_COLOR_START_INDEX (0x2058): An invalid starting index parameter was specified with a logical color table or color query function.
PMERR_PALETTE_SELECTED (0x210F): Color palette operations cannot be performed on a presentation space while a palette is selected.

Example Code

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

HPS   hps;       /* Presentation-space handle. */
ULONG flOptions; /* Specifies options. */
LONG  lStart;    /* Starting index for which data is to be returned. */
LONG  lCount;    /* Count of elements. */
PLONG alArray;   /* Array in which the information is returned. */
LONG  lRetCount; /* Number of elements returned and error indicators. */

lRetCount = GpiQueryLogColorTable(hps, flOptions, lStart, lCount, alArray);

This example uses the GpiQueryLogColorTable function to retrieve all the entries in the current logical color table.

#define INCL_GPILOGCOLORTABLE /* Color Table functions */
#define INCL_DOSMEMMGR /* DOS Memory Manager Functions */
#define INCL_DEV /* Device Function definitions */
#include <os2.h>

HPS hps; /* presentation space handle */
LONG cColors; /* number of colors */
PLONG alColor; /* color table array */

/* Find out how many colors are in the color table. */
DevQueryCaps(GpiQueryDevice(hps), CAPS_COLORS, 1L, &cColors);

/* Allocate space for the color values and indexes. */
DosAllocMem((VOID *)alColor,(ULONG)cColors*2, PAG_COMMIT | PAG_READ | PAG_WRITE);

/* Retrieve the values. */
GpiQueryLogColorTable(hps, /* presentation space */
                       LCOLOPT_INDEX, /* retrieve indexes and RGB values */
                       0L, /* start with first entry */
                       cColors * 2, /* copy 2 values for each entry */
                       alColor); /* array to receive values */