First off, it's worth emphasizing that the Uize.Color object is not a Uize.Class subclass, but a very lightweight object.

As such, the Uize.Color object does not support events, does not provide state properties, does not inherit subclassing facilities from the Uize.Class base class, etc. This object is deliberately designed to be very lightweight and to have a really tiny footprint - in the spirit of JavaScript's native objects, such as String, Number, Date, and the like.

The Uize.Color object provides the following key features...

1.2.1. A Framework for Defining Color Spaces

1.2.2. A Framework for Defining Color Encodings

1.2.3. Methods for Manipulating Colors

1.2.4. A Framework for Defining Named Colors

There are actually three different ways that a new instance of the Uize.Color object can be created.

1.3.1. Using the Constructor

var myColor = Uize.Color ('#f0f');  // initialized to fuchsia

1.3.2. Using the Uize.Color.from Static Method

var myColor = Uize.Color.from ('#f0f');  // initialized to fuchsia

1.3.3. Using the Uize.Color.to Static Method

var myColor = Uize.Color.to ('#f0f','color');  // initialized to fuchsia

The following example pages are good showcases for the Uize.Color module...

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Color module...

SEARCH

The Uize.Color module defines the Uize.Color object under the Uize namespace.

1.5.1. Features Introduced in This Module

1.5.2. Features Overridden in This Module

1.5.3. Features Inherited From Other Modules

1.5.4. Modules Directly Under This Namespace

1.5.5. Unit Tests

A string, reflecting the name of the color encoding that is set for the instance.

This is a read-only property. In order to change the color encoding for an instance, you should use the setEncoding instance method. The setEncoding method handles the conversions necessary when switching to an encoding in a different color space and will automatically transform the color component values contained inside the tuple array.

NOTES

An array, containing typically three, but up to four floating point number elements, representing the values for the color components of the instance.

This property can be accessed by code that wishes to perform color computations, or by code that wishes to encode a color value in a custom manner - not using any of the color encodings supported by the Uize.Color object. This property can also be useful when implementing extension modules.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Lets you set the color for the Uize.Color object instance from the specified color, by decoding the specified color as needed.

SYNTAX

colorOBJ = colorOBJ.from (colorANYTYPE);

The color specified by the colorANYTYPE parameter can be specified using any of the many color encodings supported by the Uize.Color module. The following examples illustrate this variety and flexibility...

EXAMPLES

myColor.from (Uize.Color (255,0,255));                 // color
myColor.from ('ff00ff');                               // hex
myColor.from ('#ff00ff');                              // #hex
myColor.from ('fuchsia');                              // name
myColor.from ([255,0,255]);                            // RGB array
myColor.from (0xff00ff);                               // RGB int
myColor.from ({red:255,green:0,blue:255});             // RGB object
myColor.from ('Rgb(255,0,255)');                       // RGB string
myColor.from ({hue:300,saturation:100,lightness:50});  // HSL object
myColor.from ('Hsl(300,100%,50%)');                    // HSL string

