java.awt

Class Color

public class Color extends Object implements Paint, Serializable

This class represents a color value in the AWT system. It uses the sRGB (standard Red-Green-Blue) system, along with an alpha value ranging from transparent (0.0f or 0) and opaque (1.0f or 255). The color is not pre-multiplied by the alpha value an any of the accessor methods. Further information about sRGB can be found at http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html.

Since: 1.0

See Also: ColorSpace AlphaComposite

UNKNOWN: updated to 1.4

Field Summary
static Color	black Constant for the color black: R=0, G=0, B=0.
static Color	blue Constant for the color blue: R=0, G=0, B=255.
static Color	BLACK Constant for the color black: R=0, G=0, B=0.
static Color	BLUE Constant for the color blue: R=0, G=0, B=255.
static Color	cyan Constant for the color cyan: R=0, G=255, B=255.
static Color	CYAN Constant for the color cyan: R=0, G=255, B=255.
static Color	darkGray Constant for the color dark gray: R=64, G=64, B=64.
static Color	DARK_GRAY Constant for the color dark gray: R=64, G=64, B=64.
static Color	gray Constant for the color gray: R=128, G=128, B=128.
static Color	green Constant for the color green: R=0, G=255, B=0.
static Color	GRAY Constant for the color gray: R=128, G=128, B=128.
static Color	GREEN Constant for the color green: R=0, G=255, B=0.
static Color	lightGray Constant for the color light gray: R=192, G=192, B=192.
static Color	LIGHT_GRAY Constant for the color light gray: R=192, G=192, B=192.
static Color	magenta Constant for the color magenta: R=255, G=0, B=255.
static Color	MAGENTA Constant for the color magenta: R=255, G=0, B=255.
static Color	orange Constant for the color orange: R=255, G=200, B=0.
static Color	ORANGE Constant for the color orange: R=255, G=200, B=0.
static Color	pink Constant for the color pink: R=255, G=175, B=175.
static Color	PINK Constant for the color pink: R=255, G=175, B=175.
static Color	red Constant for the color red: R=255, G=0, B=0.
static Color	RED Constant for the color red: R=255, G=0, B=0.
static Color	white Constant for the color white: R=255, G=255, B=255.
static Color	WHITE Constant for the color white: R=255, G=255, B=255.
static Color	yellow Constant for the color yellow: R=255, G=255, B=0.
static Color	YELLOW Constant for the color yellow: R=255, G=255, B=0.

Constructor Summary
	Color(int red, int green, int blue) Initializes a new instance of `Color` using the specified red, green, and blue values, which must be given as integers in the range of 0-255.
	Color(int red, int green, int blue, int alpha) Initializes a new instance of `Color` using the specified red, green, blue, and alpha values, which must be given as integers in the range of 0-255.
	Color(int value) Initializes a new instance of `Color` using the specified RGB value.
	Color(int value, boolean hasalpha) Initializes a new instance of `Color` using the specified RGB value.
	Color(float red, float green, float blue) Initializes a new instance of `Color` using the specified RGB values.
	Color(float red, float green, float blue, float alpha) Initializes a new instance of `Color` using the specified RGB and alpha values.
	Color(ColorSpace space, float[] components, float alpha) Creates a color in the given ColorSpace with the specified alpha.

