Constructors

Color():

Represents a color. Component values should be integers between 0.0 and 1.0. You should use one of the Color factory functions such as Color.fromRGB, Color.fromHSL, etc. instead of constructing Color objects directly.

Color instances can be compared with MochiKit.Base.compare (though ordering is on RGB, so is not particularly meaningful except for equality), and the default toString implementation returns Color.prototype.toHexString().

Color instances are immutable, and much of the architecture is inspired by AppKit's NSColor [1]

Color.fromBackground(elem):

Returns a Color object based on the background of the provided element. Equivalent to:

c = Color.fromComputedStyle(
    elem, "backgroundColor", "background-color") || Color.whiteColor();

Color.fromComputedStyle(elem, style, mozillaEquivalentCSS):

Returns a Color object based on the result of MochiKit.DOM.computedStyle(elem, style, mozillaEquivalentCSS) or null if not found.

Color.fromHexString(hexString):

Returns a Color object from the given hexadecimal color string. For example, "#FFFFFF" would return a Color with RGB values [255/255, 255/255, 255/255] (white).

Color.fromHSL(hue, saturation, lightness, alpha=1.0):

Return a Color object from the given hue, saturation, lightness values. Values should be numbers between 0.0 and 1.0.

If alpha is not given, then 1.0 (completely opaque) will be used.

Alternate form:

Color.fromHSL({h: hue, s: saturation, l: lightness, a: alpha})

Color.fromHSLString(hslString):

Returns a Color object from the given decimal hsl color string. For example, "hsl(0,0%,100%)" would return a Color with HSL values [0/360, 0/360, 360/360] (white).

Color.fromHSV(hue, saturation, value, alpha=1.0):

Return a Color object from the given hue, saturation, value values. Values should be numbers between 0.0 and 1.0.

If alpha is not given, then 1.0 (completely opaque) will be used.

Alternate form:

Color.fromHSV({h: hue, s: saturation, v: value, a: alpha})

Color.fromName(colorName):

Returns a Color object corresponding to the given SVG 1.0 color keyword name [2] as per the W3C CSS3 Color Module [3]. "transparent" is also accepted as a color name, and will return Color.transparentColor().

Color.fromRGB(red, green, blue, alpha=1.0):

Return a Color object from the given red, green, blue, and alpha values. Values should be numbers between 0 and 1.0.

If alpha is not given, then 1.0 (completely opaque) will be used.

Alternate form:

Color.fromRGB({r: red, g: green, b: blue, a: alpha})

Color.fromRGBString(rgbString):

Returns a Color object from the given decimal rgb color string. For example, "rgb(255,255,255)" would return a Color with RGB values [255/255, 255/255, 255/255] (white).

Color.fromText(elem):

Returns a Color object based on the text color of the provided element. Equivalent to:

c = Color.fromComputedStyle(elem, "color") || Color.whiteColor();

Color.fromString(rgbOrHexString):

Returns a Color object from the given RGB, HSL, hex, or name. Will return null if the string can not be parsed by any of these methods.

See Color.fromHexString, Color.fromRGBString, Color.fromHSLString and Color.fromName more information.

Color.namedColors():

Returns an object with properties for each SVG 1.0 color keyword name [2] supported by CSS3 [3]. Property names are the color keyword name in lowercase, and the value is a string suitable for Color.fromString().

Color.prototype.colorWithAlpha(alpha):

Return a new Color based on this color, but with the provided alpha value.

Color.prototype.colorWithHue(hue):

Return a new Color based on this color, but with the provided hue value.

Color.prototype.colorWithSaturation(saturation):

Return a new Color based on this color, but with the provided saturation value (using the HSL color model).

Color.prototype.colorWithLightness(lightness):

Return a new Color based on this color, but with the provided lightness value.

Color.prototype.darkerColorWithLevel(level):

Return a new Color based on this color, but darker by the given level (between 0 and 1.0).

Color.prototype.lighterColorWithLevel(level):

Return a new Color based on this color, but lighter by the given level (between 0 and 1.0).

Color.prototype.blendedColor(other, fraction=0.5):

Return a new Color whose RGBA component values are a weighted sum of this color and other. Each component of the returned color is the fraction of other's value plus 1 - fraction of this color's.

Color.prototype.isLight():

Return true if the lightness value of this color is greater than 0.5.

Note that alpha is ignored for this calculation (color components are not premultiplied).

Color.prototype.isDark():

Return true if the lightness value of this color is less than or equal to 0.5.

Note that alpha is ignored for this calculation (color components are not premultiplied).

