Package io.keikai.axyra.sheets.style

Class Color

java.lang.Object
io.keikai.axyra.sheets.style.Color
public final class Color extends Object
An immutable spreadsheet color in one of four kinds: plain ARGB, a legacy indexed-palette reference, a theme-palette reference with an optional tint, or the automatic (window-text) color. These are the color forms of OOXML (ECMA-376 §18.8.3 CT_Color).

Construct with rgb(int, int, int), argb, of(int), indexed(int), theme(int) or auto(). Check the kind with isRgb(), isIndexed(), isTheme() and isAuto() before you call a kind-specific reader: argb(), red() and the other channel readers work on RGB colors only, themeIndex() and tint() on theme colors only, and each throws IllegalStateException on the wrong kind.

Colors read back from a cell keep their kind: a theme color reads back as a theme color, not as its resolved RGB value. Some setters accept RGB colors only; they say so and throw IllegalStateException for the other kinds. 


 Color accent = Color.theme(4, -0.25);   // accent 1, 25 % darker
 Color brand = Color.rgb(0x1F, 0x4E, 0x79);

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Color
    BLACK
    Opaque black, #000000.
    static final Color
    BLUE
    Opaque blue, #0000FF.
    static final Color
    GRAY
    Opaque gray, #808080.
    static final Color
    GREEN
    Opaque green, #008000 (HTML green, not #00FF00).
    static final Color
    RED
    Opaque red, #FF0000.
    static final Color
    WHITE
    Opaque white, #FFFFFF.
    static final Color
    YELLOW
    Opaque yellow, #FFFF00.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    alpha()
    The alpha channel of an RGB color.
    int
    argb()
    The packed 0xAARRGGBB value of an RGB color.
    static Color
    argb(int a, int r, int g, int b)
    An RGB color with an alpha channel.
    static Color
    auto()
    The automatic color: Excel's "Automatic", which draws as the window-text color (black by default).
    int
    blue()
    The blue channel of an RGB color.
    boolean
    equals(Object o)
     
    static Color
    fromJson(Object value)
    Decodes the engine's JSON color form: a map such as {"rgb":"#AARRGGBB"}, {"indexed":N}, {"theme":I,"tint":T} or {"auto":true}, or a string in a form that parse(String) accepts.
    int
    green()
    The green channel of an RGB color.
    int
    hashCode()
     
    static Color
    indexed(int index)
    A legacy indexed-palette color (ECMA-376 §18.8.27).
    int
    indexedValue()
    The palette index of an indexed color.
    boolean
    isAuto()
    Whether this is the automatic (window-text) color, auto().
    boolean
    isIndexed()
    Whether this is a legacy indexed-palette color; then indexedValue() works.
    boolean
    isRgb()
    Whether this is a plain ARGB color; then argb() and the channel readers work.
    boolean
    isTheme()
    Whether this is a theme-palette color; then themeIndex() and tint() work.
    static Color
    of(int argb)
    An RGB color from a packed 0xAARRGGBB value.
    static Color
    parse(String s)
    Parses a color string.
    int
    red()
    The red channel of an RGB color.
    static Color
    rgb(int r, int g, int b)
    An opaque RGB color (alpha 255).
    static Color
    theme(int themeIndex)
    A theme-palette color with no tint.
    static Color
    theme(int themeIndex, double tint)
    A theme-palette color with a tint.
    int
    themeIndex()
    The theme index of a theme color, in the order of theme(int, double) (0 = light 1, 1 = dark 1).
    double
    tint()
    The tint of a theme color.
    String
    toHex()
    The hex form of an RGB color, upper case with alpha, e.g.
    Object
    toJsonValue()
    The JSON value sent to the engine, in the forms that fromJson(Object) reads.
    String
    toString()
     

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • BLACK

      public static final Color BLACK
      Opaque black, #000000.

    • WHITE

      public static final Color WHITE
      Opaque white, #FFFFFF.

    • RED

      public static final Color RED
      Opaque red, #FF0000.

    • GREEN

      public static final Color GREEN
      Opaque green, #008000 (HTML green, not #00FF00).

    • BLUE

      public static final Color BLUE
      Opaque blue, #0000FF.

    • YELLOW

      public static final Color YELLOW
      Opaque yellow, #FFFF00.

    • GRAY

      public static final Color GRAY
      Opaque gray, #808080.

  • Method Details

    • rgb

      public static Color rgb(int r, int g, int b)
      An opaque RGB color (alpha 255).
      Parameters:
      r - red channel, 0-255; only the low 8 bits are kept
      g - green channel, 0-255; only the low 8 bits are kept
      b - blue channel, 0-255; only the low 8 bits are kept
      Returns:
      the color

    • argb

      public static Color argb(int a, int r, int g, int b)
      An RGB color with an alpha channel.
      Parameters:
      a - alpha, 0-255 (255 = opaque); only the low 8 bits are kept
      r - red channel, 0-255; only the low 8 bits are kept
      g - green channel, 0-255; only the low 8 bits are kept
      b - blue channel, 0-255; only the low 8 bits are kept
      Returns:
      the color

    • of

      public static Color of(int argb)
      An RGB color from a packed 0xAARRGGBB value. Note that of(0xFF0000) has alpha 0; write of(0xFFFF0000) or use rgb(int, int, int) for an opaque color.
      Parameters:
      argb - the packed value, alpha in the top byte
      Returns:
      the color

    • indexed

      public static Color indexed(int index)
      A legacy indexed-palette color (ECMA-376 §18.8.27). Indices 0-63 address the 64-entry palette; 64 is the system foreground and 65 the system background.
      Parameters:
      index - the palette index, 0-255
      Returns:
      the color
      Throws:
      IllegalArgumentException - if index is outside 0-255

    • theme

      public static Color theme(int themeIndex)
      A theme-palette color with no tint. themeIndex uses the order of theme(int, double): 0 = light 1, 1 = dark 1, 2 = light 2, 3 = dark 2, 4-9 = accent 1-6, 10 = hyperlink, 11 = followed hyperlink.
      Parameters:
      themeIndex - the SpreadsheetML theme index, 0-11
      Returns:
      the color
      Throws:
      IllegalArgumentException - if themeIndex is outside 0-11

    • theme

      public static Color theme(int themeIndex, double tint)
      A theme-palette color with a tint. themeIndex is the SpreadsheetML cell-color index: 0 = light 1 (Excel's "Background 1"), 1 = dark 1 ("Text 1"), 2 = light 2 ("Background 2"), 3 = dark 2 ("Text 2"), 4-9 = accent 1-6, 10 = hyperlink, 11 = followed hyperlink.

      This order swaps 0/1 and 2/3 against the theme file order of Theme.Slot. So Color.theme(0) is white and Color.theme(1) is black in the default Office theme. The index is written to the file as given, so Excel shows the same color. 

      
 Color text = Color.theme(1);            // dark 1: black text
 Color band = Color.theme(4, 0.8);       // accent 1, 80 % lighter
      Parameters:
      themeIndex - the SpreadsheetML theme index, 0-11
      tint - lightens (positive) or darkens (negative) the color, in [-1, 1]; 0 means no change (ECMA-376 §18.8.19)
      Returns:
      the color
      Throws:
      IllegalArgumentException - if themeIndex is outside 0-11, or tint is outside [-1, 1] or NaN

    • auto

      public static Color auto()
      The automatic color: Excel's "Automatic", which draws as the window-text color (black by default). A cell attribute that has no explicit color reads back as this value.
      Returns:
      the shared automatic color

    • parse

      public static Color parse(String s)
      Parses a color string. Accepted forms: "#RRGGBB" (opaque), "#AARRGGBB", "auto" (any case), "indexed:N" and "theme:I:TINT", where TINT is the tint times 10000 ("theme:4:-2500" is accent 1, 25 % darker). The leading # is required for hex.
      Parameters:
      s - the color string, may be null
      Returns:
      the color, or null when s is null or not one of the accepted forms, or its index or tint is out of range

    • fromJson

      public static Color fromJson(Object value)
      Decodes the engine's JSON color form: a map such as {"rgb":"#AARRGGBB"}, {"indexed":N}, {"theme":I,"tint":T} or {"auto":true}, or a string in a form that parse(String) accepts. Not intended for application code; public only for the SDK's own packages.
      Parameters:
      value - the decoded JSON value
      Returns:
      the color, or null for an unrecognized value
      Throws:
      IllegalArgumentException - if an indexed or theme value is out of range

    • toJsonValue

      public Object toJsonValue()
      The JSON value sent to the engine, in the forms that fromJson(Object) reads. Not intended for application code; public only for the SDK's own packages.
      Returns:
      a new map on each call

    • isRgb

      public boolean isRgb()
      Whether this is a plain ARGB color; then argb() and the channel readers work.

    • isIndexed

      public boolean isIndexed()
      Whether this is a legacy indexed-palette color; then indexedValue() works.

    • isTheme

      public boolean isTheme()
      Whether this is a theme-palette color; then themeIndex() and tint() work.

    • isAuto

      public boolean isAuto()
      Whether this is the automatic (window-text) color, auto().

    • indexedValue

      public int indexedValue()
      The palette index of an indexed color.
      Returns:
      the index, 0-255
      Throws:
      IllegalStateException - if this is not an indexed color

    • themeIndex

      public int themeIndex()
      The theme index of a theme color, in the order of theme(int, double) (0 = light 1, 1 = dark 1).
      Returns:
      the index, 0-11
      Throws:
      IllegalStateException - if this is not a theme color

    • tint

      public double tint()
      The tint of a theme color.
      Returns:
      the tint in [-1, 1]; 0 when there is none
      Throws:
      IllegalStateException - if this is not a theme color

    • argb

      public int argb()
      The packed 0xAARRGGBB value of an RGB color.
      Returns:
      the packed value, alpha in the top byte
      Throws:
      IllegalStateException - if this is not an RGB color

    • alpha

      public int alpha()
      The alpha channel of an RGB color.
      Returns:
      0-255; 255 is opaque
      Throws:
      IllegalStateException - if this is not an RGB color

    • red

      public int red()
      The red channel of an RGB color.
      Returns:
      0-255
      Throws:
      IllegalStateException - if this is not an RGB color

    • green

      public int green()
      The green channel of an RGB color.
      Returns:
      0-255
      Throws:
      IllegalStateException - if this is not an RGB color

    • blue

      public int blue()
      The blue channel of an RGB color.
      Returns:
      0-255
      Throws:
      IllegalStateException - if this is not an RGB color

    • toHex

      public String toHex()
      The hex form of an RGB color, upper case with alpha, e.g. "#FFFF0000" for opaque red.
      Returns:
      "#AARRGGBB"
      Throws:
      IllegalStateException - if this is not an RGB color

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object