facets.util.shade
Class Shade

java.lang.Object
  facets.util.shade.Shade

All Implemented Interfaces:

Identified, Titled, java.io.Serializable, java.lang.Comparable

public final class Shade
extends java.lang.Object
implements java.io.Serializable, Identified, Titled, java.lang.Comparable

Named abstract colour.

Shade defines an immutable 24-bit RGB colour that is guaranteed to have a human-readable name. Methods mostly return properties in RGB and HSB terms, and new shades of the colour.

See Also:

Serialized Form

Field Summary

static int	B Index into values array.
static double	FACTOR_B Brightening/darkening factor.
static int	G Index into values array.
static int	H Index into values array.
static int	R Index into values array.
static int	S Index into values array.
static double	THRESHOLD_B HSB threshold value
static double	THRESHOLD_S HSB threshold value
static java.lang.String	TITLE_CUSTOM Default title for custom shades.

Constructor Summary

Shade(double[] hsb, java.lang.String title)
Convenience constructor accepting HSB values.

Shade(int rgb, java.lang.String title)
Core constructor.

Method Summary

Shade	brighter() Creates a brighter version of the shade.
int	compareTo(java.lang.Object o) Compares the rgb values of two shades.
Shade	darker() Creates a darker version of the shade.
boolean	equals(java.lang.Object o) Checks the rgb values of two shades.
int	hashCode() Returns the rgb value.
java.lang.Object	identity() Return an object that is as far as possible unique for the implementation.
boolean	isBright() True if HSB brightness is higher than THRESHOLD_B.
boolean	isSaturated() True if HSB saturation is higher than THRESHOLD_S.
Shade	resaturated(boolean saturated) Creates a new version of the shade with HSB saturation of either 1.0 or below THRESHOLD_S.
int	rgb() The 24-bit RGB value for the shade.
void	setTitle(java.lang.String title)
int	snapRGB(int bitLength) The RGB color value to a specified reduced accuracy.
java.lang.String	title() The title passed to the constructor.
java.lang.String	toString()
double[]	valuesHSB() The HSB description of the shade.
int[]	valuesRGB() The RGB components of the shade.

Methods inherited from class java.lang.Object

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

Field Detail

H

public static final int H

Index into values array.

See Also:

Constant Field Values

S

public static final int S

Index into values array.

See Also:

Constant Field Values

B

public static final int B

Index into values array.

See Also:

Constant Field Values

R

public static final int R

Index into values array.

See Also:

Constant Field Values

G

public static final int G

Index into values array.

See Also:

Constant Field Values

TITLE_CUSTOM

public static final java.lang.String TITLE_CUSTOM

Default title for custom shades.

See Also:

Constant Field Values

FACTOR_B

public static final double FACTOR_B

Brightening/darkening factor.

See Also:

Constant Field Values

THRESHOLD_S

public static final double THRESHOLD_S

HSB threshold value

See Also:

Constant Field Values

THRESHOLD_B

public static final double THRESHOLD_B

HSB threshold value

See Also:

Constant Field Values

Constructor Detail

Shade

public Shade(double[] hsb,
             java.lang.String title)

Convenience constructor accepting HSB values.

Parameters:

hsb - is converted to RGB equivalent

title - is passed to core constructor

Shade

public Shade(int rgb,
             java.lang.String title)

Core constructor.

Parameters:

rgb - is interpreted as a 24-bit RGB color value.

title - must be non-null and conform to the contract of Titled.

Method Detail

rgb

public int rgb()

The 24-bit RGB value for the shade.

title

public java.lang.String title()

The title passed to the constructor.

If the shade was created using a newXXXed method, the title will be TITLE_CUSTOM (which can be used for any 'anonymous' shade).

Note that the title does not form part of the shade's identity. Different shades can share a title (especially TITLE_CUSTOM); different titles may be returned by shades for which equals returns true.

Specified by:

title in interface Titled

Returns:

non-null, non-empty string with no structural whitespace

isBright

public boolean isBright()

True if HSB brightness is higher than THRESHOLD_B.

brighter

public Shade brighter()

Creates a brighter version of the shade.

HSB brightness will be higher than the source shade by FACTOR_B, up to a maximum of 1.0. Title will be TITLE_CUSTOM).

darker

public Shade darker()

Creates a darker version of the shade.

HSB brightness will be lower than the source shade by 1/FACTOR_B. Title will be TITLE_CUSTOM).

isSaturated

public boolean isSaturated()

True if HSB saturation is higher than THRESHOLD_S.

resaturated

public Shade resaturated(boolean saturated)

Creates a new version of the shade with HSB saturation of either 1.0 or below THRESHOLD_S.

Parameters:

saturated - switches saturation on if true

valuesRGB

public int[] valuesRGB()

The RGB components of the shade.

Returned as an int[3] with values in range 0 to 255.

valuesHSB

public double[] valuesHSB()

The HSB description of the shade.

Returned as a double[3] with values in range 0.0 to 1.0.

snapRGB

public int snapRGB(int bitLength)

The RGB color value to a specified reduced accuracy.

Components are truncated to fit the complete value within bitLength. So-called because its intended use is to determine whether one shade can reasonably be 'snapped' to another.

Parameters:

bitLength - the bit length to be used; must be divisible by 3

compareTo

public int compareTo(java.lang.Object o)

Compares the rgb values of two shades.

Note that title is ignored.

Specified by:

compareTo in interface java.lang.Comparable

equals

public boolean equals(java.lang.Object o)

Checks the rgb values of two shades.

Note that title is ignored.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Returns the rgb value.

Note that title is ignored.

Overrides:

hashCode in class java.lang.Object

identity

public java.lang.Object identity()

Description copied from interface: Identified

Return an object that is as far as possible unique for the implementation.

This will usually be a class instance counter.

Specified by:

identity in interface Identified

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

setTitle

public final void setTitle(java.lang.String title)