Classes Class XbpPresSpace() :mapColor()

Method XbpPresSpace():mapColor() Foundation

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

Syntax 
:mapColor( <aRGB>, [<lExactMatch>] ) --> <nColorIndex>|<nRGBColor>|NIL
Parameters
<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.
<lExactMatch>
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.
Return

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.

Description

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.

Feedback

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.