old_sql 1.12.0 → 1.13.0

data/public/javascripts/old_sql/MochiKit-1.4.2/doc/rst/MochiKit/Color.rst

@@ -0,0 +1,651 @@
+.. 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