ColorDef Class

An immutable integer representation of a color.

A color consists of 4 components: Red, Blue, Green, and Transparency. Each component is an 8-bit unsigned integer in the range [0..255]. A value of zero means that component contributes nothing to the color: e.g., a color with Red=0 contains no shade of red, and a color with Transparency=0 is fully opaque. A value of 255 means that component contributes its maximum value to the color: e.g., a color with Red=255 is as red as it is possible to be, and a color with Transparency=255 is fully transparent.

Internally, these 4 components are combined into a single 32-bit unsigned integer as represented by ColorDefProps. This representation can result in some confusion regarding:

  1. The ordering of the individual components; and
  2. Whether to specify transparency or opacity (sometimes referred to as "alpha").

ColorDef uses 0xTTBBGGRR internally, which uses Transparency and puts Red in the low byte and Transparency in the high byte. It can be converted to 0xRRGGBB format (blue in the low byte) using ColorDef.getRgb and `0xAABBGGRRx format (red in the low byte, using opacity instead of transparency) using ColorDef.getAbgr.

A ColorDef can be created from a numeric ColorDefProps, from a string in one of the common HTML formats (e.g., ColorDef.fromString), or by specifying values for the individual components (e.g., ColorDef.from).

ColorDef is immutable. To obtain a modified copy of a ColorDef, use methods like ColorDef.adjustedForContrast, ColorDef.inverse, or ColorDef.withTransparency. For example:

 const semiTransparentBlue = ColorDef.blue.withTransparency(100);

Methods

Name Description
adjustedForContrast(other: ColorDef, alpha?: number): ColorDef Create a new ColorDef that is adjusted from this ColorDef for maximum contrast against another color.  
equals(other: ColorDef): boolean True if the value of this ColorDef is the same as another ColorDef.  
getAbgr(): number Get the value of the color as a number in 0xAABBGGRR format (i.e.  
getAlpha(): number Get the alpha value for this ColorDef.  
getRgb(): number Get the RGB value of the color as a number in 0xRRGGBB format (i.e blue is in the low byte).  
getTransparency(): number Get the transparency value for this ColorDef (inverse of alpha).  
inverse(): ColorDef Create a new ColorDef that is the inverse (all colors set to 255 - this) of this color.  
lerp(color2: ColorDef, weight: number): ColorDef Create a ColorDef that is the linear interpolation of this ColorDef and another ColorDef, using a weighting factor.  
toHSL(): HSLColor Create an HSLColor from this ColorDef  
toHSV(): HSVColor Create an HSVColor from this ColorDef  
toHexString(): string Convert this ColorDef to a string in the form "#rrggbb" where values are hex digits of the respective colors  
toJSON(): number Convert this ColorDef to a 32 bit number representing the 0xTTBBGGRR value  
toRgbString(): string Convert this ColorDef to a string in the form "rgb(r,g,b)" where values are decimal digits of the respective colors.  
toRgbaString(): string Convert this ColorDef to a string in the form "rgba(r,g,b,a)" where color values are decimal digits and a is a fraction  
withAlpha(alpha: number): ColorDef Return a copy of this ColorDef with the specified alpha component.  
withTransparency(transparency: number): ColorDef Create a copy of this ColorDef with the specified transparency.  
computeTbgr(val?: string | number): number Static Compute the 0xTTBBGGRR value corresponding to the specified representation of a color.  
computeTbgrFromComponents(red: number, green: number, blue: number, transparency?: number): number Static Compute the 0xTTBBGGRR value corresponding to the specified Red, Green, Blue, Transparency components.  
computeTbgrFromHSL(h: number, s: number, l: number, transparency: number = 0): number Static Compute the 0xTTBBGGRR color corresponding to the specified hue, saturation, lightness values.  
computeTbgrFromString(val: string): number Static Compute the 0xTTBBGGRR value corresponding to a string representation of a color.  
create(val?: string | number): ColorDef Static Create a new ColorDef.  
from(red: number, green: number, blue: number, transparency?: number): ColorDef Static Create a ColorDef from Red, Green, Blue, Transparency values.  
fromAbgr(abgr: number): ColorDef Static Create a ColorDef from its 0xAABBGGRR representation.  
fromHSL(h: number, s: number, l: number, transparency: number = 0): ColorDef Static Create a ColorDef from hue, saturation, lightness values  
fromHSV(hsv: HSVColor, transparency: number = 0): ColorDef Static Create a ColorDef from an HSVColor  
fromJSON(json?: number): ColorDef Static Create a new ColorDef from a json object.  
fromString(val: string): ColorDef Static Create a ColorDef from a string representation.  
fromTbgr(tbgr: number): ColorDef Static Create a ColorDef from its 0xTTBBGGRR representation.  
getAbgr(tbgr: number): number Static Get the value of a 0xTTBBGGRR color as a number in 0xAABBGGRR format (i.e.  
getAlpha(tbgr: number): number Static Extract the alpha value from a 0xTTBBGGRR color.  
getColors(tbgr: number): { b: number, g: number, r: number, t: number } Static Get the r,g,b,t values encoded in an 0xTTBBGGRR value.  
getName(tbgr: number): undefined | string Static Obtain the name of the color in the ColorByName list associated with the specified 0xTTBBGGRR value, or undefined if no such named color exists.  
getRgb(tbgr: number): number Static Get the RGB value of the 0xTTBBGGRR color as a number in 0xRRGGBB format (i.e blue is in the low byte).  
getTransparency(tbgr: number): number Static Extract the transparency component from a 0xTTBBGGRR color as an integer between 0-255..  
inverse(tbgr: number): number Static Return a 0xTTBBGGRR color whose color components are the inverse of the input color.  
isOpaque(tbgr: number): boolean Static True if the specified 0xTTBBGGRR color is fully opaque.  
isValidColor(val: string | number): boolean Static Determine whether the input is a valid representation of a ColorDef.  
lerp(tbgr1: number, tbgr2: number, weight: number): number Static Interpolate between two 0xTTBBGGRR colors using a weighting factor.  
toHexString(tbgr: number): string Static Convert the 0xTTBBGGRR value to a string in the form "#rrggbb".  
toRgbString(tbgr: number): string Static Convert the 0xTTBBGGRR color to a string in the form "rgb(r,g,b)" where each component is specified in decimal.  
toRgbaString(tbgr: number): string Static Convert the 0xTTBBGGRR color to a string of the form "rgba(r,g,b,a)" where the color components are specified in decimal and the alpha component is a fraction.  
tryComputeTbgrFromString(val: string): undefined | number Static Try to compute the 0xTTBBGGRR value corresponding to a string representation of a ColorDef.  
withAlpha(tbgr: number, alpha: number): number Static Return a color equivalent to the specified 0xTTBBGGRR but with modified alpha component.  
withTransparency(tbgr: number, transparency: number): number Static Compute the 0xTTBBGGRR value of the specified color and transparency.  

Properties

Name Type Description
black StaticReadonly ColorDef pure black  
blue StaticReadonly ColorDef pure blue  
colors Accessor ReadOnly { b: number, g: number, r: number, t: number } Get the red, green, blue, and transparency values from this ColorDef.  
green StaticReadonly ColorDef pure green  
isOpaque Accessor ReadOnly boolean True if this ColorDef is fully opaque.  
name Accessor ReadOnly undefined | string The "known name" for this ColorDef.  
red StaticReadonly ColorDef pure red  
tbgr Accessor ReadOnly number The color value of this ColorDef as an integer in the form 0xTTBBGGRR (red in the low byte)  
white StaticReadonly ColorDef pure white  

Defined in

Last Updated: 15 March, 2024