GpiQueryRealColors

This function returns the RGB values of the distinct colors available on the currently associated device.

Syntax

GpiQueryRealColors(hps, flOptions, lStart, lCount, alColors)

Parameters

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

flOptions (ULONG) - input

Options.

LCOLOPT_INDEX: If this is specified, the index is to be returned for each RGB value.; If this flag is set when RGB mode is in force (LCOLF_RGB is set on GpiCreateLogColorTable), the RGB value is returned as the index.; Any color not available with the current logical color table is given a special index value of CLR_NOINDEX.; If it is not specified (flag is not set) index values are not returned.
Other: Other bits are reserved, and must be 0.

lStart (LONG) - input: Ordinal number of the first color required.; To start the sequence, this parameter is set to 0.; Note: This parameter is not the color index, and the order in which the colors are returned is not defined.

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

alColors (PLONG) - output

Array in which the information is returned.

Contents depend on the setting of the LCOLOPT_INDEX flag:

0: An array of color values (each value is as defined for GpiCreateLogColorTable).
1: An array of alternating color indexes and values, in the order index1, value1, index2, value2,... indexn, valuen. An even number of elements is always returned in this case.

Return Value

lRetCount (LONG) - returns

Number of elements returned.

>=0: Number of elements returned
GPI_ALTERROR: Error.

Remarks

Subject to space in the alColors parameter, all colors that are physically available on the device are returned. Use of the palette manager by other applications can effect the the physical colors available on the device. The available colors can change as a result of palette management, when this occurs a WM_REALIZEPALETTE message is sent to all applications.

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.

Example Code

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

HPS   hps;       /* Presentation-space handle. */
ULONG flOptions; /* Options. */
LONG  lStart;    /* Ordinal number of the first color required. */
LONG  lCount;    /* Maximum number of elements. */
PLONG alColors;  /* Array in which the information is returned. */
LONG  lRetCount; /* Number of elements returned. */

lRetCount = GpiQueryRealColors(hps, flOptions, lStart, lCount, alColors);

In this example we obtain the RGB values of the distinct colors available on the currently associated device.

#define INCL_GPILOGCOLORTABLE
#include <OS2.H>

LONG lResult; /* number of elements returned */
HPS hps; /* Presentation space handle. */
ULONG flOptions; /* options */
LONG lStart; /* ordinal number of first color */
LONG lCount; /* maximum number of elements */
LONG alColors[5]; /* array containing return information */

flOptions = LCOLOPT_INDEX; /* return index for each RGB value. */
lStart = 0L; /* start sequence at 0. */
lCount = 5L; /* maximum of 5 elements. */

lResult = GpiQueryRealColors(hps,
                            flOptions,
                            lStart,
                            lCount,
                            alColors);