GpiQueryPaletteInfo

This function passes back the information for a palette.

Syntax

GpiQueryPaletteInfo(hpal, hps, flOptions, ulStart, ulCount, aulArray)

Parameters

hpal (HPAL) - input

Palette handle.

hps (HPS) - input

Presentation-space handle.

flOptions (ULONG) - input

Specifies options.

LCOLOPT_INDEX - If this is set, the index is to be returned for each RGB value in the aulArray parameter.

Other flags are reserved and must be 0.

ulStart (ULONG) - input

The starting index for which data is to be returned.

ulCount (ULONG) - input

Count of elements.

Number of elements available in aulArray.

If 0 is specified, the number of elements required to return the palette information in aulArray is returned.

aulArray (PULONG) - output

An array in which the palette information is returned.

If LCOLOPT_INDEX is not specified, this is an array of RGB values (each value is as defined for GpiCreatePalette), starting with the specified index, and ending either when there are no further entries in the palette, or when aulArray has been exhausted. If the palette is not loaded with a contiguous set of indices, QLCT_NOTLOADED is returned as the RGB value for any index values, outside the default range, that have not been explicitly loaded.

If LCOLOPT_INDEX is specified, this is an array of alternating color indices and RGB values, in the order: index1, RGB value1, index2, RGB value2, .... An even number of elements is always returned. If the palette is not loaded with a contiguous set of indices, any index values that are not present are skipped.

Returns

lRetCount (LONG) - returns

Number of elements.

Zero is returned if no palette is selected.

PAL_ERROR - Error occurred

Otherwise - The number of elements of palette information passed back in the aulArray parameter, unless ulCount parameter is 0, in which case this is the total number of elements that are needed to hold the palette information.

Calling Sequence

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

HPAL      hpal;       /*  Palette handle. */
HPS       hps;        /*  Presentation-space handle. */
ULONG     flOptions;  /*  Specifies options. */
ULONG     ulStart;    /*  The starting index for which data is to be returned. */
ULONG     ulCount;    /*  Count of elements. */
PULONG    aulArray;   /*  An array in which the palette information is returned. */
LONG      lRetCount;  /*  Number of elements. */

lRetCount = GpiQueryPaletteInfo(hpal, hps,
              flOptions, ulStart, ulCount, aulArray);

Example Source Code

This example uses GpiQueryPaletteInfo to query the palette information and, if any values are returned, assigns the palette's first color value to a variable.

 

#define INCL_GPILOGCOLORTABLE   /* Color Table functions        */
#include <os2.h>

LONG  lRetCount;        /* number of elements                   */
HPAL  hpal;             /* palette handle                       */
ULONG flOptions;        /* options                              */
ULONG  ulStart;         /* starting index                       */
ULONG  ulCount;         /* count of elements in array           */
ULONG  *aulArray;       /* palette information array            */
ULONG  ulFirstColor;    /* first color in palette               */

/* specify no options */
flOptions = 0L;

/* start at index 0 */
ulStart = 0L;

/* tell function to determine element count */
ulCount = 0L;

lRetCount = GpiQueryPaletteInfo(hpal, NULLHANDLE, flOptions,
                                ulStart, ulCount,
                                aulArray);

/* if palette info returned, assign value of first color */
ulFirstColor = aulArray[0];

Remarks

The information passed back is in the same format as that required to create a palette (see GpiCreatePalette).

If a non-NULL palette handle is passed in the hpal parameter, the information is returned for that palette, and the hps parameter is ignored. Otherwise, hps identifies a presentation space for which the default colors are returned as a palette.

Note

In this case the default colors are returned, even if a logical color table is currently loaded into the presentation space.