ColorWithAlternatives
Date: 2016-04-28

org.apache.xmlgraphics.java2d.color

## Class ColorWithAlternatives

- java.lang.Object
- - java.awt.Color
  - - org.apache.xmlgraphics.java2d.color.ColorWithAlternatives

- All Implemented Interfaces:
    java.awt.Paint, java.awt.Transparency, java.io.Serializable

      public class ColorWithAlternatives
      extends java.awt.Color

  Extended `Color` class allowing to specify a prioritized list of alternative colors. The alternative colors shall be the ones that are preferred if an output format supports them. This is normally used for passing device-specific colors through to the output format.

  This class only adds a single reference to a color array which should not increase memory consumption by much if no alternative colors are specified.

  Important: Due to a flaw in `Color.equals(Object)`, the `equals()` method should not be used to compare two colors, especially when used to update the current color for some output format. `Color` only takes the sRGB values into account but not more the advanced facets of this class. Use `ColorUtil.isSameColor(Color, Color)` for such a check.

  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class java.awt.Color

      `black, BLACK, blue, BLUE, cyan, CYAN, DARK_GRAY, darkGray, gray, GRAY, green, GREEN, LIGHT_GRAY, lightGray, magenta, MAGENTA, orange, ORANGE, pink, PINK, red, RED, white, WHITE, yellow, YELLOW`

    - ### Fields inherited from interface java.awt.Transparency

      `BITMASK, OPAQUE, TRANSLUCENT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ColorWithAlternatives(java.awt.color.ColorSpace cspace, float[] components, float alpha, java.awt.Color[] alternativeColors)` Constructor for colors with an arbitrary color space.
    `ColorWithAlternatives(float r, float g, float b, java.awt.Color[] alternativeColors)` Constructor for RGB colors.
    `ColorWithAlternatives(float r, float g, float b, float a, java.awt.Color[] alternativeColors)` Constructor for RGBA colors.
    `ColorWithAlternatives(int rgba, boolean hasalpha, java.awt.Color[] alternativeColors)` Constructor for RGBA colors.
    `ColorWithAlternatives(int rgb, java.awt.Color[] alternativeColors)` Constructor for RGB colors.
    `ColorWithAlternatives(int r, int g, int b, java.awt.Color[] alternativeColors)` Constructor for RGB colors.
    `ColorWithAlternatives(int r, int g, int b, int a, java.awt.Color[] alternativeColors)` Constructor for RGBA colors.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.awt.Color[]` | `getAlternativeColors()` Returns the list of alternative colors.
    `java.awt.Color` | `getFirstAlternativeOfType(int colorSpaceType)` Returns the first alternative color found with the given color space type.
    `boolean` | `hasAlternativeColors()` Indicates whether alternative colors are available.
    `int` | `hashCode()`
    `boolean` | `hasSameAlternativeColors(ColorWithAlternatives col)` Indicates whether another instance has the same alternative colors.

    - ### Methods inherited from class java.awt.Color

      `brighter, createContext, darker, decode, equals, getAlpha, getBlue, getColor, getColor, getColor, getColorComponents, getColorComponents, getColorSpace, getComponents, getComponents, getGreen, getHSBColor, getRed, getRGB, getRGBColorComponents, getRGBComponents, getTransparency, HSBtoRGB, RGBtoHSB, toString`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ColorWithAlternatives

          public ColorWithAlternatives(float r,
                               float g,
                               float b,
                               float a,
                               java.awt.Color[] alternativeColors)

      Constructor for RGBA colors.
      Parameters:
        `r` - the red component
        `g` - the green component
        `b` - the blue component
        `a` - the alpha component
        `alternativeColors` - the prioritized list of alternative colors.
      See Also:
        `Color.Color(float, float, float, float)`

    - #### ColorWithAlternatives

          public ColorWithAlternatives(float r,
                               float g,
                               float b,
                               java.awt.Color[] alternativeColors)

      Constructor for RGB colors.
      Parameters:
        `r` - the red component
        `g` - the green component
        `b` - the blue component
        `alternativeColors` - the prioritized list of alternative colors.
      See Also:
        `Color.Color(float, float, float)`

    - #### ColorWithAlternatives

          public ColorWithAlternatives(int rgba,
                               boolean hasalpha,
                               java.awt.Color[] alternativeColors)

      Constructor for RGBA colors.
      Parameters:
        `rgba` - the combined RGBA value
        `hasalpha` - true if the alpha bits are valid, false otherwise
        `alternativeColors` - the prioritized list of alternative colors.
      See Also:
        `Color.Color(int, boolean)`

    - #### ColorWithAlternatives

          public ColorWithAlternatives(int r,
                               int g,
                               int b,
                               int a,
                               java.awt.Color[] alternativeColors)

      Constructor for RGBA colors.
      Parameters:
        `r` - the red component
        `g` - the green component
        `b` - the blue component
        `a` - the alpha component
        `alternativeColors` - the prioritized list of alternative colors.
      See Also:
        `Color.Color(int, int, int, int)`

    - #### ColorWithAlternatives

          public ColorWithAlternatives(int r,
                               int g,
                               int b,
                               java.awt.Color[] alternativeColors)

      Constructor for RGB colors.
      Parameters:
        `r` - the red component
        `g` - the green component
        `b` - the blue component
        `alternativeColors` - the prioritized list of alternative colors.
      See Also:
        `Color.Color(int, int, int)`

    - #### ColorWithAlternatives

          public ColorWithAlternatives(int rgb,
                               java.awt.Color[] alternativeColors)

      Constructor for RGB colors.
      Parameters:
        `rgb` - the combined RGB components
        `alternativeColors` - the prioritized list of alternative colors.
      See Also:
        `Color.Color(int)`

    - #### ColorWithAlternatives

          public ColorWithAlternatives(java.awt.color.ColorSpace cspace,
                               float[] components,
                               float alpha,
                               java.awt.Color[] alternativeColors)

      Constructor for colors with an arbitrary color space.
      Parameters:
        `cspace` - the color space
        `components` - the color components
        `alpha` - the alpha component
        `alternativeColors` - the prioritized list of alternative colors.
      See Also:
        `Color.Color(ColorSpace, float[], float)`

  - ### Method Detail

    - #### getAlternativeColors

          public java.awt.Color[] getAlternativeColors()

      Returns the list of alternative colors. An empty array will be returned if no alternative colors are available.
      Returns:
        the list of alternative colors

    - #### hasAlternativeColors

          public boolean hasAlternativeColors()

      Indicates whether alternative colors are available.
      Returns:
        true if alternative colors are available.

    - #### hasSameAlternativeColors

          public boolean hasSameAlternativeColors(ColorWithAlternatives col)

      Indicates whether another instance has the same alternative colors.
      Parameters:
        `col` - the color to compare the alternatives to
      Returns:
        true if the same alternative colors are present

    - #### getFirstAlternativeOfType

          public java.awt.Color getFirstAlternativeOfType(int colorSpaceType)

      Returns the first alternative color found with the given color space type.
      Parameters:
        `colorSpaceType` - the color space type (`ColorSpace`.TYPE_*).
      Returns:
        the requested alternative color or null, if no match was found

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.awt.Color`