The above statements would all set the color of the instance myColor to the color "fuchsia" (#ff00ff).

VARIATION

colorOBJ.from ();

When no colorANYTYPE parameter is specified, the instance will be initialized to black (in the sRGB color space).

TIP

Because the from method returns the instance on which it is called, you can "daisy chain" method calls, as in...

fuchsiaHslObject = myColor.from ('fuchsia').to ('HSL object');

The above example first sets the Uize.Color object instance myColor to the color "fuchsia" and then encodes its value as HSL object and assigns that value to the variable fuchsiaHslObject.

NOTES

IMPLEMENTATION INFO

Returns an array, being the tuple of color components for the instance, transformed for the specified color encoding or color space.

SYNTAX

tupleARRAY = myColor.getTuple (encodingOrColorSpaceSTR);

If the color space of the instance's current encoding is the same as the color space defined by the encodingOrColorSpaceSTR parameter, then the value of the tuple instance property will be returned as is (i.e. no transformation is performed). Otherwise, the necessary conversion functions will be employed to transform the instance's tuple for use in the desired color space.

This method can be used by other methods that wish to blend, mix, or otherwise process multiple tuples in a single color space.

VARIATION

tupleARRAY = myColor.getTuple ();

When no encodingOrColorSpaceSTR parameter is specified, then the value of the tuple instance property will be returned (i.e. no transformation is performed).

EXAMPLE

myColor.getTuple ('HSL');
myColor.getTuple ('HSL array');
myColor.getTuple ('HSL string');

In the above example, the same HSL color space is implied by all statements, so all statements will return the same result. Note that the particular encoding has no bearing on how the tuple is returned - it is always an array of the components of the color. So, the value 'HSL string' for encodingOrColorSpaceSTR still results in the tuple array being returned.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Lets you change the encoding for an instance.

Changing the encoding for an instance will have no effect on the instance's tuple values if the new encoding is of the same color space as the current encoding. However, if the color spaces differ, then the tuple values will be converted to be in the color space of the new encoding.

SYNTAX

myColor.setEncoding (encodingSTR);

NOTES

IMPLEMENTATION INFO

Returns the current color of the instance, encoded to the specified color encoding.

SYNTAX

encodedColor = colorOBJ.to (encodingSTR);

The encodingSTR parameter supports a wide variety of different color encodings.

EXAMPLES

var fuchsia = Uize.Color ('fuchsia');
fuchsia.to ('color');       // produces a new Uize.Color object
fuchsia.to ('hex');         // produces 'ff00ff'
fuchsia.to ('#hex');        // produces '#ff00ff'
fuchsia.to ('name');        // produces 'fuchsia'
fuchsia.to ('RGB array');   // produces [255,0,255]
fuchsia.to ('RGB int');     // produces 16711935
fuchsia.to ('RGB object');  // produces {red:255,green:0,blue:255}
fuchsia.to ('RGB string');  // produces 'rgb(255,0,255)'
fuchsia.to ('HSL array');   // produces [300,100,50]
fuchsia.to ('HSL object');  // produces {hue:300,saturation:100,lightness:50}
fuchsia.to ('HSL string');  // produces 'hsl(300,100,50)'

NOTES

IMPLEMENTATION INFO

Returns a value adapter object,

SYNTAX

valueAdapterOBJ = Uize.Color.adapter (aEncodingSTR,bEncodingSTR);

IMPLEMENTATION INFO

IMPLEMENTATION INFO

A method that is useful in the development of color space or encoding extensions, and that returns a tuple array, being a clone of the specified source tuple array.

SYNTAX

clonedTupleARRAY = Uize.Color.cloneTuple (tupleARRAY);

This method is intended primary for use in the implementation of color encodings.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Lets you define an arbitrary number of custom named colors, which will then be accessible to code that uses the Uize.Color module.

SYNTAX

Uize.Color.defineColors (colorsMapOBJ);

When you extend this object with new named colors, it will then be possible to use the names of those colors when creating instances of the Uize.Color object, or when setting the color of Uize.Color instances using the from instance method.

For more information, see the section Defining New Named Colors.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Returns a freshly minted instance of the Uize.Color object, whose color is initialized to the specified color, by decoding the specified color as needed.

SYNTAX

colorOBJ = Uize.Color.from (colorANYTYPE);

The Uize.Color.from method is a factory method, is essentially equivalent to using the Uize.Color object's constructor, and is mainly provided to have parity with the Uize.Color.to static method.

EXAMPLE

Uize.Color ('ff00ff');
Uize.Color.from ('ff00ff');

The above two statements would both return new instances of the Uize.Color object initialized to the color "fuchsia" (#ff00ff).

The color specified by the colorANYTYPE parameter can be specified using any of the many color encodings supported by the Uize.Color module. The following examples illustrate this variety and flexibility...

EXAMPLES

Uize.Color.from (Uize.Color (255,0,255));                 // color
Uize.Color.from ('ff00ff');                               // hex
Uize.Color.from ('#ff00ff');                              // #hex
Uize.Color.from ('fuchsia');                              // name
Uize.Color.from ([255,0,255]);                            // RGB array
Uize.Color.from (0xff00ff);                               // RGB int
Uize.Color.from ({red:255,green:0,blue:255});             // RGB object
Uize.Color.from ('Rgb(255,0,255)');                       // RGB string
Uize.Color.from ({hue:300,saturation:100,lightness:50});  // HSL object
Uize.Color.from ('Hsl(300,100%,50%)');                    // HSL string

The above statements would all return new instances of the Uize.Color object initialized to the color "fuchsia" (#ff00ff).

VARIATION

Uize.Color.from ();

When no colorANYTYPE parameter is specified, the new instance will be initialized to black (in the sRGB color space).

5.9.1. A Tip on Preserving Encoding

var oldEncoding = myColor.encoding;
myColor.from (newColorValue).setEncoding (oldEncoding);

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

A method that is useful in the development of color space or encoding extensions, and that copies the specified values for up to four components of a tuple into the specified tuple array.

SYNTAX

Uize.Color.setTuple (
  tupleARRAY,
  component0FLOAT,component1FLOAT,component2FLOAT,component3FLOAT
);

This method is intended primary for use in the implementation of color encodings.

NOTES

IMPLEMENTATION INFO

A method that is useful in the development of color space or encoding extensions, and that copies the values of the first four elements of the specified source array into the specified tuple array.

SYNTAX

Uize.Color.setTupleFromArray (sourceARRAY,tupleARRAY);

This method is intended primary for use in the implementation of color encodings.

NOTES

IMPLEMENTATION INFO

A method that is useful in the development of color space or encoding extensions, and that parses up to four color components from the specified source string and copies the values of those components into the specified tuple array.

SYNTAX

Uize.Color.setTupleFromString (sourceSTR,tupleARRAY);

This method is intended primary for use in the implementation of color encodings.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Encodes the specified color to the specified encoding / format.

SYNTAX

encodedColorANYTYPE = Uize.Color.to (colorToEncodeANYTYPE,encodingSTR);

This method's return value can be of any type, and is determined by the encoding specified in the encodingSTR parameter, which supports a wide variety of different color encodings. Moreover, the color to be encoded, as specified by the colorToEncodeANYTYPE parameter, can be specified in any of the supported encodings.

VARIATION

encodedColorHexSTR = Uize.Color.to (colorToEncodeANYTYPE);

When no encodingSTR parameter is specified, then the color specified by the colorToEncodeANYTYPE parameter will be encoded as hex.

EXAMPLES

Uize.Color.to ('fuchsia','color');        // produces a new Uize.Color object
Uize.Color.to ('#f0f','HSL object');      // {hue:300,saturation:100,lightness:50}
Uize.Color.to ('Rgb(255,0,255)','name');  // produces 'fuchsia'
Uize.Color.to ('hsl(300,100,50)','#hex'); // produces '#ff00ff'
Uize.Color.to ('ff00ff','HSL string');    // produces 'hsl(300,100,50)'
Uize.Color.to ('fuchsia,'RGB string');    // produces 'rgb(255,0,255)'
Uize.Color.to ([255,0,255],'hex');        // produces 'ff00ff'
Uize.Color.to ([255,0,255]);              // produces 'ff00ff'

These are just a few examples to illustrate the versatility of this method. Given the wide variety of different color encodings supported by the Uize.Color module, there are a great many permutations to this method - too numerous to list.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

An object, containing definitions for color spaces supported by the Uize.Color object.

In general, color spaces are not explicitly specified when working with Uize.Color instances. Instead, a color space is implied by a given color encoding. Encodings specify their associated color spaces, and the profile that defines a color space is utilized automatically when encoding across color spaces, such as when encoding a color object that was initialized in the sRGB color space as HSL string, as shown in the following example...

EXAMPLE

var myRgbColor = Uize.Color ('#ff00ff');
alert (myRgbColor.to ('HSL string'));  // displays "Hsl(300,100%,50%)" in dialog

You can define your own color spaces by extending the Uize.Color.colorSpaces static property. For more information, see the section Defining New Color Spaces.

NOTES

IMPLEMENTATION INFO

An object, containing presets for the standard color names supported in the CSS 2.1 specification.

Named colors defined in the Uize.Color.colors object can be used wherever color values can be specified in the methods of the Uize.Color object, and other modules that use this object for resolving color values.

EXAMPLE

Uize.Color ('yellow');                  // source encoding is name
Uize.Color (Uize.Color.colors.yellow);  // source encoding is RGB int

In the above example, each of the statements would create a new instance of the Uize.Color object initialized to primary yellow. In the first statement, the color yellow is specified using the name encoding. In the second statement, however, the color is specified using the RGB int encoding. That's because the values of the properties of the Uize.Color.colors static property are actually integers representing the RGB values of the colors.

For more information, see the section Named Colors. You can also define your own named colors by extending the Uize.Color.colors static property. For more information, see the section Defining New Named Colors.

NOTES

IMPLEMENTATION INFO

An object, containing definitions for color encodings supported by the Uize.Color object.

The Uize.Color object defines a wide variety of built-in encodings. For the full list, consult the section Color Encodings. You can also define your own color encoding by extending the Uize.Color.encodings static property. For more information, see the section Defining New Color Encodings.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

The Uize.Color.colorSpaces.sRGB property defines the sRGB (standard RGB) color space.

sRGB is the recommended color space for the Internet and is the color space used by the CSS 2.1 color specification. Because of this, it is also the default working color space for many digital cameras, phones, scanners, and other electronics devices.

The Uize.Color.colorSpaces.HSL property defines the HSL (Hue, Saturation, Lightness) color space.

The HSL color space is essentially an alternate representation / mapping of the sRGB color space, but might be considered to be a more intuitive representation of the qualities of color. Because of the benefits of this color space, it has been adopted in the CSS 3 color specification as another accepted way of specifying colors.

Additional color spaces are made available through extension modules, such as the Uize.Color.xHsv module that defines the HSV color space.

Implementing color spaces in extension modules avoids burdening the core code with having to support less common / more esoteric color spaces that are not as frequently used. This also allows applications built on the UIZE JavaScript Framework to be better optimized for code size.

You can extend the Uize.Color.colorSpaces object in order to define new color spaces.

This can be done quite easily by setting a new property on the Uize.Color.colorSpaces object, as follows...

EXAMPLE

Uize.Color.colorSpaces.CMYK = {
  fromHsl:function (_tuple) {
    // this function should accept a tuple in the HSL colorspace
    // and should return a new tuple that represents the color
    // transformed to the CMYK color space
  },
  toHsl:function (_tuple) {
    // this function should accept a tuple in the CMYK color space
    // and should return a new tuple that represents the color
    // transformed to the HSL color space
  },
  tuple:[
    {name:'cyan',min:0,max:100},
    {name:'magenta',min:0,max:100},
    {name:'yellow',min:0,max:100},
    {name:'black',min:0,max:100}
  ]
}

Typically one will define a new color space and also define new color encodings to accompany the new color space. The new encodings should specify the name of their associated color space in their colorSpace property.

The object that describes a color space is called a color space profile, and should have the following properties...

The fromHsl and toHsl conversion functions that you provide as part of a color space profile are used for converting a tuple back and forth between your color space and the HSL color space. The HSL color space is essentially used as a canonical color space - a kind of "conduit" through which colors are converted in order to convert across color spaces. This avoids having to have an ever increasing number of cross conversion functions for every defined color space to every other. For example, if a CMYK color space were defined, then conversion from sRGB to CMYK would first involve conversion from sRGB to HSL, and then HSL to CMYK.

An instance of the Uize.Color object.

8.1.1. Encoding

8.1.2. Decoding

A six digit, three digit, or one digit hexadecimal string (e.g. the color chartreuse is encoded as '7fff00').

8.2.1. Encoding

8.2.2. Decoding

A six digit, three digit, or one digit hexadecimal string, with a "#" (pound) character prefixed (e.g. the color chartreuse is encoded as '#7fff00').

8.3.1. Encoding

8.3.2. Decoding

A string, representing the name for a color (e.g. the color chartreuse is encoded as 'chartreuse').

8.4.1. Encoding

8.4.2. Decoding

fuchsia
YELLOW
Blue
whITE

NOTES

An array, containing three elements for the red, green, and blue channels of an sRGB color, whose values are integers (e.g. the color chartreuse is encoded as [127,255,0]).

8.5.1. Encoding

8.5.2. Decoding

[255,0,255]         // fuchsia
[255.5,0.23,254.7]  // fuchsia
['255','0','255']   // fuchsia
[redSlider,greenSlider,blueSlider]

An integer in the range of 0 to 16777215, corresponding in value to the hexadecimal RGB representation of a color (e.g. the color chartreuse is encoded as 8388352, which is equivalent to the hex number representation 0x7fff00).

8.6.1. Encoding

8.6.2. Decoding

16711935   // fuchsia
0xff00ff   // fuchsia

An object, containing red, green, and blue properties for the three sRGB channels, whose values are integers (e.g. the color chartreuse is encoded as {red:127,green:255,blue:0}).

8.7.1. Encoding

8.7.2. Decoding

{red:255,green:0,blue:255}         // fuchsia
{red:255.5,green:0.23,blue:254.7}  // fuchsia
{red:'255',green:'0',blue:'255'}   // fuchsia
{red:redSlider,green:greenSlider,blue:blueSlider}

An Rgb(...) formatted CSS color style property value (e.g. the color chartreuse is encoded as 'rgb(127,255,0)')

8.8.1. Encoding

8.8.2. Decoding

rgb(255,0,255)
RGB(255,0,255)
Rgb (255, 0, 255)
RGB ( 255 , 0 , 255 )

An array, containing three elements for hue, saturation, and lightness, whose values may be floating point numbers (e.g. the color chartreuse is encoded as [90.11764705882354,100,50]), and that specifies a color in the HSL color space.

8.9.1. Encoding

8.9.2. Decoding

[300,100,50]         // fuchsia
['300','100','50']   // fuchsia
[hueSlider,saturationSlider,lightnessSlider]

An object, containing hue, saturation, and lightness properties, whose values may be floating point numbers (e.g. the color chartreuse is encoded as {hue:90.11764705882354,saturation:100,lightness:50}), and that specifies a color in the HSL color space.

8.10.1. Encoding

8.10.2. Decoding

{hue:300,saturation:100,lightness:50}         // fuchsia
{hue:'300',saturation:'100',lightness:'50'}   // fuchsia
{hue:hueSlider,saturation:saturationSlider,lightness:lightnessSlider}

An Hsl(...) formatted CSS color style property value (e.g. the color chartreuse is encoded as 'hsl(90,100%,50%)') that specifies a color in the HSL color space.

8.11.1. Encoding

8.11.2. Decoding

hsl(300,100,50)
hsl(300,100%,50%)
HSL(300,100%,50%)
Hsl (300, 100%, 50%)
HSL ( 300 , 100% , 50% )
Hsl ( 300 , 100 , 50 )

You can extend the Uize.Color.encodings object in order to define new color encodings.

This can be done quite easily by setting a new property on the Uize.Color.encodings object, as follows...

EXAMPLE

Uize.Color.encodings ['RGB float array'] = {
  colorSpace:'sRGB',
  from:function (_colorValue,_tuple) {
    _tuple [0] = _colorValue [0] * 255;
    _tuple [1] = _colorValue [1] * 255;
    _tuple [2] = _colorValue [2] * 255;
  },
  to:function (_tuple) {
    return [_tuple [0] / 255,_tuple [1] / 255,_tuple [2] / 255];
  }
}

The above example defines an encoding named "RGB float aray", where the three elements of the array represent the values of the red, green, and blue channels as floating point numbers in the range of 0 to 1. So, whereas the statement Uize.Color.to ('purple','RGB array') would produce the result [128,0,128], the statement Uize.Color.to ('purple','RGB float array') would produce the result [0.5019607843137255,0,0.5019607843137255]. Conversely, the statement Uize.Color.to ({'RGB float array':[.5,0,.5]},'name') would produce the result 'purple'.

The object that describes a color encoding is called a color encoding profile, and should have the following properties...

Named colors defined in the Uize.Color.colors object can be used wherever color values can be specified in the methods of the Uize.Color object, and other modules that use this object for resolving color values.

EXAMPLE 1

var myColor = Uize.Color ('fuchsia');

In the above example, the Uize.Color instance myColor is being initialized to the color "fuchsia" (#ff00ff).

EXAMPLE 2

var fuchsiaAsHexStr = Uize.Color.to ('fuchsia','hex');

In the above example, the color "fuchsia" is being converted to a hexadecimal string using the hex encoding.

EXAMPLE 3

Uize.Fx.fadeStyle ('myNodeId',{borderColor:'purple'},{borderColor:'fuchsia'});

Because the Uize.Color module is used by other modules, such as the Uize.Fx module, it is also possible to use color names when specifying the values of color CSS style properties for fade effects.

Additional named colors are made available through extension modules, such as the Uize.Color.xSvgColors module that defines the SVG 1.0 / CSS 3 named colors.

Over a hundred additional named colors - as defined in the SVG 1.0 and CSS 3 specifications - are defined in the Uize.Color.xSvgColors extension module. Implementing further named colors in extension modules avoids burdening the core code with having to support less frequently used color sets. This also allows applications built on the UIZE JavaScript Framework to be better optimized for code size.

You can extend the Uize.Color.colors object using the Uize.Color.defineColors static method in order to add your own named colors, which will then be accessible to code that uses the Uize.Color module.

EXAMPLE

Uize.Color.defineColors ({darkmagenta:0x8b008b,lavenderblush:0xfff0f5});
Uize.Fx.fadeStyle ('myNodeId',{color:'darkmagenta'},{color:'lavenderblush'});

9.3.1. Case Doesn't Matter

9.3.2. Specify Color Values as RGB int

Uize.Color.defineColors ({lavenderblush:'#fff0f5'});  // DON'T USE OTHER ENCODING

Uize.Color.defineColors ({
  darkmagenta   : 0x8b008b,   // OK TO USE HEX FORMATTED NUMBER
  lavenderblush : 16773365    // OK TO USE DECIMAL NUMBER
});

NOTES