1 .. title:: MochiKit.Color - color abstraction with CSS3 support
6 MochiKit.Color - color abstraction with CSS3 support
14 // RGB color expressions are supported
16 objEqual(Color.whiteColor(), Color.fromString("rgb(255,100%, 255)"))
19 // So is instantiating directly from HSL or RGB values.
20 // Note that fromRGB and fromHSL take numbers between 0.0 and 1.0!
21 assert( objEqual(Color.fromRGB(1.0, 1.0, 1.0), Color.fromHSL(0.0, 0.0, 1.0) );
23 // Or even SVG color keyword names, as per CSS3!
24 assert( Color.fromString("aquamarine"), "#7fffd4" );
26 // NSColor-like colors built in
27 assert( Color.whiteColor().toHexString() == "#ffffff" );
33 MochiKit.Color is an abstraction for handling colors and strings that
40 - :mochiref:`MochiKit.Base`
41 - :mochiref:`MochiKit.DOM`
42 - :mochiref:`MochiKit.Style`
48 MochiKit.Color provides an abstraction of RGB, HSL and HSV colors with
49 alpha. It supports parsing and generating of CSS3 colors, and has a
50 full CSS3 (SVG) color table.
52 All of the functionality in this module is exposed through a Color
53 constructor and its prototype, but a few of its internals are
54 available for direct use at module level.
65 Represents a color. Component values should be integers between
66 ``0.0`` and ``1.0``. You should use one of the :mochiref:`Color`
67 factory functions such as :mochiref:`Color.fromRGB`,
68 :mochiref:`Color.fromHSL`, etc. instead of constructing
69 :mochiref:`Color` objects directly.
71 :mochiref:`Color` instances can be compared with
72 :mochiref:`MochiKit.Base.compare` (though ordering is on RGB, so
73 is not particularly meaningful except for equality), and the
74 default ``toString`` implementation returns
75 :mochiref:`Color.prototype.toHexString()`.
77 :mochiref:`Color` instances are immutable, and much of the
78 architecture is inspired by AppKit's NSColor [1]_
81 Available in MochiKit 1.3.1+
84 :mochidef:`Color.fromBackground(elem)`:
86 Returns a :mochiref:`Color` object based on the background of the
87 provided element. Equivalent to::
89 c = Color.fromComputedStyle(
90 elem, "backgroundColor", "background-color") || Color.whiteColor();
93 Available in MochiKit 1.3.1+
96 :mochidef:`Color.fromComputedStyle(elem, style)`:
98 Returns a :mochiref:`Color` object based on the result of
99 :mochiref:`MochiKit.Style.getStyle(elem, style)` or ``null`` if not
103 Available in MochiKit 1.3.1+
106 :mochidef:`Color.fromHexString(hexString)`:
108 Returns a :mochiref:`Color` object from the given hexadecimal
109 color string. For example, ``"#FFFFFF"`` would return a
110 :mochiref:`Color` with RGB values ``[255/255, 255/255, 255/255]``
114 Available in MochiKit 1.3.1+
117 :mochidef:`Color.fromHSL(hue, saturation, lightness, alpha=1.0)`:
119 Return a :mochiref:`Color` object from the given ``hue``,
120 ``saturation``, ``lightness`` values. Values should be numbers
121 between ``0.0`` and ``1.0``.
123 If ``alpha`` is not given, then ``1.0`` (completely opaque) will
127 :mochiref:`Color.fromHSL({h: hue, s: saturation, l: lightness,
131 Available in MochiKit 1.3.1+
134 :mochidef:`Color.fromHSLString(hslString)`:
136 Returns a :mochiref:`Color` object from the given decimal hsl
137 color string. For example, ``"hsl(0,0%,100%)"`` would return a
138 :mochiref:`Color` with HSL values ``[0/360, 0/360, 360/360]``
142 Available in MochiKit 1.3.1+
145 :mochidef:`Color.fromHSV(hue, saturation, value, alpha=1.0)`:
147 Return a :mochiref:`Color` object from the given ``hue``,
148 ``saturation``, ``value`` values. Values should be numbers between
151 If ``alpha`` is not given, then ``1.0`` (completely opaque) will
155 :mochiref:`Color.fromHSV({h: hue, s: saturation, v: value, a:
159 Available in MochiKit 1.3.1+
162 :mochidef:`Color.fromName(colorName)`:
164 Returns a :mochiref:`Color` object corresponding to the given SVG
165 1.0 color keyword name [2]_ as per the W3C CSS3 Color Module
166 [3]_. ``"transparent"`` is also accepted as a color name, and will
167 return :mochiref:`Color.transparentColor()`.
170 Available in MochiKit 1.3.1+
173 :mochidef:`Color.fromRGB(red, green, blue, alpha=1.0)`:
175 Return a :mochiref:`Color` object from the given ``red``,
176 ``green``, ``blue``, and ``alpha`` values. Values should be
177 numbers between ``0`` and ``1.0``.
179 If ``alpha`` is not given, then ``1.0`` (completely opaque) will
183 :mochiref:`Color.fromRGB({r: red, g: green, b: blue, a:
187 Available in MochiKit 1.3.1+
190 :mochidef:`Color.fromRGBString(rgbString)`:
192 Returns a :mochiref:`Color` object from the given decimal rgb
193 color string. For example, ``"rgb(255,255,255)"`` would return a
194 :mochiref:`Color` with RGB values ``[255/255, 255/255, 255/255]``
198 Available in MochiKit 1.3.1+
201 :mochidef:`Color.fromText(elem)`:
203 Returns a :mochiref:`Color` object based on the text color of the
204 provided element. Equivalent to::
206 c = Color.fromComputedStyle(elem, "color") || Color.whiteColor();
209 Available in MochiKit 1.3.1+
212 :mochidef:`Color.fromString(rgbOrHexString)`:
214 Returns a :mochiref:`Color` object from the given RGB, HSL, hex,
215 or name. Will return ``null`` if the string can not be parsed by
216 any of these methods.
218 See :mochiref:`Color.fromHexString`,
219 :mochiref:`Color.fromRGBString`, :mochiref:`Color.fromHSLString`
220 and :mochiref:`Color.fromName` more information.
223 Available in MochiKit 1.3.1+
226 :mochidef:`Color.namedColors()`:
228 Returns an object with properties for each SVG 1.0 color keyword
229 name [2]_ supported by CSS3 [3]_. Property names are the color
230 keyword name in lowercase, and the value is a string suitable for
231 :mochiref:`Color.fromString()`.
234 Available in MochiKit 1.3.1+
237 :mochidef:`Color.prototype.colorWithAlpha(alpha)`:
239 Return a new :mochiref:`Color` based on this color, but with the
240 provided ``alpha`` value.
243 Available in MochiKit 1.3.1+
246 :mochidef:`Color.prototype.colorWithHue(hue)`:
248 Return a new :mochiref:`Color` based on this color, but with the
249 provided ``hue`` value.
252 Available in MochiKit 1.3.1+
255 :mochidef:`Color.prototype.colorWithSaturation(saturation)`:
257 Return a new :mochiref:`Color` based on this color, but with the
258 provided ``saturation`` value (using the HSL color model).
261 Available in MochiKit 1.3.1+
264 :mochidef:`Color.prototype.colorWithLightness(lightness)`:
266 Return a new :mochiref:`Color` based on this color, but with the
267 provided ``lightness`` value.
270 Available in MochiKit 1.3.1+
273 :mochidef:`Color.prototype.darkerColorWithLevel(level)`:
275 Return a new :mochiref:`Color` based on this color, but darker by
276 the given ``level`` (between ``0`` and ``1.0``).
279 Available in MochiKit 1.3.1+
282 :mochidef:`Color.prototype.lighterColorWithLevel(level)`:
284 Return a new :mochiref:`Color` based on this color, but lighter by
285 the given ``level`` (between ``0`` and ``1.0``).
288 Available in MochiKit 1.3.1+
291 :mochidef:`Color.prototype.blendedColor(other, fraction=0.5)`:
293 Return a new :mochiref:`Color` whose RGBA component values are a
294 weighted sum of this color and ``other``. Each component of the
295 returned color is the ``fraction`` of other's value plus ``1 -
296 fraction`` of this color's.
299 Available in MochiKit 1.3.1+
302 :mochidef:`Color.prototype.isLight()`:
304 Return ``true`` if the lightness value of this color is greater
307 Note that ``alpha`` is ignored for this calculation (color
308 components are not premultiplied).
311 Available in MochiKit 1.3.1+
314 :mochidef:`Color.prototype.isDark()`:
316 Return ``true`` if the lightness value of this color is less than
319 Note that ``alpha`` is ignored for this calculation (color
320 components are not premultiplied).
323 Available in MochiKit 1.3.1+
326 :mochidef:`Color.prototype.toRGBString()`:
328 Return the decimal ``"rgb(red, green, blue)"`` string
329 representation of this color.
331 If the alpha component is not ``1.0`` (fully opaque), the
332 ``"rgba(red, green, blue, alpha)"`` string representation will be
337 assert( Color.whiteColor().toRGBString() == "rgb(255,255,255)" );
340 Available in MochiKit 1.3.1+
343 :mochidef:`Color.prototype.toHSLString()`:
345 Return the decimal ``"hsl(hue, saturation, lightness)"`` string
346 representation of this color.
348 If the alpha component is not ``1.0`` (fully opaque), the
349 ``"hsla(hue, saturation, lightness, alpha)"`` string
350 representation will be used.
354 assert( Color.whiteColor().toHSLString() == "hsl(0,0,360)" );
357 Available in MochiKit 1.3.1+
360 :mochidef:`Color.prototype.toHexString()`:
362 Return the hexadecimal ``"#RRGGBB"`` string representation of this
365 Note that the alpha component is completely ignored for
366 hexadecimal string representations!
370 assert( Color.whiteColor().toHexString() == "#FFFFFF" );
373 Available in MochiKit 1.3.1+
376 :mochidef:`Color.prototype.asRGB()`:
378 Return the RGB (red, green, blue, alpha) components of this color
379 as an object with ``r``, ``g``, ``b``, and ``a`` properties that
380 have values between ``0.0`` and ``1.0``.
383 Available in MochiKit 1.3.1+
386 :mochidef:`Color.prototype.asHSL()`:
388 Return the HSL (hue, saturation, lightness, alpha) components of
389 this color as an object with ``h``, ``s``, ``l`` and ``a``
390 properties that have values between ``0.0`` and ``1.0``.
393 Available in MochiKit 1.3.1+
396 :mochidef:`Color.prototype.asHSV()`:
398 Return the HSV (hue, saturation, value, alpha) components of this
399 color as an object with ``h``, ``s``, ``v`` and ``a`` properties
400 that have values between ``0.0`` and ``1.0``.
403 Available in MochiKit 1.3.1+
406 :mochidef:`Color.blackColor()`:
408 Return a :mochiref:`Color` object whose RGB values are 0, 0, 0
412 Available in MochiKit 1.3.1+
415 :mochidef:`Color.blueColor()`:
417 Return a :mochiref:`Color` object whose RGB values are 0, 0, 1
421 Available in MochiKit 1.3.1+
424 :mochidef:`Color.brownColor()`:
426 Return a :mochiref:`Color` object whose RGB values are 0.6, 0.4,
430 Available in MochiKit 1.3.1+
433 :mochidef:`Color.cyanColor()`:
435 Return a :mochiref:`Color` object whose RGB values are 0, 1, 1
439 Available in MochiKit 1.3.1+
442 :mochidef:`Color.darkGrayColor()`:
444 Return a :mochiref:`Color` object whose RGB values are 1/3, 1/3,
448 Available in MochiKit 1.3.1+
451 :mochidef:`Color.grayColor()`:
453 Return a :mochiref:`Color` object whose RGB values are 0.5, 0.5,
457 Available in MochiKit 1.3.1+
460 :mochidef:`Color.greenColor()`:
462 Return a :mochiref:`Color` object whose RGB values are 0, 1, 0.
466 Available in MochiKit 1.3.1+
469 :mochidef:`Color.lightGrayColor()`:
471 Return a :mochiref:`Color` object whose RGB values are 2/3, 2/3,
475 Available in MochiKit 1.3.1+
478 :mochidef:`Color.magentaColor()`:
480 Return a :mochiref:`Color` object whose RGB values are 1, 0, 1
484 Available in MochiKit 1.3.1+
487 :mochidef:`Color.orangeColor()`:
489 Return a :mochiref:`Color` object whose RGB values are 1, 0.5, 0
493 Available in MochiKit 1.3.1+
496 :mochidef:`Color.purpleColor()`:
498 Return a :mochiref:`Color` object whose RGB values are 0.5, 0, 0.5
502 Available in MochiKit 1.3.1+
505 :mochidef:`Color.redColor()`:
507 Return a :mochiref:`Color` object whose RGB values are 1, 0, 0
511 Available in MochiKit 1.3.1+
514 :mochidef:`Color.whiteColor()`:
516 Return a :mochiref:`Color` object whose RGB values are 1, 1, 1
520 Available in MochiKit 1.3.1+
523 :mochidef:`Color.yellowColor()`:
525 Return a :mochiref:`Color` object whose RGB values are 1, 1, 0
529 Available in MochiKit 1.3.1+
532 :mochidef:`Color.transparentColor()`:
534 Return a :mochiref:`Color` object that is completely transparent
535 (has alpha component of 0).
538 Available in MochiKit 1.3.1+
544 :mochidef:`clampColorComponent(num, scale)`:
546 Returns ``num * scale`` clamped between ``0`` and ``scale``.
548 :mochiref:`clampColorComponent` is not exported by default when
552 Available in MochiKit 1.3.1+
555 :mochidef:`hslToRGB(hue, saturation, lightness, alpha)`:
557 Computes RGB values from the provided HSL values. The return value
558 is a mapping with ``"r"``, ``"g"``, ``"b"`` and ``"a"`` keys.
561 :mochiref:`hslToRGB({h: hue, s: saturation, l: lightness, a:
564 :mochiref:`hslToRGB` is not exported by default when using JSAN.
567 Available in MochiKit 1.3.1+
570 :mochidef:`hsvToRGB(hue, saturation, value, alpha)`:
572 Computes RGB values from the provided HSV values. The return value
573 is a mapping with ``"r"``, ``"g"``, ``"b"`` and ``"a"`` keys.
576 :mochiref:`hsvToRGB({h: hue, s: saturation, v: value, a:
579 :mochiref:`hsvToRGB` is not exported by default when using JSAN.
582 Available in MochiKit 1.3.1+
585 :mochidef:`toColorPart(num)`:
587 Convert num to a zero padded hexadecimal digit for use in a
588 hexadecimal color string. Num should be an integer between ``0``
591 :mochiref:`toColorPart` is not exported by default when using
595 Available in MochiKit 1.3.1+
598 :mochidef:`rgbToHSL(red, green, blue, alpha)`:
600 Computes HSL values based on the provided RGB values. The return
601 value is a mapping with ``"h"``, ``"s"``, ``"l"`` and ``"a"``
605 :mochiref:`rgbToHSL({r: red, g: green, b: blue, a: alpha})`.
607 :mochiref:`rgbToHSL` is not exported by default when using JSAN.
610 Available in MochiKit 1.3.1+
613 :mochidef:`rgbToHSV(red, green, blue, alpha)`:
615 Computes HSV values based on the provided RGB values. The return
616 value is a mapping with ``"h"``, ``"s"``, ``"v"`` and ``"a"``
620 :mochiref:`rgbToHSV({r: red, g: green, b: blue, a: alpha})`.
622 :mochiref:`rgbToHSV` is not exported by default when using JSAN.
625 Available in MochiKit 1.3.1+
631 .. [1] Application Kit Reference - NSColor: http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSColor.html
632 .. [2] SVG 1.0 color keywords: http://www.w3.org/TR/SVG/types.html#ColorKeywords
633 .. [3] W3C CSS3 Color Module: http://www.w3.org/TR/css3-color/#svg-color
639 - Bob Ippolito <bob@redivi.com>
645 Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is
646 dual-licensed free software; you can redistribute it and/or modify it
647 under the terms of the `MIT License`_ or the `Academic Free License
650 .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
651 .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php