XlsApplyThemeColorToDrawing function

Unit: lxHandle

Applies one of the 12 Office theme color slots (plus an optional tint) to a drawing-side TXLSColorFormat — the same handle that FillFormat.ForeColor and LineFormat.ForeColor expose on shapes and chart elements. Available since v2.62.0 (chart backlog wave D phase 5). v2.64.0 (phase 7) added a workbook-level in-memory side-table so a subsequent XlsGetDrawingThemeColor call inside the same process can recover the original theme idx + tint.

Use this helper when the application wants chart fills, chart line colors, or shape fills to track the workbook theme palette the same way cells do through Interior.SetThemeColor.

Syntax

procedure XlsApplyThemeColorToDrawing(
  ColorFormat: TXLSColorFormat;
  Workbook   : TXLSWorkbook;
  ThemeIdx   : Word;
  Tint       : Double);

Parameters

ColorFormat — the drawing color slot to update. Typically the ForeColor of a TXLSFillFormat or TXLSLineFormat.

Workbook — the host TXLSWorkbook. Needed to resolve the theme palette and to hold the in-memory side-table.

ThemeIdx — 0-based theme slot (0=lt1, 1=dk1, 2=lt2, 3=dk2, 4..9=accent1..6, 10=hlink, 11=foHlink).

Tint — spec-style lighter/darker adjustment in the range -1.0 .. +1.0.

Remarks

The helper performs two writes per call:

OfficeArt opt blob (on disk). The theme idx + tint is resolved through the workbook's BIFF theme palette into a concrete RGB and written into the drawing color slot. BIFF8 OfficeArt is a pre-Office-2007 binary format with no native theme color encoding, so this is the only piece that survives Save / Open.
In-memory side-table on the workbook (v2.64.0+). The setter also records the original (ThemeIdx, Tint) in TXLSWorkbook.FDrawingThemeColors keyed by (ColorFormat._Container, ColorFormat._Pid). The companion XlsGetDrawingThemeColor reader pulls back those values within the same process. Re-setting the same slot overwrites the entry, so the side-table tracks the latest intent rather than accumulating history.

Why single-process only. The BIFF8 OfficeArt 4-byte ColorRef encodes indexed / RGB / scheme / sysColor variants, but there's no extension record analogous to XFExt $087D where the theme idx + tint could persist. So the cap on Save / Open round-trip is structural to the file format, not a HotXLS gap. After reload the workbook is a fresh TXLSWorkbook instance with an empty side-table and XlsGetDrawingThemeColor returns False, falling through to ColorFormat.RGB.

For cell colors that round-trip through Save / Open, use the dedicated IXLSInterior.SetThemeColor / IXLSFont.SetThemeColor / IXLSBorder.SetThemeColor entry points instead — they leverage the XFExt $087D rich-color side record to round-trip the theme idx + tint verbatim through Excel 2007+.

Example

Recolors a shape's solid fill to accent5 with a 25% darker tint, then reads the theme intent back from the workbook side-table to display it on a property pane. After SaveAs / Open the side-table starts empty again, so callers that need persistent intent should keep their own state.

var
  Shape    : TXLSShape;
  ThemeIdx : Word;
  Tint     : Double;
begin
  Shape := Workbook.Worksheets[1].Shapes.Items[0];
  XlsApplyThemeColorToDrawing(Shape.Fill.ForeColor, Workbook, 8, - 0.25);

  // Same process — the side-table still has the entry.
  if XlsGetDrawingThemeColor(Shape.Fill.ForeColor, Workbook, ThemeIdx, Tint)
  then
    ShowMessage(Format('theme=%d tint=%.2f', [ThemeIdx, Tint]));

  Workbook.SaveAs('ThemedShape.xls', xlExcel97);
end;

Unit: lxHandle

Syntax

Parameters

Remarks

Example

See also