NearestIndexedColor method
Finds the nearest entry among physical palette slots 8..63 and returns both its public ColorIndex value and physical slot
The method is available on both IXLSWorkbook and TXLSXWorkbook and does not modify palette or workbook state
Syntax
function NearestIndexedColor( AArgb: LongWord; out AMatch: TXLSNearestIndexedColorMatch): Boolean;
Input
AArgb accepts a 24-bit $00RRGGBB value or an opaque $FFRRGGBB value
A zero alpha byte is normalized to $FF; partially transparent values are rejected because indexed workbook palette entries are opaque
Result
| Field | Meaning |
|---|---|
InputARGB | The normalized opaque input color |
ColorIndex | The public palette index from 1 through 56 |
PaletteSlot | The physical BIFF or OOXML palette slot from 8 through 63 |
ARGB | The normalized opaque color stored at the selected palette slot |
DistanceSquared | The squared Euclidean distance in OKLab color space |
ExactMatch | True when the selected entry has the same RGB channels as the normalized input |
The function returns false for a partially transparent input or when the palette cache is unavailable; failure initializes ColorIndex to zero and PaletteSlot to -1
Matching contract
Each workbook caches the normalized ARGB and OKLab coordinates of its 56 physical palette entries
A palette reset rebuilds the complete cache and an effective single-slot change updates only that cached slot
Every query converts the input once and performs one fixed 56-entry scan with no query history or unbounded cache growth
Equal distances select the lowest public index, including duplicate palette colors, so results remain deterministic across engines and runs
Automatic, system, and invalid color tokens are not candidates; use ResolveIndexedColor to classify those values
Example
if Workbook.NearestIndexedColor($FF13579B, Match) then
begin
PaletteIndex := Match.ColorIndex;
if Match.ExactMatch then
UseExactPaletteColor(Match.ARGB);
end;