Method Summary
Color	brighter() Returns a brighter version of this color.
PaintContext	createContext(ColorModel cm, Rectangle deviceBounds, Rectangle2D userBounds, AffineTransform xform, RenderingHints hints) Returns a paint context, used for filling areas of a raster scan with this color.
Color	darker() Returns a darker version of this color.
static Color	decode(String str) Converts the specified string to a number, using Integer.decode, and creates a new instance of `Color` from the value.
boolean	equals(Object obj) Tests this object for equality against the specified object.
int	getAlpha() Returns the alpha value for this color, as an integer in the range 0-255.
int	getBlue() Returns the blue value for this color, as an integer in the range 0-255 in the sRGB color space.
static Color	getColor(String prop) Returns a new instance of `Color` from the value of the system property named by the specified string.
static Color	getColor(String prop, Color defcolor) Returns a new instance of `Color` from the value of the system property named by the specified string.
static Color	getColor(String prop, int defrgb) Returns a new instance of `Color` from the value of the system property named by the specified string.
float[]	getColorComponents(float[] array) Returns a float array containing the color components of this color in the ColorSpace it was created with (the constructors which do not take a ColorSpace parameter use a default sRGB ColorSpace).
float[]	getColorComponents(ColorSpace space, float[] array) Returns a float array containing the color components of this color in the given ColorSpace.
ColorSpace	getColorSpace() Returns the color space of this color.
float[]	getComponents(float[] array) Returns a float array containing the color and alpha components of this color in the ColorSpace it was created with (the constructors which do not take a ColorSpace parameter use a default sRGB ColorSpace).
float[]	getComponents(ColorSpace space, float[] array) Returns a float array containing the color and alpha components of this color in the given ColorSpace.
int	getGreen() Returns the green value for this color, as an integer in the range 0-255 in the sRGB color space.
static Color	getHSBColor(float hue, float saturation, float brightness) Returns a new instance of `Color` based on the specified HSB values.
int	getRed() Returns the red value for this color, as an integer in the range 0-255 in the sRGB color space.
int	getRGB() Returns the RGB value for this color, in the sRGB color space.
float[]	getRGBColorComponents(float[] array) Returns a float array with the red, green, and blue components, in the default sRGB space, with values in the range 0.0-1.0.
float[]	getRGBComponents(float[] array) Returns a float array with the red, green, and blue components, and the alpha value, in the default sRGB space, with values in the range 0.0-1.0.
int	getTransparency() Returns the transparency level of this color.
int	hashCode() Returns a hash value for this color.
static int	HSBtoRGB(float hue, float saturation, float brightness) Converts from the HSB (hue, saturation, brightness) color model to the RGB (red, green, blue) color model.
static float[]	RGBtoHSB(int red, int green, int blue, float[] array) Converts from the RGB (red, green, blue) color model to the HSB (hue, saturation, brightness) color model.
String	toString() Returns a string representation of this object.

Field Detail

black

public static final Color black

Constant for the color black: R=0, G=0, B=0.

blue

public static final Color blue

Constant for the color blue: R=0, G=0, B=255.

BLACK

public static final Color BLACK

Constant for the color black: R=0, G=0, B=0.

Since: 1.4

BLUE

public static final Color BLUE

Constant for the color blue: R=0, G=0, B=255.

Since: 1.4

cyan

public static final Color cyan

Constant for the color cyan: R=0, G=255, B=255.

CYAN

public static final Color CYAN

Constant for the color cyan: R=0, G=255, B=255.

Since: 1.4

darkGray

public static final Color darkGray

Constant for the color dark gray: R=64, G=64, B=64.

DARK_GRAY

public static final Color DARK_GRAY

Constant for the color dark gray: R=64, G=64, B=64.

Since: 1.4

gray

public static final Color gray

Constant for the color gray: R=128, G=128, B=128.

green

public static final Color green

Constant for the color green: R=0, G=255, B=0.

GRAY

public static final Color GRAY

Constant for the color gray: R=128, G=128, B=128.

Since: 1.4

GREEN

public static final Color GREEN

Constant for the color green: R=0, G=255, B=0.

Since: 1.4

lightGray

public static final Color lightGray

Constant for the color light gray: R=192, G=192, B=192.

LIGHT_GRAY

public static final Color LIGHT_GRAY

Constant for the color light gray: R=192, G=192, B=192.

Since: 1.4

magenta

public static final Color magenta

Constant for the color magenta: R=255, G=0, B=255.

MAGENTA

public static final Color MAGENTA

Constant for the color magenta: R=255, G=0, B=255.

Since: 1.4

orange

public static final Color orange

Constant for the color orange: R=255, G=200, B=0.

ORANGE

public static final Color ORANGE

Constant for the color orange: R=255, G=200, B=0.

Since: 1.4

pink

public static final Color pink

Constant for the color pink: R=255, G=175, B=175.

PINK

public static final Color PINK

