Contents

1. Introduction

The Uize.Color module provides support for Color Spaces, Color Encodings, Named Colors, the sRGB and HSL color spaces, and many color encodings.

DEVELOPERS: Chris van Rensburg

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

1.1. Not a Uize Subclass

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

As such, the Uize.Color object does not support events, does not provide set-get properties, does not inherit subclassing facilities from the Uize 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.

1.2. Key Features

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

1.2.1. A Framework for Defining Color Spaces

Colors can be represented using different color models and mapping functions. These are called color spaces. Examples of color spaces include sRGB, HSL, HSV, and CMYK, but there are many more in existence.

1.2.2. A Framework for Defining Color Encodings

Colors can be represented using different formats and color models. In UIZE, the combination of a color space and format is called a color encoding.

The Uize.Color object supports a wide variety of built-in Color Encodings. Multiple encodings often exist for the same color space. For example, the #hex (eg. #ff00ff), RGB string (eg. rgb(255,0,255)), and name (eg. fuchsia) encodings are all encodings for the sRGB color space.

EXAMPLES OF BUILT-IN ENCODINGS

ENCODING NAME  |  THE COLOR FUCHSIA IN THIS ENCODING
-------------------------------------------------------
color          |  new Uize.Color ('fuchsia')
hex            |  ff00ff
#hex           |  #ff0fff
name           |  fuchsia
RGB array      |  [255,0,255]
RGB int        |  16711935
RGB object     |  {red:255,green:0,blue:255}
RGB string     |  rgb(255,0,255)
HSL array      |  [300,100,50]
HSL object     |  {hue:300,saturation:100,lightness:50}
HSL string     |  hsl(300,100%,50%)

Beyond the built-in encodings, further encodings are available in extension modules, such as the Uize.Color.xHsv module that defines the HSV color space. Further color spaces can be defined - your own custom color spaces, or those not yet supported.

1.2.3. Methods for Manipulating Colors

Using the Uize.Color object, colors can be converted across color spaces and formats.

Further utilities for dealing with colors are available in extension module, such as the Uize.Color.xUtil module, which provides methods for blending between colors, mixing multiple colors together, testing for color equivalence, etc.

1.2.4. A Framework for Defining Named Colors

Named Colors can be defined, and these colors can then be used wherever colors can be specified using the methods of the Uize.Color object.

And because the Uize.Color module is used by other modules, such as the Uize.Fx module, it is possible to use color names when specifying the values of color CSS style properties for fade effects. The SVG 1.0 and CSS 3 specifications define over a hundred additional named colors, and these become available when using the Uize.Color.xSvgColors extension module. You can also define your own custom named colors (see the section Defining New Named Colors).

1.3. Creating Instances

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

1.3.1. Using the Constructor

Typically, you will create a new instance of the Uize.Color object using its constructor, as follows...

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

1.3.2. Using the Uize.Color.from Static Method

The Uize.Color.from static method is a factory method that decodes the specified color value and produces an instance of the Uize.Color object as a result.

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

1.3.3. Using the Uize.Color.to Static Method

The Uize.Color.to static method decodes the specified color value and then encodes it using the specified encoding. Using the color encoding encodes the source color as an instance of the Uize.Color object.

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

2. Constructor

Lets you create an instance of the Uize.Color object.

SYNTAX

colorOBJ = new Uize.Color (colorANYTYPE);

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

EXAMPLES

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

VARIATION 1

colorOBJ = new Uize.Color;

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

VARIATION 2

colorOBJ = new Uize.Color (redINT,greenINT,blueINT);

When the three parameters redINT, greenINT, blueINT are specified, then the color will be initialized as though the arguments of the constructor represented an RGB array encoding.

EXAMPLE

var
  yellow = new Uize.Color (255,255,0),
  alsoYellow = new Uize.Color ([255,255,0])
;

NOTES

in addition to using the constructor, there are two other methods for Creating Instances of the Uize.Color object

