Kiwi.Utils.Color Class
Utility class used to make color management more transparent. Color objects hold color and alpha values, and can get or set them in a variety of ways.
Construct this object in one of the following ways.
Pass 3 or 4 numbers to determine RGB or RGBA. If the numbers are in the range 0-1, they will be parsed as normalized numbers. If they are in the range 1-255, they will be parsed as 8-bit channels.
Pass 3 or 4 numbers followed by the string "hsv" or "hsl" (lowercase) to parse HSV or HSL color space (with optional alpha). HSV and HSL colors may be specified as normalized parameters (0-1), or as an angle (0-360) and two percentages (0-100).
Pass a string containing a hexadecimal color with or without alpha (such as "ff8040ff" or "4080ff"). You may prepend "#" or "0x", but they are not necessary and will be stripped.
Pass a string containing a CSS color function, such as "rgb(255,255,255)", "rgba( 192, 127, 64, 32 )", "hsl(180, 100, 100)", or "hsla(360, 50, 50, 50)".
Pass 1 number to set a grayscale value, or 2 numbers to set grayscale with alpha. These are interpreted as with RGB values.
The color object stores its internal values as normalized RGBA channels. This is the most mathematically useful format, and corresponds with the WebGL color paradigm. When you query the color object's values, such as with "r" or "red" properties, it will return normalized values. You can get values in the 0-255 8-bit range by calling the corresponding x255 value. For example, if r = 1, then r255 = 255.
We advise that you work with normalized colors wherever possible. While the Color object is smart enough to recognise non-normalized ranges in most cases, it cannot tell the difference between 0.5 on a 0-1 scale, and 0.5 on a 0-255 scale. Try to reduce ambiguity by working in normalized color space.
You can get HSV, HSL, and hexadecimal values with the functions "getHsva", "getHsla", and "getHex". By default, these all include an alpha term. You can omit alpha from the getHex result by calling the function with the parameter "false". As getHsva and getHsla return objects rather than strings, you can freely ignore the provided alpha.
You can modify a Color object once created using its properties, methods, or the "set" method as you would use the constructor.
Constructor
Kiwi.Utils.Color
-
[...args]
Parameters:
-
[...args]
Object optionalAny number of arguments
Item Index
Methods
_hue2rgb
-
p
-
q
-
t
Method used for computing HSL values. Based on algorithms at http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c
Parameters:
-
p
Number -
q
Number -
t
Number
Returns:
number
getHex
-
[alpha=true]
Returns color as a hexadecimal string
Parameters:
-
[alpha=true]
Boolean optionalWhether to include the alpha
Returns:
A hexadecimal color such as "13579bdf"
getHsla
()
Object
public
Returns HSL value of the Color. Based on algorithms at http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c
Returns:
Object with normalized h, s, l, a properties.
getHsva
()
Object
Returns HSV value of the Color. Based on algorithms at http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c
Returns:
Object with normalized h, s, v, a properties.
parseHex
-
color
Parse hexadecimal colors from strings
Parameters:
-
color
StringA hexadecimal color such as "ffffff" (no alpha) or "ffffffff" (with alpha). Also supports "fff" and "ffff" with 4-bit channels.
Returns:
This object with the new color set
parseHsl
-
h
-
s
-
l
-
a
Parses HSL value onto the Color. Interprets either normalized values, or H in degrees (0-360) and S and L in % (0-100).
Based on algorithms at http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c
Parameters:
-
h
NumberHue
-
s
NumberSaturation
-
l
NumberLightness
-
a
NumberAlpha
Returns:
This object with the new color set
parseHsv
-
h
-
s
-
v
-
a
Parses normalized HSV values into the Color. Interprets either normalized values, or H in degrees (0-360) and S and V in % (0-100).
Based on algorithms at http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c
Parameters:
-
h
NumberHue
-
s
NumberSaturation
-
v
NumberValue
-
a
NumberAlpha
Returns:
This object with the new color set
parseString
-
color
Parse colors from strings
Parameters:
-
color
StringA CSS color specification
Returns:
This object with the new color set
set
-
params
Set colors from parameters, as in the class description. If you supply invalid parameters, the color will be unchanged.
Parameters:
-
params
ObjectComposite parameter object
Returns:
This object with the new color set
Properties
_a
Number
private
Alpha channel, stored as a normalized value between 0 and 1. This is most compatible with graphics hardware.
Default: 0.5
_b
Number
private
Blue channel, stored as a normalized value between 0 and 1. This is most compatible with graphics hardware.
Default: 0.5
_g
Number
private
Green channel, stored as a normalized value between 0 and 1. This is most compatible with graphics hardware.
Default: 0.5
_r
Number
private
Red channel, stored as a normalized value between 0 and 1. This is most compatible with graphics hardware.
Default: 0.5
a
Number
public
Alpha channel. If set to a number in the range 0-1, is interpreted as a normalized color (see aNorm). If set to a number above 1, is interpreted as an 8-bit channel (see a255). If queried, returns a normalized number in the range 0-1.
a255
Number
public
Alpha channel, specified as an 8-bit channel in the range 0-255.
alpha
Number
public
Alpha channel, alias of a
aNorm
Number
public
Alpha channel, stored as a normalized value between 0 and 1.
b
Number
public
Blue channel. If set to a number in the range 0-1, is interpreted as a normalized color (see bNorm). If set to a number above 1, is interpreted as an 8-bit channel (see b255). If queried, returns a normalized number in the range 0-1.
b255
Number
public
Blue channel, specified as an 8-bit channel in the range 0-255.
blue
Number
public
Blue channel, alias of b
bNorm
Number
public
Blue channel, stored as a normalized value between 0 and 1.
g
Number
public
Green channel. If set to a number in the range 0-1, is interpreted as a normalized color (see gNorm). If set to a number above 1, is interpreted as an 8-bit channel (see g255). If queried, returns a normalized number in the range 0-1.
g255
Number
public
Green channel, specified as an 8-bit channel in the range 0-255.
gNorm
Number
public
Green channel, stored as a normalized value between 0 and 1.
green
Number
public
Green channel, alias of g
r
Number
public
Red channel. If set to a number in the range 0-1, is interpreted as a normalized color (see rNorm). If set to a number above 1, is interpreted as an 8-bit channel (see r255). If queried, returns a normalized number in the range 0-1.
r255
Number
public
Red channel, specified as an 8-bit channel in the range 0-255.
red
Number
public
Red channel, alias of r
rNorm
Number
public
Red channel, stored as a normalized value between 0 and 1.