Basic concepts¶

Before I start explaining to you how to use the library, we need to agree on certain terminology.

Color models¶

This library supports several color models described below.

Alpha-channel

Each model may contain an additional optional alpha-channel that represents transparency (or, to be more precise, opacity). If so, the model's name contains the A letter as you'll see below.

RGB¶

Represents a color as a combination of Red, Green, and Blue components.

More details on Wikipedia.

Variants: RGB, ARGB, RGBA.

HSL¶

It's an alternative representation of a color in RGB color model that uses a combination of:

Hue $\in [0°, 360°]$
Saturation $\in [0\%, 100\%]$
Lightness $\in [0\%, 100\%]$

More details on Wikipedia.

Variants: HSL, HSLA.

HSV¶

It's an alternative representation of a color in RGB color model that uses a combination of:

Hue $\in [0°, 360°]$
Saturation $\in [0\%, 100\%]$
Value $\in [0\%, 100\%]$ (AKA brightness)

More details on Wikipedia.

Variants: HSV, HSVA.

HWB¶

It's an alternative representation of a color in RGB color model that uses a combination of:

Hue $\in [0°, 360°]$
Whiteness $\in [0\%, 100\%]$
Blackness $\in [0\%, 100\%]$

More details on Wikipedia.

Variants: HWB, HWBA.

Types¶

Color types¶

`color-name`¶

It's a string that contains one of the extended color keywords from CSS.

List of all names

