Documentation
dojo/_base/Color¶
Authors: | Marcus Reimann, Bill Keese, JJ Kress |
---|---|
Developers: | Eugene Lazutkin, Adam Peller, Alex Russell |
Contents
dojo._base.Color contains functions for setting Colors.
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.
Usage¶
As with the rest of dojo/_base modules, if you are running the Dojo loader in legacy mode (async: false) this module is automatically loaded. Even if it is automatically loaded, you should require it in to have access to its features:
require(["dojo/_base/Color"], function(Color){
// Color contains functions
});
Features¶
Methods¶
Method | Returns | Description |
---|---|---|
blendColors(start,end,weight,obj) | undefined | Blend colors end and start with weight from 0 to 1, 0.5 being a 50/50 blend, can reuse a previously allocated Color object for the result |
constructor(color) | dojo/_base/Color | Takes a named string, hex string, array of rgb or rgba values,
an object with r, g, b, and a properties, or another |
fromArray(a,obj) | any|undefined | Builds a |
fromHex(color,obj) | any | Converts a hex string with a '#' prefix to a color object.
Supports 12-bit #rgb shorthand. Optionally accepts a
|
fromString(str,obj) | any | Parses Acceptable input values for str may include arrays of any form accepted by dojo.colorFromArray, hex strings such as "#aaaaaa", or rgb or rgba strings such as "rgb(133, 200, 16)" or "rgba(10, 10, 10, 50)" |
setColor(color) | function | Takes a named string, hex string, array of rgb or rgba values,
an object with r, g, b, and a properties, or another |
toCss(includeAlpha) | string | Returns a css color string in rgb(a) representation |
toHex() | string | Returns a CSS color string in hexadecimal representation |
toRgb() | Array | Returns 3 component array of rgb values |
toRgba() | Array | Returns a 4 component array of rgba values from the color represented by this object. |
toString() | undefined | Returns a visual representation of the color |
Properties¶
Property | Type | Description |
---|---|---|
named | object | Dictionary list of all CSS named colors, by name. Values are 3-item arrays with corresponding RG and B values. |
Note: named only contains the 16 named colors defined by the HTML4 standard. If you need all named colors from the CSS3 standard you have to require dojo/colors.
Examples¶
Creating 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:
require(["dojo/_base/Color"], function(Color){ // AMD allows us to use the color functions under the alias name
"Color"
// Creates an empty color object for later use
var emptyColor = new Color();
// Constructor accepts named colors
var namedColor = new Color("purple");
// Hex Strings work also
var hexColor = new Color("#cdefa0");
// One can also pass arrays containing 3 or 4 values
var a3Color = new Color([123, 123, 234]);
var a4Color = new Color([123, 123, 234, 0.6]);
// Finally, objects with r,g,b and a values work as well
var objColor = new Color({ r:23, g:45, b:67, a:0.7 });
});
Using the from Utility Functions¶
All these expressions result in the same value, a dojo/_base/Color object representing red with no transparency ( full opacity):
require(["dojo/_base/Color"],function(Color){
Color.fromHex("#FF0000");
Color.fromHex("#F00");
Color.fromArray([255, 0, 0]);
Color.fromArray([255, 0, 0, 1]);
Color.fromRgb("rgb(255, 0, 0)");
Color.fromRgb("rgba(255, 0, 0, 1)");
Color.fromString("red");
// as mentioned above, you could also pass a hex string or an rgb(a) string
});
Blending Colors¶
dojo/_base/Color supports a blend function that can blend two Color instances together with a weighting, to produce a new color.
require(["dojo/_base/Color"], function(Color){
Color.blendColors(start, end, weight, color);
});
Return a Specific Format¶
The Color object also provides some methods to return the color in a desired format: toRgb(), toRgba(), toHex(), toCss() and toString().
require(["dojo/_base/Color"], function(Color){
// First create a color object, containing red
var myColor = Color.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:
require(["dojo/_base/Color", "dom-stlye"], function(Color, style){
var myColor = Color.fromString("red");
style.set("someId", "backgroundColor", myColor);
// This changes the background-color of the element "someId" to the color specified in myColor
});
See Also¶
- dojo/colors - Additional color features.
- dojox/color - Even more color features.