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.