Initial check-in

[dygraphs.git] / mochikit_v14 / doc / rst / MochiKit / Color.rst

.. title:: MochiKit.Color - color abstraction with CSS3 support

Name
====

MochiKit.Color - color abstraction with CSS3 support


Synopsis
========

::

    // RGB color expressions are supported
    assert(
        objEqual(Color.whiteColor(), Color.fromString("rgb(255,100%, 255)"))
    );

    // So is instantiating directly from HSL or RGB values.
    // Note that fromRGB and fromHSL take numbers between 0.0 and 1.0!
    assert( objEqual(Color.fromRGB(1.0, 1.0, 1.0), Color.fromHSL(0.0, 0.0, 1.0) );

    // Or even SVG color keyword names, as per CSS3!
    assert( Color.fromString("aquamarine"), "#7fffd4" );

    // NSColor-like colors built in
    assert( Color.whiteColor().toHexString() == "#ffffff" );


Description
===========

MochiKit.Color is an abstraction for handling colors and strings that
represent colors.


Dependencies
============

- :mochiref:`MochiKit.Base`
- :mochiref:`MochiKit.DOM`
- :mochiref:`MochiKit.Style`


Overview
========

MochiKit.Color provides an abstraction of RGB, HSL and HSV colors with
alpha.  It supports parsing and generating of CSS3 colors, and has a
full CSS3 (SVG) color table.

All of the functionality in this module is exposed through a Color
constructor and its prototype, but a few of its internals are
available for direct use at module level.


API Reference
=============

Constructors
------------

:mochidef:`Color()`:

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

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

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.fromBackground(elem)`:

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

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.fromComputedStyle(elem, style)`:

    Returns a :mochiref:`Color` object based on the result of
    :mochiref:`MochiKit.Style.getStyle(elem, style)` or ``null`` if not 
    found.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.fromHexString(hexString)`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


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

    Return a :mochiref:`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:
        :mochiref:`Color.fromHSL({h: hue, s: saturation, l: lightness,
        a: alpha})`

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.fromHSLString(hslString)`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


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

    Return a :mochiref:`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:
        :mochiref:`Color.fromHSV({h: hue, s: saturation, v: value, a:
        alpha})`

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.fromName(colorName)`:

    Returns a :mochiref:`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 :mochiref:`Color.transparentColor()`.

    *Availability*:
        Available in MochiKit 1.3.1+


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

    Return a :mochiref:`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:
        :mochiref:`Color.fromRGB({r: red, g: green, b: blue, a:
        alpha})`

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.fromRGBString(rgbString)`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.fromText(elem)`:

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

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.fromString(rgbOrHexString)`:

    Returns a :mochiref:`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 :mochiref:`Color.fromHexString`,
    :mochiref:`Color.fromRGBString`, :mochiref:`Color.fromHSLString`
    and :mochiref:`Color.fromName` more information.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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
    :mochiref:`Color.fromString()`.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.prototype.colorWithAlpha(alpha)`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.prototype.colorWithHue(hue)`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.prototype.colorWithSaturation(saturation)`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.prototype.colorWithLightness(lightness)`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.prototype.darkerColorWithLevel(level)`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.prototype.lighterColorWithLevel(level)`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


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

    Return a new :mochiref:`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.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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).

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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).

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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)" );

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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)" );

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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" );

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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``.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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``.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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``.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.blackColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.blueColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.brownColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.cyanColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.darkGrayColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.grayColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.greenColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.lightGrayColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.magentaColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.orangeColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.purpleColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.redColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.whiteColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.yellowColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Color.transparentColor()`:

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

    *Availability*:
        Available in MochiKit 1.3.1+


Functions
---------

:mochidef:`clampColorComponent(num, scale)`:

    Returns ``num * scale`` clamped between ``0`` and ``scale``.

    :mochiref:`clampColorComponent` is not exported by default when
    using JSAN.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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:
        :mochiref:`hslToRGB({h: hue, s: saturation, l: lightness, a:
        alpha})`.

    :mochiref:`hslToRGB` is not exported by default when using JSAN.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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:
        :mochiref:`hsvToRGB({h: hue, s: saturation, v: value, a:
        alpha})`.

    :mochiref:`hsvToRGB` is not exported by default when using JSAN.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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``.

    :mochiref:`toColorPart` is not exported by default when using
    JSAN.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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:
        :mochiref:`rgbToHSL({r: red, g: green, b: blue, a: alpha})`.

    :mochiref:`rgbToHSL` is not exported by default when using JSAN.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`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:
        :mochiref:`rgbToHSV({r: red, g: green, b: blue, a: alpha})`.

    :mochiref:`rgbToHSV` is not exported by default when using JSAN.

    *Availability*:
        Available in MochiKit 1.3.1+


See Also
========

.. [1] Application Kit Reference - NSColor: http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSColor.html
.. [2] SVG 1.0 color keywords: http://www.w3.org/TR/SVG/types.html#ColorKeywords
.. [3] W3C CSS3 Color Module: http://www.w3.org/TR/css3-color/#svg-color


Authors
=======

- Bob Ippolito <bob@redivi.com>


Copyright
=========

Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is
dual-licensed free software; you can redistribute it and/or modify it
under the terms of the `MIT License`_ or the `Academic Free License
v2.1`_.

.. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
.. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php