TCondFormat / TCondFormatRule and CF12 spec classes

Unit: lxCondFormat

Die BIFF8-.xls-Conditional-Formatting-Familie unterstützt die Erweiterungsregeln von Excel 2007+. TXLSWorksheet verwaltet eine Sammlung von TCondFormat-Einträgen; jeder Eintrag umfasst einen oder mehrere Zellbereiche und enthält eine geordnete Liste von TCondFormatRule-Objekten, wobei jede Regel entweder eine klassische Zellwertregel oder eine CF12-Data-Bar-/Color-Scale-/Icon-Set-Regel ist. Die vier Sheet.AddCondFormat*-Einstiegspunkte (DataBar, ColorScale2, ColorScale3, IconSet) erzeugen Regeln des richtigen Untertyps. Verfügbar seit v2.34.0

Threshold kind enumeration

type
  TXLSCfValueKind = (
    cfvNumber      = 0,
    cfvMinOfRange  = 1,
    cfvMaxOfRange  = 2,
    cfvPercent     = 3,
    cfvPercentile  = 4,
    cfvFormula     = 5,
    cfvAutoMin     = 6,  // Excel 2010+ data-bar only
    cfvAutoMax     = 7); // Excel 2010+ data-bar only

Icon-set family enumeration

type
  TXLSIconSetType = (
    icsArrows3, icsArrows3Gray, icsFlags3,
    icsTrafficLights3, icsTrafficLightsRimmed3, icsSigns3,
    icsSymbols3, icsSymbolsUncircled3,
    icsArrows4, icsArrows4Gray, icsRedToBlack4,
    icsRatings4, icsTrafficLights4,
    icsArrows5, icsArrows5Gray,
    icsRatings5, icsQuarters5);

17 baseline Excel 2007 icon families. numeric stop count (3, 4, oder 5) ist encoded im enum Name

Threshold value (cfvo)

type
  TXLSCfValue = class
    constructor Create(AKind: TXLSCfValueKind;
      const AValue: WideString; AColor: LongWord);
    procedure SetThemeColor(ThemeId: Word; Tint: Single); // v2.43.0+
    procedure ClearThemeColor;                            // v2.43.0+
    property Kind: TXLSCfValueKind;
    property Value: WideString;       // numeric literal or formula text
    property Color: LongWord;         // BGR RGB for ColorScale stops
    property IsThemeColor: Boolean;    // v2.43.0+ true = theme mode active
    property ThemeColorId: Word;       // v2.43.0+ theme palette index
    property ThemeColorTint: Single;   // v2.43.0+ -1.0 .. 0.0 .. +1.0
  end;

Data bar payload

type
  TXLSDataBarSpec = class
    procedure SetThemeColor(ThemeId: Word; Tint: Single); // v2.43.0+ — opt bar fill into theme mode
    procedure ClearThemeColor;                            // v2.43.0+ — revert to RGB Color
    property Min: TXLSCfValue;
    property Max: TXLSCfValue;
    property Color: LongWord;         // bar fill
    property ShowValue: Boolean;      // false = hide cell text
    property MinLength: Byte;         // 0..100 percent
    property MaxLength: Byte;         // 0..100 percent
    property IsThemeColor: Boolean;    // v2.43.0+ true = theme mode active
    property ThemeColorId: Word;       // v2.43.0+ theme palette index
    property ThemeColorTint: Single;   // v2.43.0+ -1.0 .. 0.0 .. +1.0
  end;

XLSX Design Farbe Rundlauf (v2.43.0+)

Die Balkenfüllfarbe einer Data-Bar-Regel und die Farben je Stopp einer Color-Scale-Regel können statt mit einem fest verdrahteten RGB über einen Arbeitsmappen-Theme-Index plus einen Tint-Wert mit SetThemeColor(ThemeId, Tint) gesetzt werden. Der XLSX-Writer schreibt <color theme="N"/>, wenn Tint genau 0.0 ist, oder <color theme="N" tint="0.5"/> bei einem von null verschiedenen Wert, passend zu Excels eigener Ausgabe in der „kürzesten Form“. Der Reader parst beide Attributkombinationen und fällt auf den RGB-Pfad rgb= zurück, wenn weder theme noch tint vorhanden ist. Beide Modi schließen sich pro Platz gegenseitig aus; was immer zuletzt mit Set gesetzt wurde, gewinnt. IsThemeColor spiegelt den aktiven Modus zur Prüfung wider

