GreQueryRealColors

GreQueryRealColors stores, in the array addressed by pArray, the RGB values of the distinct colors available on the currently associated device.

This function must be supported by the presentation driver. GreQueryRealColors is called by GpiQueryRealColors in response to an application requesting the currently available colors for the device context.

Simulation support

None. This function is mandatory for all drivers.

Syntax

GreQueryRealColors(hdc, flOptions, lStart, cArray, pArray, pInstance, lFunction);

Parameters

hdc (HDC) - input

Device context handle.

flOptions (ULONG) - input

Options flag.

Valid options are:

LCOLOPT_REALIZED

If set, the information is required when the logical color table (if any) is realized. When this flag is not set, the information is required when the logical color table is not realized.

LCOLOPT_INDEX

If set, the handling routine must return the index for each RGB value. Other flags are reserved and must be 0.

lStart (LONG) - input

Ordinal number of the first color required.

Typically, this is 0 to start the sequence. This value does not necessarily bear any relationship to the color index because the order in which the colors are returned is not defined.

cArray (LONG) - input

Number of elements available in the array.

pArray (PLONG) - input

Pointer to array in which data is returned.

When LCOLOPT_INDEX is set, this is an array of alternating color indexes and values (in the order, index1, value1, index2, value2 and so on). If there is a color table, colors that are not in the table but are available on the device, have a special index of QLCT_NOTLOADED. In RGB mode, the RGB value is returned in the color indexes.

When LCOLOPT_INDEX is not set, this is an array of color values. Each value is the same as those defined for GreCreateLogColorTable.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreQueryRealColors.

Returns

rc (LONG) - returns

Return Code.

On completion, the handling routine must return the number of colors returned in the array (cColors), or GPI_ALTERROR if an error occurred

Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:

• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_INV_COLOR_OPTIONS
• PMERR_INV_COLOR_START_INDEX
• PMERR_INV_HDC
• PMERR_INV_LENGTH_OR_COUNT

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Sample

#define INCL_GRE_COLORTABLE
#include <os2.h>

HDC      hdc;        /*  Device context handle. */
ULONG    flOptions;  /*  Options flag. */
LONG     lStart;     /*  Ordinal number of the first color required. */
LONG     cArray;     /*  Number of elements available in the array. */
PLONG    pArray;     /*  Pointer to array in which data is returned. */
PVOID    pInstance;  /*  Pointer to instance data. */
ULONG    lFunction;  /*  High-order WORD=flags; low-order WORD=NGreQueryRealColors. */
LONG     rc;         /*  Return Code. */

rc = GreQueryRealColors(hdc, flOptions, lStart,
       cArray, pArray, pInstance, lFunction);