dojo.Color

Authors:Marcus Reimann, Bill Keese, JJ Kress Developers:Eugene Lazutkin, Adam Peller, Alex Russell since:v1.0.0

Contents

• dojo.Color
  • Features
  • Examples

dojo._base.Color contains functions for setting Colors.

As with all dojo._base components, these functions are included within Dojo Base. You get this functionality by just including dojo.js in your page.

The Color object provides a unified way to store colors, which holds the color in rgba form. This simplifies dealing with the different ways to define colors as everyone can use the format they are most comfortable with. Color objects can be used directly as a value to the various color attributes.

Features

• dojo.Color.named

  An array of named Colors. Those are only the 16 named colors defined by the HTML 4 standard. If you need all named colors from the CSS3 standard you have to require dojo.colors

• dojo.blendColors

  Blend two colors in a given ration to create a new one. It takes two dojo.Color objects and a ration between 0 and 1, which is interpreted as a weight: if you provide a ration of 0.25, blendColors will take 25% of the first color and 75% of the second color. The calculation is straight forward: each of the rgba values of the first color are multiplied by 0.25, the values of the second color are multiplied by 0.75 and added to the results

• dojo.colorFromRgb

  This will create or modify a color object from a string resembling a CSS color definition in the form of rgb() or rgba()

• dojo.colorFromHex

  Converts a hex string with a ‘#’ prefix to a color object. Supports 12-bit #rgb shorthand.

• dojo.colorFromArray

  Builds a color from 3 or 4 element array. Note that, contrary to what the autogenerated API documentation might tell you, fewer elements in the array will result in broken color objects.

• dojo.colorFromString

  Parses a string for a color value. You can pass either one of the 16 named colors, hex strings such as “#23ab45” and “#28a”, or rgb(a) strings such as “rgb(200,100,50)” and “rgba(200,100,50,0.5)”

Examples

Creating color objects with the constructor

A new color object is either created by using the constructor or any of the utility functions. Next are some examples of using the constructor with different arguments:

// Creates an empty color object for later use
var emptyColor = new dojo.Color();

// Constructor accepts named colors
var namedColor = new dojo.Color("purple");

// Hex Strings work also
var hexColor = new dojo.Color("#cdefa0");

// One can also pass arrays containing 3 or 4 values
var a3Color = new dojo.Color([123,123,234]);
var a4Color = new dojo.Color([123,123,234,0.6]);

// Finally, objects with r,g,b and a values work as well
var objColor = new dojo.Color({r:23,g:45,b:67,a:0.7});

// Creates an empty color object for later use var emptyColor = new dojo.Color(); // Constructor accepts named colors var namedColor = new dojo.Color("purple"); // Hex Strings work also var hexColor = new dojo.Color("#cdefa0"); // One can also pass arrays containing 3 or 4 values var a3Color = new dojo.Color([123,123,234]); var a4Color = new dojo.Color([123,123,234,0.6]); // Finally, objects with r,g,b and a values work as well var objColor = new dojo.Color({r:23,g:45,b:67,a:0.7});

Using the colorFrom* utility functions

All these expressions result in the same value, a dojo.Color object representing red with no transparency (full opacity):

dojo.colorFromHex("#FF0000")

dojo.colorFromHex("#FF0000")

dojo.colorFromHex("#F00")

dojo.colorFromHex("#F00")

dojo.colorFromArray([255, 0, 0])

dojo.colorFromArray([255, 0, 0])

dojo.colorFromArray([255, 0, 0, 1])

dojo.colorFromArray([255, 0, 0, 1])

dojo.colorFromRgb("rgb(255, 0, 0)")

dojo.colorFromRgb("rgb(255, 0, 0)")

dojo.colorFromRgb("rgba(255, 0, 0, 1)")

dojo.colorFromRgb("rgba(255, 0, 0, 1)")

dojo.colorFromString("red")
// as mentioned above, you could also pass a hex string or an rgb(a) string

dojo.colorFromString("red") // as mentioned above, you could also pass a hex string or an rgb(a) string

Using the blendColors function

TODO

Returning specific formats with the object methods

The color object also provides some methods to return the color in a desired format, toRgb(), toRgba(), toHex(), toCss() and toString().

// First create a color object, containing red
var myColor = dojo.colorFromString("red");

// Now return the color with the object methods
myColor.toRgb();  // returns the Array [255,0,0]
myColor.toRgba(); // returns the Array [255,0,0,1]
myColor.toHex(); // returns the String "#ff0000"
myColor.toCss(false); // returns the String "rgb(255,0,0)"
myColor.toCss(true); // returns the String "rgba(255,0,0,1)"
myColor.toString(); // returns the String "rgba(255,0,0,1)"

// First create a color object, containing red var myColor = dojo.colorFromString("red"); // Now return the color with the object methods myColor.toRgb(); // returns the Array [255,0,0] myColor.toRgba(); // returns the Array [255,0,0,1] myColor.toHex(); // returns the String "#ff0000" myColor.toCss(false); // returns the String "rgb(255,0,0)" myColor.toCss(true); // returns the String "rgba(255,0,0,1)" myColor.toString(); // returns the String "rgba(255,0,0,1)"

Although the last two lines are equivalent, you should use the method that fits to the context to maintain readability.

Using the color object as a value

The last example shows how one can use the color object directly to change the properties of an element:

var myColor = dojo.colorFromString("red");
dojo.style("someId", "backgroundColor", myColor);
// This changes the background-color of the element "someId" to the color specified in myColor

var myColor = dojo.colorFromString("red"); dojo.style("someId", "backgroundColor", myColor); // This changes the background-color of the element "someId" to the color specified in myColor

Table of Contents

• dojo.Color
  • Features
  • Examples
    • Creating color objects with the constructor
    • Using the colorFrom* utility functions
    • Using the blendColors function
    • Returning specific formats with the object methods
    • Using the color object as a value