HotXLS Docs

Custom colour Palette

Overview

Excel workbooks manage colour formatting using two models: the older 56-colour indexed palette in BIFF8 (classic XLS) and arbitrary RGB bindings or theme slots in OpenXML (XLSX); HotXLS provides APIs to customise palette mapping indexes and smoothly bridge the differences between these formats

Palette colour Indexing

The BIFF8 format maps formatting colours to index entries from 8 to 63; use the workbook colours interface to override the default colour definitions

procedure SetColor(const AIndex: Integer; const AColor: TColor);

If you assign a custom RGB value directly to a cell without updating the palette index, HotXLS will automatically map it to the closest colour in the workbook's active palette

Deterministic Indexed-Colour Resolution

IXLSWorkbook and TXLSXWorkbook expose matching ResolveIndexedColor overloads for interpreting an index without changing the workbook

The caller identifies the source index space as public ColorIndex, BIFF icv, or OOXML indexed; the result keeps palette, automatic, system, and invalid tokens distinct and reports the normalised ARGB value only when a concrete colour is available

System and automatic tokens never read the current desktop implicitly; pass an explicit system-colour resolver when environment-specific RGB output is required

The usage role preserves format-specific meaning such as BIFF border index zero being unspecified rather than black

Use NearestIndexedColor when an RGB value must be mapped to the nearest physical palette entry; the shared cached OKLab matcher returns public and physical indexes without changing the workbook

Use ScanIndexedColorUsage to obtain a deterministic 56-slot inventory before planning palette changes; definitions and references from styles, worksheet objects, charts, comments, and conditional formats mark the affected slots as locked

Mutation-Free Palette Planning

Use BuildBiffPalettePlan to preview how direct RGB and resolved theme colours can fit into the 56 physical BIFF palette slots without changing the workbook

The plan preserves every indexed slot reported as locked, retains existing exact colours at the lowest matching slot, assigns exact colours whilst capacity remains, and uses frequency-weighted deterministic OKLab clustering only when unique targets exceed the free slots

Each target reports its selected public and physical index, mapped ARGB value, frequency weight, squared perceptual distance, and exact-match state; summary fields report exact weight, weighted error, maximum error, changed slots, and whether quantisation was required

The source palette generation and hash let ApplyBiffPalettePlan reject a stale or tampered plan before any slot changes; a successful application rebuilds the cached matcher once and a valid no-op plan leaves the generation unchanged

Classic workbooks also expose BiffPaletteSavePolicy; its default preserves the historical palette, whilst the explicit optimisation value builds and applies a current plan only for BIFF8 output and restores the original palette if the save fails or is cancelled

Rich RGB colour Mapping

XLSX workbooks bypass palette limitations and allow direct assignment of 24-bit RGB values; check the colour conversion APIs below

Copyright © 2010-2026 losLab Software