Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPILOGCOLORTABLE
 
LONG GpiQueryLogColorTable(hps, flOptions, iStart, clTable, alTable)
HPS hps;            /* presentation-space handle        */
ULONG flOptions;    /* color type to retrieve           */
LONG iStart;        /* starting index                   */
LONG clTable;       /* maximum number of values to copy */
PLONG alTable;      /* address of array for elements    */
 
The GpiQueryLogColorTable function retrieves the current logical-color-table
entries. This function copies the RGB color values from the current logical
color table to the array pointed to by alTable. It may also copy the
color-table index values for each RGB color value, depending on the value of
flOptions.
 
GpiQueryLogColorTable uses iStart as the index of the first color table
entry to copy. It continues to copy subsequent entries until it reaches the
end of the table or it has copied the number of values specified by clTable.
If a logical color-table entry has no corresponding RGB color value, the
function either copies -1 to the array or skips the entry, depending on the
value of flOptions. It skips the entry only if it is copying both the
color-table index and the RGB value to the array.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
flOptions  Specifies whether to retrieve indexes and RGB color values or
           just RGB values. If flOptions is LCOLOPT_INDEX, the function
           retrieves indexes and RGB color values. If it is 0x0000, the
           function retrieves RGB color values only.
 
iStart     Specifies the color-table index for the first entry to copy. The
           function copies this entry and all subsequent entries up to the
           number of values specified by clTable or the end of the logical
           color table.
 
clTable    Specifies the maximum number of values to copy to the array
           pointed to by alTable. If flOptions is 0x0000, this parameter
           specifies the number of RGB color values to retrieve. If
           flOptions is LCOLOPT_INDEX, this parameter specifies the combined
           total of index and RGB values to retrieve and must be an even
           value.
 
alTable    Points to the array to receive the color-table entries. If
           flOptions is equal to 0x0000, each element in the array receives
           an RGB color value. If flOptions is LCOLOPT_INDEX, each pair of
           array elements receives an index and a corresponding RGB value,
           with the first element in the pair receiving the index.
 
Return Value
 
The return value is the number of values copied to alTable if the function
is successful or QLCT_ERROR if an error occurred. The return value is
QLCT_RGB if flOptions is LCOLOPT_INDEX and the current logical color table
does not use indexes.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
the following:
 
     PMERR_INV_COLOR_OPTIONS
     PMERR_INV_COLOR_START_INDEX
     PMERR_INV_HPS
     PMERR_INV_LENGTH_OR_COUNT
     PMERR_PS_BUSY
 
Example
 
This example uses the GpiQueryLogColorTable function to retrieve all the
entries in the current logical color table.
 
LONG cColors;
SEL sel;
PLONG alColor;
 
/* 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. */
 
DosAllocSeg((USHORT) cColors * 2, &sel, SEG_NONSHARED);
alColor = MAKEP(sel, 0);
 
/* 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         */
 
See Also
 
GpiCreateLogColorTable, GpiQueryColorData, GpiQueryNearestColor,
GpiQueryRealColors, GpiQueryRGBColor, WinGetLastError
 
                                      ♦