mochikit_v14/doc/rst/MochiKit/Color.rst

   1 .. title:: MochiKit.Color - color abstraction with CSS3 support
   2
   3 Name
   4 ====
   5
   6 MochiKit.Color - color abstraction with CSS3 support
   7
   8
   9 Synopsis
  10 ========
  11
  12 ::
  13
  14     // RGB color expressions are supported
  15     assert(
  16         objEqual(Color.whiteColor(), Color.fromString("rgb(255,100%, 255)"))
  17     );
  18
  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) );
  22
  23     // Or even SVG color keyword names, as per CSS3!
  24     assert( Color.fromString("aquamarine"), "#7fffd4" );
  25
  26     // NSColor-like colors built in
  27     assert( Color.whiteColor().toHexString() == "#ffffff" );
  28
  29
  30 Description
  31 ===========
  32
  33 MochiKit.Color is an abstraction for handling colors and strings that
  34 represent colors.
  35
  36
  37 Dependencies
  38 ============
  39
  40 - :mochiref:`MochiKit.Base`
  41 - :mochiref:`MochiKit.DOM`
  42 - :mochiref:`MochiKit.Style`
  43
  44
  45 Overview
  46 ========
  47
  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.
  51
  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.
  55
  56
  57 API Reference
  58 =============
  59
  60 Constructors
  61 ------------
  62
  63 :mochidef:`Color()`:
  64
  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.
  70
  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()`.
  76
  77     :mochiref:`Color` instances are immutable, and much of the
  78     architecture is inspired by AppKit's NSColor [1]_
  79
  80     *Availability*:
  81         Available in MochiKit 1.3.1+
  82
  83
  84 :mochidef:`Color.fromBackground(elem)`:
  85
  86     Returns a :mochiref:`Color` object based on the background of the
  87     provided element. Equivalent to::
  88
  89         c = Color.fromComputedStyle(
  90             elem, "backgroundColor", "background-color") || Color.whiteColor();
  91
  92     *Availability*:
  93         Available in MochiKit 1.3.1+
  94
  95
  96 :mochidef:`Color.fromComputedStyle(elem, style)`:
  97
  98     Returns a :mochiref:`Color` object based on the result of
  99     :mochiref:`MochiKit.Style.getStyle(elem, style)` or ``null`` if not
 100     found.
 101
 102     *Availability*:
 103         Available in MochiKit 1.3.1+
 104
 105
 106 :mochidef:`Color.fromHexString(hexString)`:
 107
 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]``
 111     (white).
 112
 113     *Availability*:
 114         Available in MochiKit 1.3.1+
 115
 116
 117 :mochidef:`Color.fromHSL(hue, saturation, lightness, alpha=1.0)`:
 118
 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``.
 122
 123     If ``alpha`` is not given, then ``1.0`` (completely opaque) will
 124     be used.
 125
 126     Alternate form:
 127         :mochiref:`Color.fromHSL({h: hue, s: saturation, l: lightness,
 128         a: alpha})`
 129
 130     *Availability*:
 131         Available in MochiKit 1.3.1+
 132
 133
 134 :mochidef:`Color.fromHSLString(hslString)`:
 135
 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]``
 139     (white).
 140
 141     *Availability*:
 142         Available in MochiKit 1.3.1+
 143
 144
 145 :mochidef:`Color.fromHSV(hue, saturation, value, alpha=1.0)`:
 146
 147     Return a :mochiref:`Color` object from the given ``hue``,
 148     ``saturation``, ``value`` values. Values should be numbers between
 149     ``0.0`` and ``1.0``.
 150
 151     If ``alpha`` is not given, then ``1.0`` (completely opaque) will
 152     be used.
 153
 154     Alternate form:
 155         :mochiref:`Color.fromHSV({h: hue, s: saturation, v: value, a:
 156         alpha})`
 157
 158     *Availability*:
 159         Available in MochiKit 1.3.1+
 160
 161
 162 :mochidef:`Color.fromName(colorName)`:
 163
 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()`.
 168
 169     *Availability*:
 170         Available in MochiKit 1.3.1+
 171
 172
 173 :mochidef:`Color.fromRGB(red, green, blue, alpha=1.0)`:
 174
 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``.
 178
 179     If ``alpha`` is not given, then ``1.0`` (completely opaque) will
 180     be used.
 181
 182     Alternate form:
 183         :mochiref:`Color.fromRGB({r: red, g: green, b: blue, a:
 184         alpha})`
 185
 186     *Availability*:
 187         Available in MochiKit 1.3.1+
 188
 189
 190 :mochidef:`Color.fromRGBString(rgbString)`:
 191
 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]``
 195     (white).
 196
 197     *Availability*:
 198         Available in MochiKit 1.3.1+
 199
 200
 201 :mochidef:`Color.fromText(elem)`:
 202
 203     Returns a :mochiref:`Color` object based on the text color of the
 204     provided element. Equivalent to::
 205
 206         c = Color.fromComputedStyle(elem, "color") || Color.whiteColor();
 207
 208     *Availability*:
 209         Available in MochiKit 1.3.1+
 210
 211
 212 :mochidef:`Color.fromString(rgbOrHexString)`:
 213
 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.
 217
 218     See :mochiref:`Color.fromHexString`,
 219     :mochiref:`Color.fromRGBString`, :mochiref:`Color.fromHSLString`
 220     and :mochiref:`Color.fromName` more information.
 221
 222     *Availability*:
 223         Available in MochiKit 1.3.1+
 224
 225
 226 :mochidef:`Color.namedColors()`:
 227
 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()`.
 232
 233     *Availability*:
 234         Available in MochiKit 1.3.1+
 235
 236
 237 :mochidef:`Color.prototype.colorWithAlpha(alpha)`:
 238
 239     Return a new :mochiref:`Color` based on this color, but with the
 240     provided ``alpha`` value.
 241
 242     *Availability*:
 243         Available in MochiKit 1.3.1+
 244
 245
 246 :mochidef:`Color.prototype.colorWithHue(hue)`:
 247
 248     Return a new :mochiref:`Color` based on this color, but with the
 249     provided ``hue`` value.
 250
 251     *Availability*:
 252         Available in MochiKit 1.3.1+
 253
 254
 255 :mochidef:`Color.prototype.colorWithSaturation(saturation)`:
 256
 257     Return a new :mochiref:`Color` based on this color, but with the
 258     provided ``saturation`` value (using the HSL color model).
 259
 260     *Availability*:
 261         Available in MochiKit 1.3.1+
 262
 263
 264 :mochidef:`Color.prototype.colorWithLightness(lightness)`:
 265
 266     Return a new :mochiref:`Color` based on this color, but with the
 267     provided ``lightness`` value.
 268
 269     *Availability*:
 270         Available in MochiKit 1.3.1+
 271
 272
 273 :mochidef:`Color.prototype.darkerColorWithLevel(level)`:
 274
 275     Return a new :mochiref:`Color` based on this color, but darker by
 276     the given ``level`` (between ``0`` and ``1.0``).
 277
 278     *Availability*:
 279         Available in MochiKit 1.3.1+
 280
 281
 282 :mochidef:`Color.prototype.lighterColorWithLevel(level)`:
 283
 284     Return a new :mochiref:`Color` based on this color, but lighter by
 285     the given ``level`` (between ``0`` and ``1.0``).
 286
 287     *Availability*:
 288         Available in MochiKit 1.3.1+
 289
 290
 291 :mochidef:`Color.prototype.blendedColor(other, fraction=0.5)`:
 292
 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.
 297
 298     *Availability*:
 299         Available in MochiKit 1.3.1+
 300
 301
 302 :mochidef:`Color.prototype.isLight()`:
 303
 304     Return ``true`` if the lightness value of this color is greater
 305     than ``0.5``.
 306
 307     Note that ``alpha`` is ignored for this calculation (color
 308     components are not premultiplied).
 309
 310     *Availability*:
 311         Available in MochiKit 1.3.1+
 312
 313
 314 :mochidef:`Color.prototype.isDark()`:
 315
 316     Return ``true`` if the lightness value of this color is less than
 317     or equal to ``0.5``.
 318
 319     Note that ``alpha`` is ignored for this calculation (color
 320     components are not premultiplied).
 321
 322     *Availability*:
 323         Available in MochiKit 1.3.1+
 324
 325
 326 :mochidef:`Color.prototype.toRGBString()`:
 327
 328     Return the decimal ``"rgb(red, green, blue)"`` string
 329     representation of this color.
 330
 331     If the alpha component is not ``1.0`` (fully opaque), the
 332     ``"rgba(red, green, blue, alpha)"`` string representation will be
 333     used.
 334
 335     For example::
 336
 337         assert( Color.whiteColor().toRGBString() == "rgb(255,255,255)" );
 338
 339     *Availability*:
 340         Available in MochiKit 1.3.1+
 341
 342
 343 :mochidef:`Color.prototype.toHSLString()`:
 344
 345     Return the decimal ``"hsl(hue, saturation, lightness)"`` string
 346     representation of this color.
 347
 348     If the alpha component is not ``1.0`` (fully opaque), the
 349     ``"hsla(hue, saturation, lightness, alpha)"`` string
 350     representation will be used.
 351
 352     For example::
 353
 354         assert( Color.whiteColor().toHSLString() == "hsl(0,0,360)" );
 355
 356     *Availability*:
 357         Available in MochiKit 1.3.1+
 358
 359
 360 :mochidef:`Color.prototype.toHexString()`:
 361
 362     Return the hexadecimal ``"#RRGGBB"`` string representation of this
 363     color.
 364
 365     Note that the alpha component is completely ignored for
 366     hexadecimal string representations!
 367
 368     For example::
 369
 370         assert( Color.whiteColor().toHexString() == "#FFFFFF" );
 371
 372     *Availability*:
 373         Available in MochiKit 1.3.1+
 374
 375
 376 :mochidef:`Color.prototype.asRGB()`:
 377
 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``.
 381
 382     *Availability*:
 383         Available in MochiKit 1.3.1+
 384
 385
 386 :mochidef:`Color.prototype.asHSL()`:
 387
 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``.
 391
 392     *Availability*:
 393         Available in MochiKit 1.3.1+
 394
 395
 396 :mochidef:`Color.prototype.asHSV()`:
 397
 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``.
 401
 402     *Availability*:
 403         Available in MochiKit 1.3.1+
 404
 405
 406 :mochidef:`Color.blackColor()`:
 407
 408     Return a :mochiref:`Color` object whose RGB values are 0, 0, 0
 409     (#000000).
 410
 411     *Availability*:
 412         Available in MochiKit 1.3.1+
 413
 414
 415 :mochidef:`Color.blueColor()`:
 416
 417     Return a :mochiref:`Color` object whose RGB values are 0, 0, 1
 418     (#0000ff).
 419
 420     *Availability*:
 421         Available in MochiKit 1.3.1+
 422
 423
 424 :mochidef:`Color.brownColor()`:
 425
 426     Return a :mochiref:`Color` object whose RGB values are 0.6, 0.4,
 427     0.2 (#996633).
 428
 429     *Availability*:
 430         Available in MochiKit 1.3.1+
 431
 432
 433 :mochidef:`Color.cyanColor()`:
 434
 435     Return a :mochiref:`Color` object whose RGB values are 0, 1, 1
 436     (#00ffff).
 437
 438     *Availability*:
 439         Available in MochiKit 1.3.1+
 440
 441
 442 :mochidef:`Color.darkGrayColor()`:
 443
 444     Return a :mochiref:`Color` object whose RGB values are 1/3, 1/3,
 445     1/3 (#555555).
 446
 447     *Availability*:
 448         Available in MochiKit 1.3.1+
 449
 450
 451 :mochidef:`Color.grayColor()`:
 452
 453     Return a :mochiref:`Color` object whose RGB values are 0.5, 0.5,
 454     0.5 (#808080).
 455
 456     *Availability*:
 457         Available in MochiKit 1.3.1+
 458
 459
 460 :mochidef:`Color.greenColor()`:
 461
 462     Return a :mochiref:`Color` object whose RGB values are 0, 1, 0.
 463     (#00ff00).
 464
 465     *Availability*:
 466         Available in MochiKit 1.3.1+
 467
 468
 469 :mochidef:`Color.lightGrayColor()`:
 470
 471     Return a :mochiref:`Color` object whose RGB values are 2/3, 2/3,
 472     2/3 (#aaaaaa).
 473
 474     *Availability*:
 475         Available in MochiKit 1.3.1+
 476
 477
 478 :mochidef:`Color.magentaColor()`:
 479
 480     Return a :mochiref:`Color` object whose RGB values are 1, 0, 1
 481     (#ff00ff).
 482
 483     *Availability*:
 484         Available in MochiKit 1.3.1+
 485
 486
 487 :mochidef:`Color.orangeColor()`:
 488
 489     Return a :mochiref:`Color` object whose RGB values are 1, 0.5, 0
 490     (#ff8000).
 491
 492     *Availability*:
 493         Available in MochiKit 1.3.1+
 494
 495
 496 :mochidef:`Color.purpleColor()`:
 497
 498     Return a :mochiref:`Color` object whose RGB values are 0.5, 0, 0.5
 499     (#800080).
 500
 501     *Availability*:
 502         Available in MochiKit 1.3.1+
 503
 504
 505 :mochidef:`Color.redColor()`:
 506
 507     Return a :mochiref:`Color` object whose RGB values are 1, 0, 0
 508     (#ff0000).
 509
 510     *Availability*:
 511         Available in MochiKit 1.3.1+
 512
 513
 514 :mochidef:`Color.whiteColor()`:
 515
 516     Return a :mochiref:`Color` object whose RGB values are 1, 1, 1
 517     (#ffffff).
 518
 519     *Availability*:
 520         Available in MochiKit 1.3.1+
 521
 522
 523 :mochidef:`Color.yellowColor()`:
 524
 525     Return a :mochiref:`Color` object whose RGB values are 1, 1, 0
 526     (#ffff00).
 527
 528     *Availability*:
 529         Available in MochiKit 1.3.1+
 530
 531
 532 :mochidef:`Color.transparentColor()`:
 533
 534     Return a :mochiref:`Color` object that is completely transparent
 535     (has alpha component of 0).
 536
 537     *Availability*:
 538         Available in MochiKit 1.3.1+
 539
 540
 541 Functions
 542 ---------
 543
 544 :mochidef:`clampColorComponent(num, scale)`:
 545
 546     Returns ``num * scale`` clamped between ``0`` and ``scale``.
 547
 548     :mochiref:`clampColorComponent` is not exported by default when
 549     using JSAN.
 550
 551     *Availability*:
 552         Available in MochiKit 1.3.1+
 553
 554
 555 :mochidef:`hslToRGB(hue, saturation, lightness, alpha)`:
 556
 557     Computes RGB values from the provided HSL values. The return value
 558     is a mapping with ``"r"``, ``"g"``, ``"b"`` and ``"a"`` keys.
 559
 560     Alternate form:
 561         :mochiref:`hslToRGB({h: hue, s: saturation, l: lightness, a:
 562         alpha})`.
 563
 564     :mochiref:`hslToRGB` is not exported by default when using JSAN.
 565
 566     *Availability*:
 567         Available in MochiKit 1.3.1+
 568
 569
 570 :mochidef:`hsvToRGB(hue, saturation, value, alpha)`:
 571
 572     Computes RGB values from the provided HSV values. The return value
 573     is a mapping with ``"r"``, ``"g"``, ``"b"`` and ``"a"`` keys.
 574
 575     Alternate form:
 576         :mochiref:`hsvToRGB({h: hue, s: saturation, v: value, a:
 577         alpha})`.
 578
 579     :mochiref:`hsvToRGB` is not exported by default when using JSAN.
 580
 581     *Availability*:
 582         Available in MochiKit 1.3.1+
 583
 584
 585 :mochidef:`toColorPart(num)`:
 586
 587     Convert num to a zero padded hexadecimal digit for use in a
 588     hexadecimal color string. Num should be an integer between ``0``
 589     and ``255``.
 590
 591     :mochiref:`toColorPart` is not exported by default when using
 592     JSAN.
 593
 594     *Availability*:
 595         Available in MochiKit 1.3.1+
 596
 597
 598 :mochidef:`rgbToHSL(red, green, blue, alpha)`:
 599
 600     Computes HSL values based on the provided RGB values. The return
 601     value is a mapping with ``"h"``, ``"s"``, ``"l"`` and ``"a"``
 602     keys.
 603
 604     Alternate form:
 605         :mochiref:`rgbToHSL({r: red, g: green, b: blue, a: alpha})`.
 606
 607     :mochiref:`rgbToHSL` is not exported by default when using JSAN.
 608
 609     *Availability*:
 610         Available in MochiKit 1.3.1+
 611
 612
 613 :mochidef:`rgbToHSV(red, green, blue, alpha)`:
 614
 615     Computes HSV values based on the provided RGB values. The return
 616     value is a mapping with ``"h"``, ``"s"``, ``"v"`` and ``"a"``
 617     keys.
 618
 619     Alternate form:
 620         :mochiref:`rgbToHSV({r: red, g: green, b: blue, a: alpha})`.
 621
 622     :mochiref:`rgbToHSV` is not exported by default when using JSAN.
 623
 624     *Availability*:
 625         Available in MochiKit 1.3.1+
 626
 627
 628 See Also
 629 ========
 630
 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
 634
 635
 636 Authors
 637 =======
 638
 639 - Bob Ippolito <bob@redivi.com>
 640
 641
 642 Copyright
 643 =========
 644
 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
 648 v2.1`_.
 649
 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