Constant for the color pink: R=255, G=175, B=175.

Since: 1.4

red

public static final Color red

Constant for the color red: R=255, G=0, B=0.

RED

public static final Color RED

Constant for the color red: R=255, G=0, B=0.

Since: 1.4

white

public static final Color white

Constant for the color white: R=255, G=255, B=255.

WHITE

public static final Color WHITE

Constant for the color white: R=255, G=255, B=255.

Since: 1.4

yellow

public static final Color yellow

Constant for the color yellow: R=255, G=255, B=0.

YELLOW

public static final Color YELLOW

Constant for the color yellow: R=255, G=255, B=0.

Since: 1.4

Constructor Detail

Color

public Color(int red, int green, int blue)

Initializes a new instance of Color using the specified red, green, and blue values, which must be given as integers in the range of 0-255. Alpha will default to 255 (opaque). When drawing to screen, the actual color may be adjusted to the best match of hardware capabilities.

Parameters: red the red component of the RGB value green the green component of the RGB value blue the blue component of the RGB value

Throws: IllegalArgumentException if the values are out of range 0-255

See Also: getRed getGreen getBlue getRGB Color

Color

public Color(int red, int green, int blue, int alpha)

Initializes a new instance of Color using the specified red, green, blue, and alpha values, which must be given as integers in the range of 0-255. When drawing to screen, the actual color may be adjusted to the best match of hardware capabilities.

Parameters: red the red component of the RGB value green the green component of the RGB value blue the blue component of the RGB value alpha the alpha value of the color

Throws: IllegalArgumentException if the values are out of range 0-255

Color

public Color(int value)

Initializes a new instance of Color using the specified RGB value. The blue value is in bits 0-7, green in bits 8-15, and red in bits 16-23. The other bits are ignored. The alpha value is set to 255 (opaque). When drawing to screen, the actual color may be adjusted to the best match of hardware capabilities.

Parameters: value the RGB value

Color

public Color(int value, boolean hasalpha)

Initializes a new instance of Color using the specified RGB value. The blue value is in bits 0-7, green in bits 8-15, and red in bits 16-23. The alpha value is in bits 24-31, unless hasalpha is false, in which case alpha is set to 255. When drawing to screen, the actual color may be adjusted to the best match of hardware capabilities.

Parameters: value the RGB value hasalpha true if value includes the alpha

Color

public Color(float red, float green, float blue)

Initializes a new instance of Color using the specified RGB values. These must be in the range of 0.0-1.0. Alpha is assigned the value of 1.0 (opaque). When drawing to screen, the actual color may be adjusted to the best match of hardware capabilities.

Parameters: red the red component of the RGB value green the green component of the RGB value blue the blue component of the RGB value

Throws: IllegalArgumentException tf the values are out of range 0.0f-1.0f

See Also: getRed getGreen getBlue getRGB Color

Color

public Color(float red, float green, float blue, float alpha)

Initializes a new instance of Color using the specified RGB and alpha values. These must be in the range of 0.0-1.0. When drawing to screen, the actual color may be adjusted to the best match of hardware capabilities.

Parameters: red the red component of the RGB value green the green component of the RGB value blue the blue component of the RGB value alpha the alpha value of the color

Throws: IllegalArgumentException tf the values are out of range 0.0f-1.0f

Color

public Color(ColorSpace space, float[] components, float alpha)

Creates a color in the given ColorSpace with the specified alpha. The array must be non-null and have enough elements for the color space (for example, RGB requires 3 elements, CMYK requires 4). When drawing to screen, the actual color may be adjusted to the best match of hardware capabilities.

Parameters: space the color space of components components the color components, except alpha alpha the alpha value of the color

Throws: NullPointerException if cpsace or components is null ArrayIndexOutOfBoundsException if components is too small IllegalArgumentException if alpha or any component is out of range

Method Detail

brighter

public Color brighter()

Returns a brighter version of this color. This is done by increasing the RGB values by an arbitrary scale factor. The new color is opaque (an alpha of 255). Note that this method and the darker() method are not necessarily inverses.

Returns: a brighter version of this color

