Skip to content

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 FF16 (= 25510).
  • 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}.