Method XbpPresSpace():mapColor() Foundation

Maps a RGB color to a color available in the color palette.

:mapColor( <aRGB>, [<lExactMatch>] ) --> <nColorIndex>|<nRGBColor>|NIL
<aRGB> := { nRed, nGreen, nBlue }
<aRGB> is an array containing three elements that are numeric values indicating the intensity of the colors red, green, and blue. The color mix of the color <nColorIndex> is based on the intensity of these three colors. The intensity of each of these colors is defined by integer values between 0 and 255.
The parameter controls if the color specified with <aRGB> should be mapped exactly or by using a "best fit" algorithm when the color is not available. The default value is .F. (false) which means that a "best fit" color is mapped.

The return value depends on the color depth supported by the device context linked to the presentation space object.

1. 8-bit color depth or less

The method returns a color index as a numeric value. It points to the color of the color palette the requested color <aRGB> is mapped to. If <lExactMatch> is set to .T. (true) and the requested color is not available in the color palette, the return value is NIL.

2. 16-bit color depth or higher

The method returns a RGB color value matching the requested color as close as possible.


The major purpose of the :mapColor() method is to determine how a specific color will be displayed on an output device having only a limited number of colors available. This is generally the case when the device context linked to the presentation space does not support a 24-bit or higher color depth. 24-bit colors allow for defining 16.7 million colors which makes a color palette obsolete. If a presentation space object uses a color palette due to the limitations of it's device context, the method can be used to check either if a color is available in the color palette ( <lExactMatch>==.T.) or what the requested color is mapped to ( <lExactMatch>==.F.). If the requested color cannot be matched close enough, it can be defined using the :setColorIndex() method.


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.