Class: SC.Color

Extends SC.Copyable, SC.Error, SC.Object.

Represents a color, and provides methods for manipulating it. Maintains underlying rgba values, and includes support for colorspace conversions between rgb and hsl.

For instructions on using SC.Color to color a view, see "SC.Color and SC.View" below.

Basic Use

You can create a color from red, green, blue and alpha values, with:

SC.Color.create({
  r: 255,
  g: 255,
  b: 255,
  a: 0.5
});

All values are optional; the default is black. You can also create a color from any valid CSS string, with:

SC.Color.from('rgba(255, 255, 255, 0.5)');

The best CSS value for the given color in the current browser is available at the bindable property cssText. (This will provide deprecated ARGB values for older versions of IE; see "Edge Case: Supporting Alpha in IE" below.) (Calling SC.Color.from with an undefined or null value is equivalent to calling it with 'transparent'.)

Once created, you can manipulate a color by settings its a, r, g or b values, or setting its cssText value (though be careful of invalid values; see "Error State" below).

Math

SC.Color provides three methods for performing basic math: sub for subtraction, add for addition, and mult for scaling a number via multiplication.

Note that these methods do not perform any validation to ensure that the underlying rgba values stay within the device's gamut (0 to 255 on a normal screen, and 0 to 1 for alpha). For example, adding white to white will result in r, g and b values of 510, a nonsensical value. (The cssText property will, however, correctly clamp the component values, and the color will output #FFFFFF.) This behavior is required for operations such as interpolating between colors (see "SC.Color and SC.View" below); it also gives SC.Color more predictable math, where A + B - B = A, even if the intermediate (A + B) operation results in underlying values outside of the normal gamut.

(The class method SC.Color.clampToDeviceGamut is used to clamp r, g and b values to the standard 0 - 255 range. If your application is displaying on a screen with non-standard ranges, you may need to override this method.)

SC.Color and SC.View

Hooking up an instance of SC.Color to SC.View#backgroundColor is simple, but like all uses of backgroundColor, it comes with moderate performance implications, and should be avoided in cases where regular CSS is sufficient, or where bindings are unduly expensive, such as in rapidly-scrolling ListViews.

Use the following code to tie a view's background color to an instance of SC.Color. Note that you must add backgroundColor to displayProperties in order for your view to update when the it changes; for performance reasons it is not included by default.

SC.View.extend({
  color: SC.Color.from({'burlywood'}),
  backgroundColorBinding: SC.Binding.oneWay('*color.cssText'),
  displayProperties: ['backgroundColor']
})

You can use this to implement a simple cross-fade between two colors. Here's a basic example (again, note that when possible, pure CSS transitions will be substantially more performant):

SC.View.extend({
  displayProperties: ['backgroundColor'],
  backgroundColor: 'cadetblue',
  fromColor: SC.Color.from('cadetblue'),
  toColor: SC.Color.from('springgreen'),
  click: function() {
    // Cancel previous timer.
    if (this._timer) this._timer.invalidate();
    // Figure out whether we're coming or going.
    this._forward = !this._forward;
    // Calculate the difference between the two colors.
    var fromColor = this._forward ? this.fromColor : this.toColor,
        toColor = this._forward ? this.toColor : this.fromColor;
    this._deltaColor = toColor.sub(fromColor);
    // Set the timer.
    this._timer = SC.Timer.schedule({
      target: this,
      action: '_tick',
      interval: 15,
      repeats: YES,
      until: Date.now() + 500
    });
  },
  _tick: function() {
    // Calculate percent of time elapsed.
    var started = this._timer.startTime,
        now = Date.now(),
        until = this._timer.until,
        pct = (now - started) / (until - started);
    // Constrain pct.
    pct = Math.min(pct, 1);
    // Calculate color.
    var fromColor = this._forward ? this.fromColor : this.toColor,
        toColor = this._forward ? this.toColor : this.fromColor,
        deltaColor = this._deltaColor,
        currentColor = fromColor.add(deltaColor.mult(pct));
    // Set.
    this.set('backgroundColor', currentColor.get('cssText'));
  }
})

Error State

If you call SC.Color.from with an invalid value, or set cssText to an invalid value, the color object will go into error mode, with isError set to YES and errorValue containing the invalid value that triggered it. A color in error mode will become transparent, and you will be unable to modify its r, g, b or a values.

To reset a color to its last-good values (or, if none, to black), call its reset method. Setting cssText to a valid value will also recover the color object to a non-error state.

Edge Case: Supporting Alpha in IE

Supporting the alpha channel in older versions of IE requires a little extra work. The bindable cssText property will return valid ARGB (e.g. #99FFFFFF) when it detects that it's in an older version of IE which requires it, but unfortunately you can't simply plug that value into background-color. The following code will detect this case and provide the correct CSS snippet:

// This hack disables ClearType on IE!
var color = SC.Color.from('rgba(0, 0, 0, .5)').get('cssText'),
    css;
if (SC.Color.supportsARGB) {
  var gradient = "progid:DXImageTransform.Microsoft.gradient";
  css = ("-ms-filter:" + gradient + "(startColorstr=%@1,endColorstr=%@1);" +
         "filter:" + gradient + "(startColorstr=%@1,endColorstr=%@1)" +
         "zoom: 1").fmt(color);
} else {
  css = "background-color:" + color;
}

Defined in: color.js

Field Summary

Class Methods

• clamp(value, min, max)
• clampInt(value, min, max)
• clampToDeviceGamut(value)
• from(color)
• hslToRgb(h, s, l)
• hsvToRgb(h, s, v)
• rgbToHsl(r, g, b)
• rgbToHsv(r, g, b)

Instance Methods

• a(key, value)
• add(color)
• b(key, value)
• copy()
• g(key, value)
• isEqualTo(color)
• mult(multipler)
• r(key, value)
• reset()
• sub(color)
• toArgb()
• toHex()
• toHsl()
• toHsla()
• toRgb()
• toRgba()