BIFF8 CF12 speichert nur die aufgelöste RGB-Farbe — der Theme-Modus wird in dieser Version ausschließlich im XLSX-Backend round-tripped. iconSet-Regeln haben keine <color>-Elemente, daher wirkt sich der Zusatz für den Theme-Modus nicht auf sie aus

Color scale payload

type
  TXLSColorScaleSpec = class
    constructor Create(IsThreeStop: Boolean);
    procedure SetStop(I: Integer; Kind: TXLSCfValueKind;
      const Value: WideString; Color: LongWord);
    property StopCount: Integer;      // 2 or 3
    property Stops[I: Integer]: TXLSCfValue; default;
  end;

Icon set payload

type
  TXLSIconSetSpec = class
    constructor Create(ASetType: TXLSIconSetType);
    procedure SetThreshold(I: Integer; Kind: TXLSCfValueKind;
      const Value: WideString);
    // Per-stop icon override (v2.44.0+).
    procedure SetIconOverride(I: Integer;
      OverrideSet: TXLSIconSetType; IconId: Byte);
    procedure ClearIconOverride(I: Integer);
    property SetType: TXLSIconSetType;
    property Reverse: Boolean;        // reverse the icon order
    property ShowOnly: Boolean;       // true = icon only, hide cell text
    property IconCount: Integer;      // 3, 4 or 5 (derived from SetType)
    property Thresholds[I: Integer]: TXLSCfValue;
    property HasIconOverride[I: Integer]: Boolean;        // v2.44.0+
    property IconOverrideSet[I: Integer]: TXLSIconSetType; // v2.44.0+
    property IconOverrideId[I: Integer]: Byte;             // v2.44.0+
  end;

Per-Stopp-Symbolüberschreibung (v2.44.0+)

Jeder Stopp in einer Icon-Set-Regel kann sein angezeigtes Symbol mit einem beliebigen Symbol aus jeder der 17 eingebauten Symbolfamilien überschreiben, identifiziert durch ein (OverrideSet, IconId)-Paar. XLSX schreibt pro überschriebenem Stopp <cfIcon iconSet="..." iconId="N"/>. BIFF8 CF12 rendert weiterhin das Familiensymbol als Standard, weil das BIFF8-Wire-Format keinen Platz für Stopp-spezifische Überschreibungen hat — das ist in der aktuellen Version eine reine XLSX-Funktion. HasIconOverride[i] liefert nur für Stopps True, die ausdrücklich über SetIconOverride aktiviert wurden; die Standard-Symbole verwenden weiterhin den positionsabhängigen Standard der Familie

Rule

type
  TCondFormatRule = class
    property Kind: TXLSCfKind;
    property cfType: Word;            // CF-record subtype
    property Operator_: Word;         // comparison operator for cellIs
    property DataBar: TXLSDataBarSpec;       // non-nil for Data Bar rules
    property ColorScale: TXLSColorScaleSpec; // non-nil for Color Scale rules
    property IconSet: TXLSIconSetSpec;       // non-nil for Icon Set rules
    property Style: TXLSDxfStyle;        // DXF override; lazy-created (v2.35.0+)
    property DxfBlob: TXLSBlob;       // raw DXF bytes from Parse (v2.35.0+)
    property Priority: Word;          // CF12 ipriority; 0 = writer assigns (v2.45.0+)
  end;

Genau eines von DataBar / ColorScale / IconSet ist pro CF12-Regel nicht nil, passend zu Kind. Klassische ZellIs-Regeln (nicht CF12) lassen alle drei nil und verwenden Operator_ + Formula1 / Formula2