createContext

public PaintContext createContext(ColorModel cm, Rectangle deviceBounds, Rectangle2D userBounds, AffineTransform xform, RenderingHints hints)

Returns a paint context, used for filling areas of a raster scan with this color. Since the color is constant across the entire rectangle, and since it is always in sRGB space, this implementation returns the same object, regardless of the parameters. Subclasses, however, may have a mutable result.

Parameters: cm the requested color model deviceBounds the bounding box in device coordinates, ignored userBounds the bounding box in user coordinates, ignored xform the bounds transformation, ignored hints any rendering hints, ignored

Returns: a context for painting this solid color

darker

public Color darker()

Returns a darker version of this color. This is done by decreasing the RGB values by an arbitrary scale factor. The new color is opaque (an alpha of 255). Note that this method and the brighter() method are not necessarily inverses.

Returns: a darker version of this color

decode

public static Color decode(String str)

Converts the specified string to a number, using Integer.decode, and creates a new instance of Color from the value. The alpha value will be 255 (opaque).

Parameters: str the numeric color string

Returns: a new instance of Color for the string

Throws: NumberFormatException if the string cannot be parsed NullPointerException if the string is null

Since: 1.1

equals

public boolean equals(Object obj)

Tests this object for equality against the specified object. This will be true if and only if the specified object is an instance of Color and has the same 8-bit integer red, green, and blue values as this object. Note that two colors may be slightly different as float values, but round to the same integer values. Also note that this does not accurately compare SystemColors, since that class does not store its internal data in RGB format like regular colors.

Parameters: obj the object to compare to

Returns: true if the specified object is semantically equal to this one

getAlpha

public int getAlpha()

Returns the alpha value for this color, as an integer in the range 0-255.

Returns: the alpha value for this color

See Also: getRGB

getBlue

public int getBlue()

Returns the blue value for this color, as an integer in the range 0-255 in the sRGB color space.

Returns: the blue value for this color

See Also: getRGB

getColor

public static Color getColor(String prop)

Returns a new instance of Color from the value of the system property named by the specified string. If the property does not exist, or cannot be parsed, then null will be returned.

Parameters: prop the system property to retrieve

Throws: SecurityException if getting the property is denied

getColor

public static Color getColor(String prop, Color defcolor)

Returns a new instance of Color from the value of the system property named by the specified string. If the property does not exist, or cannot be parsed, then the default color value will be returned.

Parameters: prop the system property to retrieve defcolor the default color

Throws: SecurityException if getting the property is denied

getColor

public static Color getColor(String prop, int defrgb)

Returns a new instance of Color from the value of the system property named by the specified string. If the property does not exist, or cannot be parsed, then the default RGB value will be used to create a return value.

Parameters: prop the system property to retrieve defrgb the default RGB value

Throws: SecurityException if getting the property is denied

getColorComponents

public float[] getColorComponents(float[] array)

Returns a float array containing the color components of this color in the ColorSpace it was created with (the constructors which do not take a ColorSpace parameter use a default sRGB ColorSpace). If the array is null, a new one is created, otherwise it is recycled, and must have at least as many positions as used in the color space.

Parameters: array the array to put results into, or null

Returns: the original color space components

Throws: ArrayIndexOutOfBoundsException if array is too small

getColorComponents

public float[] getColorComponents(ColorSpace space, float[] array)

Returns a float array containing the color components of this color in the given ColorSpace. If the array is null, a new one is created, otherwise it is recycled, and must have at least as many positions as used in the color space.

Parameters: space the color space to translate to

Returns: the color space components

Throws: ArrayIndexOutOfBoundsException if array is too small NullPointerException if space is null

getColorSpace

public ColorSpace getColorSpace()

Returns the color space of this color. Except for the constructor which takes a ColorSpace argument, this will be an implementation of ColorSpace.CS_sRGB.

Returns: the color space

getComponents

public float[] getComponents(float[] array)

Returns a float array containing the color and alpha components of this color in the ColorSpace it was created with (the constructors which do not take a ColorSpace parameter use a default sRGB ColorSpace). If the array is null, a new one is created, otherwise it is recycled, and must have at least one more position than components used in the color space.

