GreQueryLogColorTable

From EDM2
Jump to: navigation, search

GreQueryLogColorTable stores an array of the current logical color values at the location addressed by pArray.

This function must be supported by the presentation driver. GreQueryLogColorTable is called by GpiQueryLogColorTable in response to an application's request for the currently configured logical color table. This function can be handled by bit-map simulation.

Simulation support
None. This function is mandatory for all drivers.

Syntax

GreQueryLogColorTable(hdc, flOptions, lStart, cArray, pArray, pInstance, lFunction)

Parameters

hdc (HDC) - input 
Device context handle.
flOptions (ULONG) - input 
Options flag.
The only valid option flag is:
LCOLOPT_INDEX
If set, the handling routine must return the index for each RGB value.
lStart (LONG) - input
Starting index for which data is to be returned.
cArray (LONG) - input
Number of elements available in the array.
pArray (PLONG) - input
Pointer to the array in which the information is returned.
When LCOLOPT_INDEX is set, pArray points to an array of alternating color indexes and values (index1, value1, index2, value2, and so forth). If the logical color table is not loaded with a contiguous set of indexes, any index values that are not loaded are skipped.
When LCOLOPT_INDEX is not set, pArray points to an array of RGB color values in which the information is to be returned. Each value is the same as those defined for GreCreateLogColorTable, starting with the specified index and ending when there are no further loaded entries in the table or when cCount has been exhausted. If the logical color table is not loaded with a contiguous set of indexes, QLCT_NOTLOADED is returned as the color value for any index values that are not loaded.
pInstance (PVOID) - input
Pointer to instance data.
lFunction (ULONG) - input
High-order WORD=flags; low-order WORD=NGreQueryLogColorTable.

Returns

rc (LONG) - returns
Return Code.

The handling routine must return a LONG value indicating the number of elements returned in pArray or:

  • QLCT_ERROR Error.
  • QLCT_RGB Color table is in RGB mode and no elements are returned.

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;     /*  Starting index for which data is to be returned. */
LONG     cArray;     /*  Number of elements available in the array. */
PLONG    pArray;     /*  Pointer to the array in which the information is returned. */
PVOID    pInstance;  /*  Pointer to instance data. */
ULONG    lFunction;  /*  High-order WORD=flags; low-order WORD=NGreQueryLogColorTable. */
LONG     rc;         /*  Return Code. */

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