Color.prototype.toRGBString():

Return the decimal "rgb(red, green, blue)" string representation of this color.

If the alpha component is not 1.0 (fully opaque), the "rgba(red, green, blue, alpha)" string representation will be used.

For example:

assert( Color.whiteColor().toRGBString() == "rgb(255,255,255)" );

Color.prototype.toHSLString():

Return the decimal "hsl(hue, saturation, lightness)" string representation of this color.

If the alpha component is not 1.0 (fully opaque), the "hsla(hue, saturation, lightness, alpha)" string representation will be used.

For example:

assert( Color.whiteColor().toHSLString() == "hsl(0,0,360)" );

Color.prototype.toHexString():

Return the hexadecimal "#RRGGBB" string representation of this color.

Note that the alpha component is completely ignored for hexadecimal string representations!

For example:

assert( Color.whiteColor().toHexString() == "#FFFFFF" );

Color.prototype.asRGB():

Return the RGB (red, green, blue, alpha) components of this color as an object with r, g, b, and a properties that have values between 0.0 and 1.0.

Color.prototype.asHSL():

Return the HSL (hue, saturation, lightness, alpha) components of this color as an object with h, s, l and a properties that have values between 0.0 and 1.0.

Color.prototype.asHSV():

Return the HSV (hue, saturation, value, alpha) components of this color as an object with h, s, v and a properties that have values between 0.0 and 1.0.

Color.blackColor():

Return a Color object whose RGB values are 0, 0, 0 (#000000).

Color.blueColor():

Return a Color object whose RGB values are 0, 0, 1 (#0000ff).

Color.brownColor():

Return a Color object whose RGB values are 0.6, 0.4, 0.2 (#996633).

Color.cyanColor():

Return a Color object whose RGB values are 0, 1, 1 (#00ffff).

Color.darkGrayColor():

Return a Color object whose RGB values are 1/3, 1/3, 1/3 (#555555).

Color.grayColor():

Return a Color object whose RGB values are 0.5, 0.5, 0.5 (#808080).

Color.greenColor():

Return a Color object whose RGB values are 0, 1, 0. (#00ff00).

Color.lightGrayColor():

Return a Color object whose RGB values are 2/3, 2/3, 2/3 (#aaaaaa).

Color.magentaColor():

Return a Color object whose RGB values are 1, 0, 1 (#ff00ff).

Color.orangeColor():

Return a Color object whose RGB values are 1, 0.5, 0 (#ff8000).

Color.purpleColor():

Return a Color object whose RGB values are 0.5, 0, 0.5 (#800080).

Color.redColor():

Return a Color object whose RGB values are 1, 0, 0 (#ff0000).

Color.whiteColor():

Return a Color object whose RGB values are 1, 1, 1 (#ffffff).

Color.yellowColor():

Return a Color object whose RGB values are 1, 1, 0 (#ffff00).

Color.transparentColor():

Return a Color object that is completely transparent (has alpha component of 0).

Functions

clampColorComponent(num, scale):

Returns num * scale clamped between 0 and scale.

clampColorComponent is not exported by default when using JSAN.

hslToRGB(hue, saturation, lightness, alpha):

Computes RGB values from the provided HSL values. The return value is a mapping with "r", "g", "b" and "a" keys.

Alternate form:

hslToRGB({h: hue, s: saturation, l: lightness, a: alpha}).

hslToRGB is not exported by default when using JSAN.

hsvToRGB(hue, saturation, value, alpha):

Computes RGB values from the provided HSV values. The return value is a mapping with "r", "g", "b" and "a" keys.

Alternate form:

hsvToRGB({h: hue, s: saturation, v: value, a: alpha}).

hsvToRGB is not exported by default when using JSAN.

toColorPart(num):

Convert num to a zero padded hexadecimal digit for use in a hexadecimal color string. Num should be an integer between 0 and 255.

toColorPart is not exported by default when using JSAN.

rgbToHSL(red, green, blue, alpha):

Computes HSL values based on the provided RGB values. The return value is a mapping with "h", "s", "l" and "a" keys.

Alternate form:

rgbToHSL({r: red, g: green, b: blue, a: alpha}).

rgbToHSL is not exported by default when using JSAN.

rgbToHSV(red, green, blue, alpha):

Computes HSV values based on the provided RGB values. The return value is a mapping with "h", "s", "v" and "a" keys.

Alternate form:

rgbToHSV({r: red, g: green, b: blue, a: alpha}).

rgbToHSV is not exported by default when using JSAN.