Die Eigenschaft Style (v2.35.0+) wird beim ersten Lesen verzögert erzeugt; das zurückgegebene Objekt gehört der Regel und wird in ihrem Destruktor freigegeben. Setze HasXxx über den entsprechenden SetXxx-Aufruf auf Style. Der BIFF8-Reader behält die rohen Bytes zusätzlich zur Dekodierung in DxfBlob in Style (v2.35.1+) bei, sodass ein Lade-Bearbeiten-Speichern-Roundtrip jede nach dem Laden vorgenommene Änderung an Style widerspiegelt; wenn der Benutzer nichts daran ändert, enthält die gespeicherte Datei dieselben Überschreibungen wie das Original

Bei BIFF8-CF12-Data-Bar-, Color-Scale- und Icon-Set-Regeln verlangt [MS-XLS], dass der Inline-DXF-Block leer ist. Seit v2.87.4 befolgt HotXLS diese Regel: Stilüberschreibungen, die über Rule.Style zugewiesen werden, werden beim Speichern von .xls-Dateien für diese drei CF12-Arten nicht serialisiert. Die Konfiguration der Data-Bar-/Color-Scale-/Icon-Set-Regel selbst wird weiterhin über den CF12-spezifischen Schlussteil bewahrt. Die Conditional-Formatting-Ausgabe für XLSX bleibt unverändert

Container

type
  TCondFormat = class
    procedure ClearRow(row: Integer);
    procedure ClearCol(col: Integer);
    procedure ClearRange(row1, col1, row2, col2: Integer);
    procedure MoveRanges(row1, col1, row2, col2,
      drow, dcol: Integer);
    function  RuleCount: Integer;                // v2.40.0+
    function  Rule(I: Integer): TCondFormatRule;  // v2.40.0+
    property Range[i: Integer]: TCondRange; default;
    property IsEmpty: Boolean;
    property IsExt12: Boolean;       // true = emits CONDFMT12/CF12
    property IsShadowed: Boolean;    // v2.37.0+ — duplicate CONDFMT marker
    property TotalRange: TCondRange; // v2.37.0+ — merged-extent range
  end;

Cross-version shadow detection (v2.37.0+)

Von Excel gespeicherte Dateien enthalten oft sowohl ein Excel-2003-CONDFMT für Zellwerte als auch ein Excel-2007+-CONDFMT12, die denselben sqref abdecken — der Zellwert-Datensatz ist ein versionsübergreifender Fallback, den das ältere Excel weiterhin rendern kann. Der Reader markiert den älteren Eintrag nach Erkennen einer exakten Bounding-Box-Übereinstimmung bei TotalRange mit IsShadowed = True, damit benutzerseitiger Code, der die Conditional-Format-Sammlung durchläuft, das Duplikat überspringen kann. Der Writer gibt beim Speichern weiterhin beide Datensatzfamilien aus, um die Kompatibilität zwischen Excel 2003 und Excel 2007+ zu erhalten

Wire format

Bei BIFF8 SaveAs(xlExcel97) geben CF12-Regeln CONDFMT12 ($0879) + CF12 ($087A) zusammen mit dem klassischen CONDFMT ($01B0) + CF ($01B1) aus, um die versionsübergreifende Kompatibilität mit Excel 2003 zu sichern. Der Reader erkennt die modernen Datensätze und stellt sie über dasselbe In-Memory-Regelmodell bereit, sodass von Excel erstellte .xls-Dateien mit Erweiterungsregeln ohne Datenverlust round-trippen

Example

// Data bar with custom min/max thresholds.
with Sheet.AddCondFormatDataBar('A1:A10', $00FF0000,
  cfvNumber, '0', cfvNumber, '100').DataBar do
begin
  ShowValue := True;
  MinLength := 10;
  MaxLength := 90;
end;

// 3 Arrows icon set, reversed so green points down.
with Sheet.AddCondFormatIconSet('B1:B10', icsArrows3).IconSet do
begin
  Reverse  := True;
  ShowOnly := False;
end;