GpiQueryColorIndex: Difference between revisions

Latest revision as of 20:06, 17 November 2025

This function returns the color index of the device color that is closest to the specified RGB color representation for the device connected to the specified presentation space.

Syntax

GpiQueryColorIndex(hps, flOptions, lRgbColor)

Parameters

hps (HPS) - input: Presentation-space handle.
flOptions (ULONG) - input: Options.; Reserved, and must be zero.
lRgbColor (LONG) - input: Specifies a color in RGB terms.

Return Value

lIndex (LONG) - returns

Color index providing closest match to the specified color.

>=0

Color index

CLR_BACKGROUND (0L)
CLR_BLUE (1L)
CLR_RED (2L)
CLR_PINK (3L)
CLR_GREEN (4L)
CLR_CYAN (5L)
CLR_YELLOW (6L)
CLR_NEUTRAL (7L)
CLR_DARKGRAY (8L)
CLR_DARKBLUE (9L)
CLR_DARKRED (10L)
CLR_DARKPINK (11L)
CLR_DARKGREEN (12L)
CLR_DARKCYAN (13L)
CLR_BROWN (14L)
CLR_PALEGRAY (15L)

GPI_ALTERROR: Error.

Remarks

If an RGB logical color table has been loaded, this call returns the same RGB color that is passed to it.

Errors

Possible returns from WinGetLastError:

PMERR_INV_HPS (0x207F): An invalid presentation-space handle was specified.
PMERR_PS_BUSY (0x20F4): An attempt was made to access the presentation space from more than one thread simultaneously.
PMERR_INV_COLOR_OPTIONS (0x2057): An invalid options parameter was specified with a logical color table or color query function.
PMERR_INV_RGBCOLOR (0x20C3): An invalid rgb color parameter was specified with GpiQueryNearestColor or GpiQueryColor.

Example Code

This example uses GpiQueryColorIndex to return the color index of the device color that is closest to the specified RGB color representation for the device connected to the specified presentation space.

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

LONG  lIndex;    /* closest match color index */
HPS   hps;       /* Presentation-space handle */
ULONG ulOptions; /* options */
LONG  lRgbColor; /* color in RGB terms */

/* reserved; set to 0 */
ulOptions = 0L;

/* color to find index for (r=137, g=136, b= 135 */
lRgbColor = (137*65536) + (136*256) + 135;

lIndex = GpiQueryColorIndex(hps, ulOptions, lRgbColor);

@@ Line 5: / Line 5: @@
 ==Parameters==
-; hps ([[HPS]]) - input
+; hps ([[HPS]]) - input: Presentation-space handle.
-: Presentation-space handle.
+; flOptions ([[ULONG]]) - input: Options.
-; flOptions ([[ULONG]]) - input
-: Options.
 : Reserved, and must be zero.
+; lRgbColor ([[LONG]]) - input: Specifies a color in RGB terms.
-; lRgbColor ([[LONG]]) - input
-: Specifies a color in RGB terms.
 ==Return Value==
-; lIndex ([[LONG]]) - returns
+; lIndex ([[LONG]]) - returns: Color index providing closest match to the specified color.
-: Color index providing closest match to the specified color.
 :; >=0
 :: Color index
@@ Line 54: / Line 48: @@
 ==Example Code==
-<PRE>
-#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI, INCL_PM, */
-#include &lt;os2.h&gt;
-HPS   hps;       /* Presentation-space handle. */
-ULONG flOptions; /* Options. */
-LONG  lRgbColor; /* Specifies a color in RGB terms. */
-LONG  lIndex;    /* Color index providing closest match to the specified color. */
-lIndex = GpiQueryColorIndex(hps, flOptions, lRgbColor);
-</PRE>
 This example uses GpiQueryColorIndex to return the color index of the device color that is closest to the specified RGB color representation for the device connected to the specified presentation space.
 <pre>
 #define INCL_GPILOGCOLORTABLE /* Color Table functions */
-#include &lt;os2.h&gt;
+#include <os2.h>
-LONG lIndex; /* closest match color index */
+LONG  lIndex;    /* closest match color index */
-HPS hps; /* Presentation-space handle */
+HPS   hps;       /* Presentation-space handle */
 ULONG ulOptions; /* options */
-LONG lRgbColor; /* color in RGB terms */
+LONG  lRgbColor; /* color in RGB terms */
 /* reserved; set to 0 */