Parameters: array the array to put results into, or null

Returns: the original color space components and alpha value

Throws: ArrayIndexOutOfBoundsException if array is too small

getComponents

public float[] getComponents(ColorSpace space, float[] array)

Returns a float array containing the color and alpha components of this color in the given ColorSpace. If the array is null, a new one is created, otherwise it is recycled, and must have at least one more position than components used in the color space.

Parameters: space the color space to translate to array the array to put results into, or null

Returns: the color space components and alpha value

Throws: ArrayIndexOutOfBoundsException if array is too small NullPointerException if space is null

getGreen

public int getGreen()

Returns the green value for this color, as an integer in the range 0-255 in the sRGB color space.

Returns: the green value for this color

See Also: getRGB

getHSBColor

public static Color getHSBColor(float hue, float saturation, float brightness)

Returns a new instance of Color based on the specified HSB values. The hue may be any floating point; it's fractional portion is used to select the angle in the HSB model. The saturation and brightness must be between 0 and 1.

Parameters: hue the hue of the HSB value saturation the saturation of the HSB value brightness the brightness of the HSB value

Returns: the new Color object

getRed

public int getRed()

Returns the red value for this color, as an integer in the range 0-255 in the sRGB color space.

Returns: the red value for this color

See Also: getRGB

getRGB

public int getRGB()

Returns the RGB value for this color, in the sRGB color space. The blue value will be in bits 0-7, green in 8-15, red in 16-23, and alpha value in 24-31.

Returns: the RGB value for this color

getRGBColorComponents

public float[] getRGBColorComponents(float[] array)

Returns a float array with the red, green, and blue components, in the default sRGB space, with values in the range 0.0-1.0. If the array is null, a new one is created, otherwise it is recycled.

Parameters: array the array to put results into (at least 3 elements), or null

Returns: the RGB components

Throws: ArrayIndexOutOfBoundsException if array is too small

getRGBComponents

public float[] getRGBComponents(float[] array)

Returns a float array with the red, green, and blue components, and the alpha value, in the default sRGB space, with values in the range 0.0-1.0. If the array is null, a new one is created, otherwise it is recycled.

Parameters: array the array to put results into (at least 4 elements), or null

Returns: the RGB components and alpha value

Throws: ArrayIndexOutOfBoundsException if array is too small

getTransparency

public int getTransparency()

Returns the transparency level of this color.

Returns: one of {@link #OPAQUE}, {@link #BITMASK}, or {@link #TRANSLUCENT}

hashCode

public int hashCode()

Returns a hash value for this color. This is simply the color in 8-bit precision, in the format 0xAARRGGBB (alpha, red, green, blue).

Returns: a hash value for this color

HSBtoRGB

public static int HSBtoRGB(float hue, float saturation, float brightness)

Converts from the HSB (hue, saturation, brightness) color model to the RGB (red, green, blue) color model. The hue may be any floating point; it's fractional portion is used to select the angle in the HSB model. The saturation and brightness must be between 0 and 1. The result is suitable for creating an RGB color with the one-argument constructor.

Parameters: hue the hue of the HSB value saturation the saturation of the HSB value brightness the brightness of the HSB value

Returns: the RGB value

RGBtoHSB

public static float[] RGBtoHSB(int red, int green, int blue, float[] array)

Converts from the RGB (red, green, blue) color model to the HSB (hue, saturation, brightness) color model. If the array is null, a new one is created, otherwise it is recycled. The results will be in the range 0.0-1.0 if the inputs are in the range 0-255.

Parameters: red the red part of the RGB value green the green part of the RGB value blue the blue part of the RGB value array an array for the result (at least 3 elements), or null

Returns: the array containing HSB value

Throws: ArrayIndexOutOfBoundsException of array is too small

toString

public String toString()

Returns a string representation of this object. Subclasses may return any desired format, except for null, but this implementation returns

getClass().getName() + "[r=" + getRed() + ",g=" + getGreen()
 + ",b=" + getBlue() + ']'

Returns: a string representation of this object