Name	Color	HEX
aliceblue		`#f0f8ff`
antiquewhite		`#faebd7`
aqua		`#00ffff`
aquamarine		`#7fffd4`
azure		`#f0ffff`
beige		`#f5f5dc`
bisque		`#ffe4c4`
black		`#000000`
blanchedalmond		`#ffebcd`
blue		`#0000ff`
blueviolet		`#8a2be2`
brown		`#a52a2a`
burlywood		`#deb887`
cadetblue		`#5f9ea0`
chartreuse		`#7fff00`
chocolate		`#d2691e`
coral		`#ff7f50`
cornflowerblue		`#6495ed`
cornsilk		`#fff8dc`
crimson		`#dc143c`
cyan		`#00ffff`
darkblue		`#00008b`
darkcyan		`#008b8b`
darkgoldenrod		`#b8860b`
darkgray		`#a9a9a9`
darkgreen		`#006400`
darkgrey		`#a9a9a9`
darkkhaki		`#bdb76b`
darkmagenta		`#8b008b`
darkolivegreen		`#556b2f`
darkorange		`#ff8c00`
darkorchid		`#9932cc`
darkred		`#8b0000`
darksalmon		`#e9967a`
darkseagreen		`#8fbc8f`
darkslateblue		`#483d8b`
darkslategray		`#2f4f4f`
darkslategrey		`#2f4f4f`
darkturquoise		`#00ced1`
darkviolet		`#9400d3`
deeppink		`#ff1493`
deepskyblue		`#00bfff`
dimgray		`#696969`
dimgrey		`#696969`
dodgerblue		`#1e90ff`
firebrick		`#b22222`
floralwhite		`#fffaf0`
forestgreen		`#228b22`
fuchsia		`#ff00ff`
gainsboro		`#dcdcdc`
ghostwhite		`#f8f8ff`
gold		`#ffd700`
goldenrod		`#daa520`
gray		`#808080`
green		`#008000`
greenyellow		`#adff2f`
grey		`#808080`
honeydew		`#f0fff0`
hotpink		`#ff69b4`
indianred		`#cd5c5c`
indigo		`#4b0082`
ivory		`#fffff0`
khaki		`#f0e68c`
lavender		`#e6e6fa`
lavenderblush		`#fff0f5`
lawngreen		`#7cfc00`
lemonchiffon		`#fffacd`
lightblue		`#add8e6`
lightcoral		`#f08080`
lightcyan		`#e0ffff`
lightgoldenrodyellow		`#fafad2`
lightgray		`#d3d3d3`
lightgreen		`#90ee90`
lightgrey		`#d3d3d3`
lightpink		`#ffb6c1`
lightsalmon		`#ffa07a`
lightseagreen		`#20b2aa`
lightskyblue		`#87cefa`
lightslategray		`#778899`
lightslategrey		`#778899`
lightsteelblue		`#b0c4de`
lightyellow		`#ffffe0`
lime		`#00ff00`
limegreen		`#32cd32`
linen		`#faf0e6`
magenta		`#ff00ff`
maroon		`#800000`
mediumaquamarine		`#66cdaa`
mediumblue		`#0000cd`
mediumorchid		`#ba55d3`
mediumpurple		`#9370db`
mediumseagreen		`#3cb371`
mediumslateblue		`#7b68ee`
mediumspringgreen		`#00fa9a`
mediumturquoise		`#48d1cc`
mediumvioletred		`#c71585`
midnightblue		`#191970`
mintcream		`#f5fffa`
mistyrose		`#ffe4e1`
moccasin		`#ffe4b5`
navajowhite		`#ffdead`
navy		`#000080`
oldlace		`#fdf5e6`
olive		`#808000`
olivedrab		`#6b8e23`
orange		`#ffa500`
orangered		`#ff4500`
orchid		`#da70d6`
palegoldenrod		`#eee8aa`
palegreen		`#98fb98`
paleturquoise		`#afeeee`
palevioletred		`#db7093`
papayawhip		`#ffefd5`
peachpuff		`#ffdab9`
peru		`#cd853f`
pink		`#ffc0cb`
plum		`#dda0dd`
powderblue		`#b0e0e6`
purple		`#800080`
random		`???`
red		`#ff0000`
rosybrown		`#bc8f8f`
royalblue		`#4169e1`
saddlebrown		`#8b4513`
salmon		`#fa8072`
sandybrown		`#f4a460`
seagreen		`#2e8b57`
seashell		`#fff5ee`
sienna		`#a0522d`
silver		`#c0c0c0`
skyblue		`#87ceeb`
slateblue		`#6a5acd`
slategray		`#708090`
slategrey		`#708090`
snow		`#fffafa`
springgreen		`#00ff7f`
steelblue		`#4682b4`
tan		`#d2b48c`
teal		`#008080`
thistle		`#d8bfd8`
tomato		`#ff6347`
transparent		`#00000000`
turquoise		`#40e0d0`
violet		`#ee82ee`
wheat		`#f5deb3`
white		`#ffffff`
whitesmoke		`#f5f5f5`
yellow		`#ffff00`
yellowgreen		`#9acd32`

`color-literal`¶

A string in either form:

'#rgb'
'#argb'
'#rrggbb'
'#aarrggbb'

Every a, r, g, or b is a hex-digit, i.e. a value 0–9 or A–F (or a–f). They represent alpha, red, green, and blue correspondingly.

Expanding rules

The #aarrggbb is a full form and all other forms are expanded to it with the following rules:

If alpha is omitted, it equals to FF₁₆ (= 255₁₀).
In short form, every digit is doubled.

Examples

'#70f'       // ⇒ #ff7700ff
'#a789'      // ⇒ #aa778899
'#8000ff'    // ⇒ #ff8000ff
'#c0ff79bf'  // ⇒ #c0ff79bf

Qt color (`qolor`)¶

Qt Quick's color basic type. In this documentation I usually refer to it as qolor to distinguish from the Color class.

Read more about qolor vs color in the next chapter.

The Color class (`color`)¶

The bread-and-butter of this library is the Color class which provides all the interesting methods. Essentially, it's just a thin wrapper around qolor which provides some additional properties and methods.

Read more about qolor vs color in the next chapter.

Any type of color (`any-color`)¶

This is a union type that allows using any suitable way of constructing a color object.

Can be substituted with: color-name|color-literal|qolor|color.

Auxiliary types¶

`change-object`¶

