Package io.keikai.axyra.sheets.content

Class ConditionalFormat

java.lang.Object
io.keikai.axyra.sheets.content.ConditionalFormat
public final class ConditionalFormat extends Object
A conditional-formatting rule (immutable). Covers cellIs (operator + formula), expression, top-N / above-average, duplicate / unique values, blank / error presence, notContainsText, and "date occurring" (timePeriod) rules — each with a differential format (fill, font color, bold / italic / underline / strikethrough, number format, and borders) — plus the visual color-scale / data-bar / icon-set kinds. Apply with Range.addConditionalFormat(...).

The visual kinds carry their full configuration (ECMA-376 §18.3.1.11 cfvo, §18.3.1.16 colorScale, §18.3.1.28 dataBar, §18.3.1.49 iconSet): threshold ConditionalFormat.ValueObjects, showValue(), icon-set reverse(), and the data-bar extension detail (gradient / border / negative-value / axis colors). A rule read from Sheet.conditionalFormats() can be re-issued through Range.addConditionalFormat(...). A rule read back reports only the first range it covers (firstRow() ...), so re-issuing a rule that covers several ranges covers that first range only.

Builder methods that take a Color accept only RGB colors and throw IllegalStateException for a theme, indexed or automatic color. Rule kinds and operators are checked only when the rule is added. 


 sheet.range("C2:C50").addConditionalFormat(ConditionalFormat.builder()
         .cellIs("greaterThan", "100")
         .fillColor(Color.of(0xFFFFC7CE))
         .bold()
         .build());

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    ConditionalFormat.Builder
    A fluent builder for a ConditionalFormat.
    static final record 
    ConditionalFormat.ValueObject
    A threshold value object of a color-scale / data-bar / icon-set rule (ECMA-376 §18.3.1.11 cfvo).

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    axisColor()
    The data-bar axis color token, or null.
    String
    axisPosition()
    The data-bar axis position (automatic / middle / none), or null.
    String
    barBorderColor()
    The data-bar border color token, or null when borderless.
    String
    barDirection()
    The data-bar direction (context / leftToRight / rightToLeft), or null.
    static ConditionalFormat.Builder
    builder()
    A builder.
    List<String>
    colorScaleColors()
    The color-scale gradient colors in cfvo order (engine color tokens: #RRGGBB hex, raw AARRGGBB hex, theme:N[:tint], indexed:N); empty for other kinds.
    String
    dataBarColor()
    The data-bar fill color token, or null for other kinds.
    int
    firstColumn()
    The first column of the rule's first range (0-based, inclusive); 0 for a rule that was built, not read back.
    int
    firstRow()
    The first row of the rule's first range (0-based, inclusive).
    String
    formula1()
    The first formula, without a leading = and without _xlfn. prefixes, or null when none is set.
    String
    formula2()
    The second formula of a between / notBetween rule, or null when none is set.
    static ConditionalFormat
    fromJson(String json)
    Builds a rule from the engine's JSON, the form behind Sheet.conditionalFormats().
    Boolean
    gradient()
    false when a data bar paints a solid fill instead of the default gradient; null when the source did not specify.
    String
    iconSetName()
    The icon-set name (e.g.
    int
    lastColumn()
    The last column of the rule's first range (0-based, inclusive); 0 for a rule that was built, not read back.
    int
    lastRow()
    The last row of the rule's first range (0-based, inclusive); 0 for a rule that was built, not read back.
    String
    negativeBorderColor()
    The negative-value bar border color token, or null.
    String
    negativeFillColor()
    The negative-value bar fill color token, or null.
    String
    operator()
    The cellIs operator, such as greaterThan or between; an empty string when the rule has none.
    int
    priority()
    Evaluation priority: 1 is evaluated first; 0 when unset.
    boolean
    reverse()
    Whether an icon set draws its icons in reversed order.
    boolean
    showValue()
    Whether the cell value is shown beside a data bar / icon set (ECMA-376 default true; meaningful for those kinds only).
    boolean
    stopIfTrue()
    Whether lower-priority rules stop evaluating once this one matches.
    String
    text()
    The text operand of a notContainsText rule, or null.
    TimePeriod
    timePeriod()
    The date window of a timePeriod rule, or null.
    ConditionalFormat.Builder
    toBuilder()
    A builder pre-loaded with this rule, for read–modify–write round-trips.
    String
    toJson()
    The rule as the JSON object sent to the engine.
    String
    type()
    The rule kind: cellIs, expression, colorScale, dataBar, iconSet, top10, aboveAverage, duplicateValues, uniqueValues, containsBlanks, notContainsBlanks, containsErrors, notContainsErrors, notContainsText or timePeriod; an empty string when unset.
    List<ConditionalFormat.ValueObject>
    valueObjects()
    The threshold value objects of a color-scale / data-bar / icon-set rule, in document order; empty for the non-visual kinds.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • builder

      public static ConditionalFormat.Builder builder()
      A builder. Call one rule-kind method (cellIs, expression, colorScale, ...), then style methods, then ConditionalFormat.Builder.build().

    • toBuilder

      public ConditionalFormat.Builder toBuilder()
      A builder pre-loaded with this rule, for read–modify–write round-trips.

    • toJson

      public String toJson()
      The rule as the JSON object sent to the engine. Used by the SDK.

    • fromJson

      public static ConditionalFormat fromJson(String json)
      Builds a rule from the engine's JSON, the form behind Sheet.conditionalFormats(). Used by the SDK.

    • type

      public String type()
      The rule kind: cellIs, expression, colorScale, dataBar, iconSet, top10, aboveAverage, duplicateValues, uniqueValues, containsBlanks, notContainsBlanks, containsErrors, notContainsErrors, notContainsText or timePeriod; an empty string when unset.

    • operator

      public String operator()
      The cellIs operator, such as greaterThan or between; an empty string when the rule has none.

    • formula1

      public String formula1()
      The first formula, without a leading = and without _xlfn. prefixes, or null when none is set. For the blank, error, text and time-period kinds of a read-back rule, it is the formula Excel stores.

    • formula2

      public String formula2()
      The second formula of a between / notBetween rule, or null when none is set.

    • text

      public String text()
      The text operand of a notContainsText rule, or null.

    • timePeriod

      public TimePeriod timePeriod()
      The date window of a timePeriod rule, or null.

    • priority

      public int priority()
      Evaluation priority: 1 is evaluated first; 0 when unset.

    • stopIfTrue

      public boolean stopIfTrue()
      Whether lower-priority rules stop evaluating once this one matches.

    • valueObjects

      public List<ConditionalFormat.ValueObject> valueObjects()
      The threshold value objects of a color-scale / data-bar / icon-set rule, in document order; empty for the non-visual kinds.

    • showValue

      public boolean showValue()
      Whether the cell value is shown beside a data bar / icon set (ECMA-376 default true; meaningful for those kinds only).

    • reverse

      public boolean reverse()
      Whether an icon set draws its icons in reversed order.

    • colorScaleColors

      public List<String> colorScaleColors()
      The color-scale gradient colors in cfvo order (engine color tokens: #RRGGBB hex, raw AARRGGBB hex, theme:N[:tint], indexed:N); empty for other kinds.

    • dataBarColor

      public String dataBarColor()
      The data-bar fill color token, or null for other kinds.

    • iconSetName

      public String iconSetName()
      The icon-set name (e.g. "3Arrows"), or null.

    • gradient

      public Boolean gradient()
      false when a data bar paints a solid fill instead of the default gradient; null when the source did not specify.

    • axisPosition

      public String axisPosition()
      The data-bar axis position (automatic / middle / none), or null.

    • barDirection

      public String barDirection()
      The data-bar direction (context / leftToRight / rightToLeft), or null.

    • barBorderColor

      public String barBorderColor()
      The data-bar border color token, or null when borderless.

    • negativeFillColor

      public String negativeFillColor()
      The negative-value bar fill color token, or null.

    • negativeBorderColor

      public String negativeBorderColor()
      The negative-value bar border color token, or null.

    • axisColor

      public String axisColor()
      The data-bar axis color token, or null.

    • firstRow

      public int firstRow()
      The first row of the rule's first range (0-based, inclusive). A rule that covers several ranges reports only its first range, so re-issuing it covers that range only. 0 for a rule that was built, not read back.

    • firstColumn

      public int firstColumn()
      The first column of the rule's first range (0-based, inclusive); 0 for a rule that was built, not read back.

    • lastRow

      public int lastRow()
      The last row of the rule's first range (0-based, inclusive); 0 for a rule that was built, not read back.

    • lastColumn

      public int lastColumn()
      The last column of the rule's first range (0-based, inclusive); 0 for a rule that was built, not read back.