3. Instance Properties

3.1. encoding

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

	this is a read-only property
	see the related `setEncoding` instance method

3.2. tuple

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

	for three component color spaces, the `tuple` array may still contain four elements, where the value of the fourth element is `NaN` or `undefined`
	see the related `getTuple` instance method

4. Instance Methods

4.1. from

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 (new 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

see the related Uize.Color.from static method

4.2. getTuple

Returns an array, being the 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 (ie. 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 (ie. 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

see the related tuple and encoding instance properties

4.3. setEncoding

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

see the related encoding instance property

4.4. to

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 = new 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

see the related Uize.Color.to static method

5. Static Methods

5.1. Uize.Color.cloneTuple

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

see the related Uize.Color.setTuple, Uize.Color.setTupleFromArray, and Uize.Color.setTupleFromString static methods

5.2. Uize.Color.defineColors

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

	see the related `Uize.Color.colors` static property
	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

5.3. Uize.Color.from

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

new 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).

EXAMPLES

Uize.Color.from (new 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.3.1. A Tip on Preserving Encoding

There might be times when you want to set the color value for an instance using a color that is specified in a different encoding - possibly even in a different color space - but you don't wish to change the encoding of the instance.

You can accomplish this by temporarily storing the instance's encoding, and then restoring it after setting the instance's color by using the setEncoding instance method, as in...

EXAMPLE

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

Because the from instance method returns a reference to the instance, you can call the setEncoding method on the result.

NOTES

see the related from instance method

5.4. Uize.Color.setTuple

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

see the related Uize.Color.cloneTuple, Uize.Color.setTupleFromArray, and Uize.Color.setTupleFromString static methods

5.5. Uize.Color.setTupleFromArray

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

see the related Uize.Color.cloneTuple, Uize.Color.setTuple, and Uize.Color.setTupleFromString static methods

5.6. Uize.Color.setTupleFromString

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

see the related Uize.Color.cloneTuple, Uize.Color.setTuple, and Uize.Color.setTupleFromArray static methods

5.7. Uize.Color.to

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

see the related to instance method

6. Static Properties

6.1. Uize.Color.colorSpaces

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 = new 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

compare to the Uize.Color.encodings static property

6.2. Uize.Color.colors

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

new Uize.Color ('yellow');                  // source encoding is name
new 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

	see the related `Uize.Color.defineColors` static method
	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

6.3. Uize.Color.encodings

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

see the related Uize.Color.colorSpaces static property

7. Color Spaces

The Uize.Color object provides a foundation for supporting multiple color spaces, and supports two built-in color spaces: sRGB and HSL.

A color space provides a way to represent colors, and is the combination of a color model and a mapping function. Certain color spaces are better suited to specific applications, and a wide variety of color spaces exist. In the computer world, sRGB is the dominant color space and is based around an additive color model. In the print world, CMYK is a dominant color space and is based around a subtractive color model.

7.1. sRGB

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.

7.2. HSL

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.

7.3. Additional Color Spaces

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.

7.4. Defining New Color Spaces

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...

	`fromHsl` - This is a function that should accept a tuple in the `HSL` colorspace and should return a new tuple that represents the color transformed to your color space.
	`toHsl` - This function should accept a tuple in your color space and should return a new tuple that represents the color transformed to the `HSL` color space.
	`tuple (profile)` - This is an object that provides a profile for the tuple of color components of the color space - the "dimensions" of the color space, if you will. The tuple profile is an array of objects, one for each component of the color space, where each object is a profile for a component and should contain "name", "min", and "max" properties. The "name" property for a component profile is self-explanatory, and the "min" and "max" properties define the value range for the component.

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.

8. Color Encodings

The Uize.Color module supports a wide variety of different color encodings / formats.

For methods that have color parameters, color values for these parameters can be flexibly specified in any of the many supported encodings. Additionally, many of the methods that produce a color as a result allow an encoding to optionally be specified for that return value.

Supported encodings are as follows...

8.1. color

An instance of the Uize.Color object.

8.1.1. Encoding

When a color is encoded as color, an instance of the Uize.Color object is created with its color initialized to that of the encoding source.

EXAMPLES

color name   |  color
------------------------------------------
fuchsia      |  new Uize.Color ('fuchsia')
yellow       |  new Uize.Color ('yellow')
blue         |  new Uize.Color ('blue')
white        |  new Uize.Color ('white')

8.1.2. Decoding

When a color is decoded from color, the value of the source Uize.Color object instance's encoding property and the component values in its tuple property are used for the resulting Uize.Color object.

8.2. hex

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

8.2.1. Encoding

When a color is encoded as hex, the hexadecimal number always contains six digits and is all lowercase.

EXAMPLES

color name  |  hex
---------------------
fuchsia     |  ff00ff
yellow      |  ffff00
blue        |  0000ff
white       |  ffffff

8.2.2. Decoding

When a color is decoded from hex, the hexadecimal number may be specified using only one digit, three digits, or six digits, the "#" (pound) character is optional, and the digits may be in upper, lower, or mixed case (ie. not case sensitive).

WHITE

lowercase  |  UPPERCASE  |  #lowercase  |  #UPPERCASE  |  MiXeD  |  #MiXeD
---------------------------------------------------------------------------
ffffff     |  FFFFFF     |  #ffffff     |  #FFFFFF     |  FfFfFf |  #FfFfFf
fff        |  FFF        |  #fff        |  #FFF        |  FfF    |  #FfF
f          |  F          |  #f          |  #           |         |

8.3. #hex

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

8.3.1. Encoding

When a color is encoded as #hex, the hexadecimal number always contains six digits, is all lowercase, and is prefixed with a "#" (pound) character.

EXAMPLES

color name  |  #hex
----------------------
fuchsia     |  #ff00ff
yellow      |  #ffff00
blue        |  #0000ff
white       |  #ffffff

8.3.2. Decoding

When a color is decoded from #hex, the hexadecimal number may be specified using only one digit, three digits, or six digits, the "#" (pound) character is optional, and the digits may be in upper, lower, or mixed case (ie. not case sensitive).

WHITE

lowercase  |  UPPERCASE  |  #lowercase  |  #UPPERCASE  |  MiXeD  |  #MiXeD
---------------------------------------------------------------------------
ffffff     |  FFFFFF     |  #ffffff     |  #FFFFFF     |  FfFfFf |  #FfFfFf
fff        |  FFF        |  #fff        |  #FFF        |  FfF    |  #FfF
f          |  F          |  #f          |  #           |         |

8.4. name

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

8.4.1. Encoding

When a color is encoded as name, the name string is all lowercase. If no named color is defined that matches the color being encoded, then the encoding source will be encoded as hex as a fallback.

EXAMPLES

color name  |  name
----------------------
fuchsia     |  fuchsia
yellow      |  yellow
blue        |  blue
white       |  white

8.4.2. Decoding

When a color is decoded from name, the name may be in upper, lower, or mixed case (ie. not case sensitive). If no named color is defined by the name specified, then the color will be decoded as black (in the sRGB color space).

EXAMPLES

fuchsia
YELLOW
Blue
whITE

NOTES

	for a list of all the color names supported by the `Uize.Color` module, see the section Named Colors
	further named colors may be defined using the `Uize.Color.defineColors` static method (see the section Defining New 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

8.5. RGB array

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

8.5.1. Encoding

When a color is encoded as RGB array, the resulting array is made up of three number type elements that represent the values of the source color's red, green, and blue channels, respectively.

EXAMPLES

color name  |  RGB array
----------------------------
fuchsia     |  [255,0,255]
yellow      |  [255,255,0]
blue        |  [0,0,255]
white       |  [255,255,255]

8.5.2. Decoding

When a color is decoded from RGB array, the values of the array's three elements may be numbers, strings, or any object that implements a valueOf interface (such as an instance of a Uize subclass that implements the value set-get property).

EXAMPLES

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

NOTES

the values of the color components will be coerced to number type by invoking the valueOf Intrinsic Method

8.6. RGB int

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

8.6.1. Encoding

When a color is encoded as RGB int, it is calculated as red * 65536 + green * 255 + blue.

EXAMPLES

color name  |  RGB int
-----------------------
fuchsia     |  16711935
yellow      |  16776960
blue        |  255
white       |  16777215

8.6.2. Decoding

When a color is decoded from RGB int, the value is first rounded and then constrained to the range of 0 to 16777215.

EXAMPLES

16711935   // fuchsia
0xff00ff   // fuchsia

TIP: When specifying colors as RGB int, you can use JavaScript's facility for specifying numbers in hexadecimal format using the "0x" prefix. This way, you're specifying an integer that looks exactly like a hex or #hex encoded RGB color value, but with the benefit of not using a more costly (in terms of performance) string.

8.7. RGB object

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

8.7.1. Encoding

When a color is encoded as RGB object, the resulting object will contain the three number type properties red, green, and blue, reflecting the values of the source color's red, green, and blue channels.

EXAMPLES

color name  |  RGB object
-------------------------------------------
fuchsia     |  {red:255,green:0,blue:255}
yellow      |  {red:255,green:255,blue:0}
blue        |  {red:0,green:0,blue:255}
white       |  {red:255,green:255,blue:255}

8.7.2. Decoding

When a color is decoded from RGB object, the values of the object's red, green, and blue properties may be numbers, strings, or any object that implements a valueOf interface interface (such as an instance of a Uize subclass that implements the value set-get property).

EXAMPLES

{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}

NOTES

	the values of the color components will be coerced to number type by invoking the `valueOf Intrinsic Method`
	the property names of the source `RGB object` must be all lowercase

8.8. RGB string

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

8.8.1. Encoding

When a color is encoded as RGB string, the resulting string will always be all lowercase, without any spaces, and the values of the red, green, and blue components will be rounded and constrained to the range of 0 to 255.

EXAMPLES

color name  |  RGB string
-------------------------------
fuchsia     |  rgb(255,0,255)
yellow      |  rgb(255,255,0)
blue        |  rgb(0,0,255)
white       |  rgb(255,255,255)

8.8.2. Decoding

When a color is decoded from RGB string, the string may contain separating spaces, and may be in upper, lower, or mixed case (ie. not case sensitive).

FUCHSIA

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

8.9. HSL array

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

8.9.1. Encoding

When a color is encoded as HSL array, the resulting array is made up of three number type elements that represent the values of the source color's hue, saturation, and lightness, respectively.

EXAMPLES

color name  |  HSL array
---------------------------
fuchsia     |  [300,100,50]
yellow      |  [60,100,50]
blue        |  [240,100,50]
white       |  [0,0,100]

8.9.2. Decoding

When a color is decoded from HSL array, the values of the array's three elements may be numbers, strings, or any object that implements a valueOf interface interface (such as an instance of a Uize subclass that implements the value set-get property).

EXAMPLES

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

NOTES

	the values of the color components will be coerced to number type by invoking the `valueOf Intrinsic Method`
	string values for the saturation and lightness components in the array may not contain a "%" (percent) suffix

8.10. HSL object

An object, containing hue, saturation, and lightness properties, whose values may be floating point numbers (eg. 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

When a color is encoded as HSL object, the resulting object will contain the three number type properties hue, saturation, and lightness, reflecting the values of the source color's hue, saturation, and lightness.

EXAMPLES

color name  |  HSL object
----------------------------------------------------
fuchsia     |  {hue:300,saturation:100,lightness:50}
yellow      |  {hue:60,saturation:100,lightness:50}
blue        |  {hue:240,saturation:100,lightness:50}
white       |  {hue:0,saturation:0,lightness:100}

8.10.2. Decoding

When a color is decoded from HSL object, the values of the object's hue, saturation, and lightness properties may be numbers, strings, or any object that implements a valueOf interface interface (such as an instance of a Uize subclass that implements the value set-get property).

EXAMPLES

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

NOTES

	the values of the color components will be coerced to number type by invoking the `valueOf Intrinsic Method`
	string values for the saturation and lightness components in the array may not contain a "%" (percent) suffix
	the property names of the source `RGB object` must be all lowercase

8.11. HSL string

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

8.11.1. Encoding

When a color is encoded as HSL string, the resulting string will always be all lowercase, without any spaces.

Furthermore, the values for hue, saturation, and lightness will be rounded to the nearest integer, and a "%" (percent symbol) character will be appended to the values for saturation and lightness.

EXAMPLES

color name  |  HSL string
--------------------------------
fuchsia     |  hsl(300,100%,50%)
yellow      |  hsl(60,100%,50%)
blue        |  hsl(240,100%,50%)
white       |  hsl(0,0%,100%)

NOTES

because encoding as HSL string rounds the values for hue, saturation, and lightness, colors encoded as HSL string may not produce exactly the same original color when decoding the encoded HSL string

8.11.2. Decoding

When a color is decoded from HSL string, the string may contain separating spaces, may be in upper, lower, or mixed case (ie. not case sensitive), and the "%" (percent symbol) character for the saturation and lightness values may be omitted.

FUCHSIA

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

8.12. Defining New Color Encodings

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...

	`colorSpace` - This is the name of the color space that is associated with the encoding, and should be one of the Color Spaces defined in the `Uize.Color.colorSpaces` static property.
	`from (decoder function)` - This is a function that should set the values of the elements of the provided tuple array, based upon the provided color value. The function should expect two parameters: 1) the color value, and 2) the tuple. The function should decode (ie. process or parse) the color value as needed in order to set the appropriate values for the components of the color in the provided tuple array. The function does not need to return anything, and anything it returns will be ignored.
	`to (encoder function)` - This is a function that should use the values for the components of the color in the provided tuple array, and encode them as needed in order to produce a color value. The encoded color value should then be returned by the function.

9. Named Colors

The Uize.Color object defines a set of seventeen standard named colors (as defined in the CSS 2.1 color specification) in the Uize.Color.colors object.

COLOR NAME  |  HEX VALUE
------------------------
white       |   #ffffff
silver      |   #c0c0c0
gray        |   #808080
black       |   #000000
navy        |   #000080
blue        |   #0000ff
aqua        |   #00ffff
teal        |   #008080
green       |   #008000
olive       |   #808000
lime        |   #00ff00
maroon      |   #800000
red         |   #ff0000
orange      |   #ffa500
yellow      |   #ffff00
purple      |   #800080
fuchsia     |   #ff00ff

9.1. Using Named Colors

EXAMPLE 1

var myColor = new 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.

9.2. Additional Named Colors

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.

9.3. Defining New Named Colors

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'});

When extending the Uize.Color.colors object, the names of added colors should be in all lowecase, and the values should be specified in the RGB int encoding (you can use JavaScript's hexadecimal notation for convenience, so that the RGB int encoding resembles the hex or #hex encodings).

WRONG! WRONG! WRONG!

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

CORRECT

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

NOTES

	see the related `Uize.Color.colors` static property
	see the related `Uize.Color.defineColors` static method
	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

10. Deprecated Features

10.1. Uize.Color.RgbColor -- DEPRECATED 2009-04-17

This object has been deprecated in favor of the Uize.Color object.

INSTEAD OF...

myColor = new Uize.Color.RgbColor (redINT,greenINT,blueINT);

USE...

myColor = new Uize.Color (redINT,greenINT,blueINT);

The Constructor of the Uize.Color object lets you specify initial color in a much wider variety of Color Encodings than the constructor of the deprecated Uize.Color.RgbColor object.

10.2. Uize.Color.blendHex -- DEPRECATED 2009-04-20

This method has been deprecated in favor of the more versatile Uize.Color.blend static method that is implemented in the Uize.Color.xUtil extension module.

INSTEAD OF...

colorHexSTR = Uize.Color.blendHex (color1HexSTR,color2HexSTR,blendFRACTION);

USE...

colorHexSTR = Uize.Color.blend (color1HexSTR,color2HexSTR,blendFRACTION);

Unlike the deprecated Uize.Color.blendHex static method, the Uize.Color.blend static method supports a wide variety of different Color Encodings.

10.3. Uize.Color.hexStrToRgb -- DEPRECATED 2009-04-20

This method has been deprecated in favor of the more versatile Uize.Color.to static method.

INSTEAD OF...

rgbOBJ = Uize.Color.hexStrToRgb (hexRgbSTR);

USE...

rgbOBJ = Uize.Color.to (hexRgbSTR,'RGB object');

The Uize.Color.to static method allows source color to be specified in a wide variety of different Color Encodings, and also allows the source color to be encoded to any of the supported encodings.

10.4. Uize.Color.mixColors -- MIGRATED 2009-04-19

This static method has been migrated to the Uize.Color.xUtil extension module, which implements it as Uize.Color.mix.

INSTEAD OF...

Uize.Color.mixColors (color1,color2,color3,...,colorN);

USE...

Uize.Color.mix ([color1,color2,color3,...,colorN]);

While the discontinued Uize.Color.mixColors static method required colors to be specified as objects containing red, green, and blue properties, the Uize.Color.mix methods supports a wide variety of different Color Encodings. Also, colors being mixed do not have to be in the sRGB color space, but may be in any of the supported Color Spaces.

10.5. Uize.Color.rgbFromStyleStr -- DEPRECATED 2009-04-02

This method has been deprecated and has been replaced by an improved version of the Uize.Color object with a more flexible Constructor that allows initial color to be specified in a wide variety of ways.

INSTEAD OF...

colorOBJ = Uize.Color.rgbFromStyleStr (styleColorSTR);

USE...

colorOBJ = new Uize.Color (styleColorSTR);

In addition to using the Constructor, there are two other methods for creating instances of the Uize.Color object, where you can specify the initial color in any of the many supported Color Encodings (see the section Creating Instances).

10.6. Uize.Color.rgbToHexStr -- DEPRECATED 2009-04-20

This method has been deprecated in favor of the more versatile Uize.Color.to static method.

INSTEAD OF...

hexRgbSTR = Uize.Color.rgbToHexStr (rgbOBJ);

USE...

hexRgbSTR = Uize.Color.to (rgbOBJ,'hex');

Or, for the variation of the deprecated Uize.Color.rgbToHexStr method that accepted the three parameters redINT, greenINT, and blueINT...

INSTEAD OF...

hexRgbSTR = Uize.Color.rgbToHexStr (redINT,greenINT,blueINT);

USE...

hexRgbSTR = Uize.Color.to ([redINT,greenINT,blueINT],'hex');

The Uize.Color.to static method allows source color to be specified in a wide variety of different Color Encodings, and also allows the source color to be encoded to any of the supported encodings.

10.7. Uize.Color.rgbToStyleStr -- DEPRECATED 2009-04-20

This static method has been deprecated in favor of the more versatile Uize.Color.to static method.

INSTEAD OF...

rgbColorStyleSTR = Uize.Color.rgbToStyleStr (colorOBJ);

USE...

rgbColorStyleSTR = Uize.Color.to (colorOBJ,'RGB string');

10.8. mix -- DEPRECATED 2009-04-18

This instance method has been deprecated in favor of the better named and more versatile blend instance method that is implemented in the Uize.Color.xUtil extension module.

INSTEAD OF...

myRgbColor.mix (rgbColor1,rgbColor2,blendFRACTION);

USE...

myRgbColor.blend (rgbColor1,rgbColor2,blendFRACTION);

While the deprecated mix instance method of the deprecated Uize.Color.RgbColor object required colors to be specified as objects containing red, green, and blue properties, the blend method of the Uize.Color object supports a wide variety of different Color Encodings. Also, colors being blended do not have to be in the sRGB color space, but may be in any of the supported Color Spaces.

10.9. setColor -- DEPRECATED 2009-04-19

This method has been deprecated in favor of the more versatile from instance method that offers many more ways for colors to be specified.

INSTEAD OF...

colorOBJ.setColor (colorANYTYPE);

USE...

colorOBJ.from (colorANYTYPE);

The from instance method of the Uize.Color object supports a much wider variety of Color Encodings than the deprecated setColor method.

10.10. setHex -- DEPRECATED 2009-04-16

This method has been deprecated and has been replaced by the more versatile from instance method that offers many more ways for colors to be specified.

INSTEAD OF...

colorOBJ.setHex (hexRgbSTR);

USE...

colorOBJ.from (hexRgbSTR);

Unlike the deprecated setHex method, the from method supports a wide variety of different Color Encodings.

10.11. toHex -- DEPRECATED 2009-04-19

This instance method has been deprecated in favor of the more versatile to instance method.

INSTEAD OF...

hexRgbSTR = colorOBJ.toHex ();

USE...

hexRgbSTR = colorOBJ.to ('hex');

Unlike the deprecated toHex method, the to method supports a wide variety of different Color Encodings.

MODULES Uize.Color

SEARCHEXAMPLESVIEW SOURCE CODE

1. Introduction

1.1. Not a Uize Subclass

1.2. 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

1.3. Creating Instances

1.3.1. Using the Constructor

1.3.2. Using the Uize.Color.from Static Method

1.3.3. Using the Uize.Color.to Static Method

2. Constructor

3. Instance Properties

3.1. encoding

3.2. tuple

4. Instance Methods

4.1. from

4.2. getTuple

4.3. setEncoding

4.4. to

5. Static Methods

5.1. Uize.Color.cloneTuple

5.2. Uize.Color.defineColors

5.3. Uize.Color.from

5.3.1. A Tip on Preserving Encoding

5.4. Uize.Color.setTuple

5.5. Uize.Color.setTupleFromArray

5.6. Uize.Color.setTupleFromString

5.7. Uize.Color.to

6. Static Properties

6.1. Uize.Color.colorSpaces

6.2. Uize.Color.colors

6.3. Uize.Color.encodings

7. Color Spaces

7.1. sRGB

7.2. HSL

7.3. Additional Color Spaces

7.4. Defining New Color Spaces

8. Color Encodings

8.1. color

8.1.1. Encoding

8.1.2. Decoding

8.2. hex

8.2.1. Encoding

8.2.2. Decoding

8.3. #hex

8.3.1. Encoding

8.3.2. Decoding

8.4. name

8.4.1. Encoding

8.4.2. Decoding

8.5. RGB array

8.5.1. Encoding

8.5.2. Decoding

8.6. RGB int

8.6.1. Encoding

8.6.2. Decoding

8.7. RGB object

8.7.1. Encoding

8.7.2. Decoding

8.8. RGB string

8.8.1. Encoding

8.8.2. Decoding

8.9. HSL array

8.9.1. Encoding

8.9.2. Decoding

8.10. HSL object

8.10.1. Encoding

8.10.2. Decoding

8.11. HSL string

8.11.1. Encoding

8.11.2. Decoding

8.12. Defining New Color Encodings

9. Named Colors

9.1. Using Named Colors

9.2. Additional Named Colors

9.3. Defining New Named Colors

10. Deprecated Features

SEARCH EXAMPLES VIEW SOURCE CODE