This type is used only as a parameter of a single method change and corresponding function.

Every individual component of this object is of type norm.

The default value of each component is null (i.e. no change). This makes every component – optional!

The object itself contains:

alpha or a
one of the following:
- {rgb: {red, green, blue}}
  or {rgb: {r, g, b}}
- {hsl: {hue, saturation, lightness}}
  or {hsl: {h, s, l}}
- {hsv: {hue, saturation, value}}
  or {hsv: {h, s, v}}
- {hwb: {hue, whiteness, blackness}}
  or {hwb: {h, w, b}}

Valid examples

{alpha: 0.5, rgb: {r: 0.5, b: 1.0}}

{hsl: {hue: 270 .deg, saturation: 100 .percent}}

Invalid examples

// alpha is within rgb, but must be on the top level
{rgb: {r: 0.5, b: 1.0, a: 0.5}}

{
    // rgb and hsl can't be mixed within one object
    rgb: {red: 128 .int, blue: 255 .int}
    hsl: {hue: 270 .deg, saturation: 100 .percent}
}

`offset-object`¶

This type is used only as a parameter of two methods: adjust and scale and corresponding functions.

Essentially, it's the same as change-object but every individual component of this object is of type offset instead of norm.

The default value of each component is 0.0 (i.e. no change). This makes every component – optional!

The object itself contains:

alpha or a
one of the following:
- {rgb: {red, green, blue}}
  or {rgb: {r, g, b}}
- {hsl: {hue, saturation, lightness}}
  or {hsl: {h, s, l}}
- {hsv: {hue, saturation, value}}
  or {hsv: {h, s, v}}
- {hwb: {hue, whiteness, blackness}}
  or {hwb: {h, w, b}}

Valid examples

{alpha: +0.5, rgb: {r: +0.3, b: -0.2}}

{hsl: {hue: +30 .deg, saturation: -20 .percent}}

Invalid examples

// alpha is within rgb, but must be on the top level
{rgb: {r: +0.5, b: -1.0, a: +0.5}}

{
    // rgb and hsl can't be mixed within one object
    rgb: {red: +128 .int, blue: -128 .int}
    hsl: {hue: -45 .deg, saturation: -15 .percent}
}

Value ranges¶

Normalized real interval (`norm`)¶

$$ n \in [0, 1] $$ Almost all functions work with arguments that belong to the normalized interval. Also, all color components' values are stored internally as normalized real values.

For example, rgba(0.5, 0, 1, 1).

Normalized real offset interval (`offset`)¶

$$ r \in [-1, 1] $$ This one is mainly used to denote an offset/change of a normalized value.

For instance, {hsl: {saturation: -0.3}}.

Integer interval (`8bit`)¶

$$ u \in [0, 255] $$ This should be quite familiar for those coming from CSS where color components are specified using integers. Usually, functions, that work with such values, have suffix 24 or 32.

For example, rgb24(128, 0, 255).

Integer offset interval (`9bit`)¶

$$ s \in [-255, 255] $$ AFAIR, there are no functions that work with this interval, however, you can use such values, for instance, together with units.

Example: {alpha: -128 .int}.

Basic concepts¶

Color models¶

RGB¶

HSL¶

HSV¶

HWB¶

Types¶

Color types¶

color-name¶

color-literal¶

Qt color (qolor)¶

The Color class (color)¶

Any type of color (any-color)¶

Auxiliary types¶

change-object¶

offset-object¶

Value ranges¶

Normalized real interval (norm)¶

Normalized real offset interval (offset)¶

Integer interval (8bit)¶

Integer offset interval (9bit)¶

`color-name`¶

`color-literal`¶

Qt color (`qolor`)¶

The Color class (`color`)¶

Any type of color (`any-color`)¶

`change-object`¶

`offset-object`¶

Normalized real interval (`norm`)¶

Normalized real offset interval (`offset`)¶

Integer interval (`8bit`)¶

Integer offset interval (`9bit`)¶