Tagged literals

This feature is based on tagged templates from ES2016.

It allow constructing color objects using one of the available tags listed below in a quick and easy manner.

Skipped notation part?

You can always find it here.

Instead of introduction

If you are too lazy to read the documentation on tagged template literals from ES2016, I'm here to help you with this short introduction.

About tagged literals

Some general information on how to pass parameters to tagged literals is available here.

For all tags except qolor and color the following rules apply:

1. String parts are ignored. The following literals are equal:

   argb`${0.5}${0.5}${0}${1}`
   

   argb`a:${0.5} r:${0.5} g:${0} b:${1}`
   

2. Previous rule means the literals can be multiline. These are equal:

   argb`${0.5}${0.5}${0}${1}`
   

   argb`
       a:${0.5}
       r:${0.5} g:${0} b:${1}
   `
   

   argb`
       alpha: ${1/2}
       red:   ${1/2}
       green: ${ 0 }
       blue:  ${ 1 }
   `
   

3. Every parameter is an expression, so it can contain calculations or any other code. These are equal:

   argb`${0.5}${0.5}${0}${1}`
   

   const anotherElementOpacity = 1.0
   const r = 0.5
   const g = 0.0
   const b = 1.0
   
   argb`${anotherElementOpacity / 2} ${r} ${g} ${b}`
   

4. If a parameter has some default value, it can be omitted. The following literals are equal:

   rgba`${0.5}${0}${1}${1}`
   

   rgba`${0.5}${0}${1}`
   

List of available tags

The first two tags—qolor and color—are trying to cover 80% of needs of an average user of the library by using a multi-step heuristics approach.

If you need to construct a color using a precise form, please, see argb, argb32, hsla, hsva, hwba, rgba, or rgba32 below.

qolor

Alias:

q

(various types) → qolor

• (name: color-name) → qolor
• (#aarrggbb|#rrggbb|#argb|#rgb: color-literal) → qolor
• (a = 255, r, g, b: 8bit) → qolor

This tag tries to construct a Qt color based on the following magic (order matters):

1. Treat the resulting string as color name.
2. Treat the resulting string as color literal.
3. Treat the template parameters as ARGB32.
4. Treat the template parameters as RGB24
5. If nothing works, return undefined.

Examples:

Color names

q`indigo`  // ⇒ #4b0082
q`yellow`  // ⇒ #ffff00

const fish = 'salmon'
q`dark${fish}`  // ⇒ #e9967a AKA darksalmon

Color literals

q`#789`  // ⇒ #778899
q`#8000ff`  // ⇒ #8000ff
q`#ccff8000`  // ⇒ #ccff8000

(A)RGB32

q`${0xCC}${255}${128}${0}`  // ⇒ #ccff8000
q`${128}${0}${255}`  // ⇒ #8000ff

Beware the hash #!

If your literal starts with # and contains no spaces, it will be treated first as a regular color literal giving you most probably an unexpected result.

Let's consider an example:

q`${0x20}${0x00}${0xff}`  // ⇒ #2000ff

It contructs us exactly what we wanted: #2000ff. How? It first tries to match it as a color name, doesn't succeed, then tries to match as a regular color literal, again no success, and then it matches it as RGB24.

Now, let's look at and analyze the following:

q`#${0x20}${0x00}${0xff}`  // ⇒ #320255

We see that it's nearly the same except the hash sign # in the very beginning. And again, it tries to match agains color names first with no success, obviously.

However, then it tries to match it as a regular color literal. To do so, it needs to combine the parameters into a string:

1. First, let's convert hexadecimal numbers into decimal
   • 20₁₆ = 32₁₀
   • 0₁₆ = 0₁₀
   • FF₁₆ = 255₁₀
2. Then we combine a string as if it were a regular (not tagged) template as following: `#${32}${0}${255}`
3. The resulting string starts with # and contains exactly 6 digits, so it is treated as a color literal.
4. The #320255 is returned.

color

Alias:

cc

(various types) → color

• (name: color-name) → color
• (#aarrggbb|#rrggbb|#argb|#rgb: color-literal) → color
• (a = 255, r, g, b: 8bit) → color

The only difference to qolor tag is that this one creates an instance of the Color class instead of a regular Qt color. This class contains lots of useful methods and is far more superior in general. However, everthing comes with a price.

Color names

cc`indigo`  // ⇒ #4b0082
cc`yellow`  // ⇒ #ffff00

const fish = 'salmon'
cc`dark${fish}`  // ⇒ #e9967a AKA darksalmon

Color literals

cc`#789`  // ⇒ #778899
cc`#8000ff`  // ⇒ #8000ff
cc`#ccff8000`  // ⇒ #ccff8000

(A)RGB32

cc`${0xCC}${255}${128}${0}`  // ⇒ #ccff8000
cc`${128}${0}${255}`  // ⇒ #8000ff

argb

Type:

(alpha, red, green, blue: norm) → qolor

Creates a color from ARGB parameters.

If this tag can't construct a color from literal's parameters, an exception is raised.

Examples:

argb`${0.5} ${0.5} ${0} ${1}`  // ⇒ #808000ff

argb`${80['%']} ${1} ${0.5} ${0}`  // ⇒ #ccff8000

argb32

Type:

(alpha, red, green, blue: 8bit) → qolor

Creates a color from ARGB parameters.

If this tag can't construct a color from literal's parameters, an exception is raised.

Examples:

argb32`${128} ${128} ${0} ${255}`  // ⇒ #808000ff

argb32`${0x80} ${0.5.byte} ${0} ${0xFF}`  // ⇒ #808000ff

argb32`${204} ${255} ${128} ${0}`  // ⇒ #ccff8000

hsla

Type:	(hue, saturation, lightness, alpha = 1.0: norm) → qolor
Alias:	hsl

Creates a color from HSLA parameters.

If this tag can't construct a color from literal's parameters, an exception is raised.

Examples:

hsla`${0.75} ${1} ${0.5} ${0.5}`  // ⇒ #808000ff

hsla`
    hue: ${270 .deg}
    saturation: ${100 .percent}
    lightness: ${50 .percent}
    alpha: ${50 .percent}
`  // ⇒ #808000ff

hsla`${30['°']} ${100['%']} ${50['%']} ${0xCC.int}`  // ⇒ #ccff8000

(no alpha):

hsl`${211 .deg} ${100 .percent} ${36 .percent}`  // ⇒ #0057b7
hsl`${ 51 .deg} ${100 .percent} ${50 .percent}`  // ⇒ #ffd700

hsva

Type:	(hue, saturation, value, alpha = 1.0: norm) → qolor
Alias:	hsv

Creates a color from HSVA parameters.

If this tag can't construct a color from literal's parameters, an exception is raised.

Examples:

hsva`${0.75} ${1} ${1} ${0.5}`  // ⇒ #808000ff

hsva`
    hue: ${270 .deg}
    saturation: ${100 .percent}
    value: ${100 .percent}
    alpha: ${50 .percent}
`  // ⇒ #808000ff

hsva`${30['°']} ${100['%']} ${100['%']} ${0xCC.int}`  // ⇒ #ccff8000

(no alpha):

hsv`${211 .deg} ${100 .percent} ${ 72 .percent}`  // ⇒ #0057b7
hsv`${ 51 .deg} ${100 .percent} ${100 .percent}`  // ⇒ #ffd700

hwba

Type:	(hue, whiteness, blackness, alpha = 1.0: norm) → qolor
Alias:	hwb

Creates a color from HWBA parameters.

If this tag can't construct a color from literal's parameters, an exception is raised.

Examples:

hwba`${0.75} ${0} ${0} ${0.5}`  // ⇒ #808000ff

hwba`
    hue: ${270 .deg}
    blackness: ${0 .percent}
    whiteness: ${0 .percent}
    alpha: ${50 .percent}
`  // ⇒ #808000ff

hwba`${30['°']} ${0['%']} ${0['%']} ${0xCC.int}`  // ⇒ #ccff8000

(no alpha):

hwb`${211 .deg} ${0 .percent} ${ 28 .percent}`  // ⇒ #0057b7
hwb`${ 51 .deg} ${0 .percent} ${  0 .percent}`  // ⇒ #ffd700

rgba

Type:	(red, green, blue, alpha = 1.0: norm) → qolor
Alias:	rgb

Creates a color from RGBA parameters.

If this tag can't construct a color from literal's parameters, an exception is raised.

Examples:

rgba`${0.5} ${0} ${1} ${0.5}`  // ⇒ #808000ff

rgba`${1} ${0.5} ${0} ${80['%']}`  // ⇒ #ccff8000

(no alpha):

rgb`${0} ${87 .int} ${0.72}`  // ⇒ #0057b7
rgb`${1} ${0xD7.int} ${0}`  // ⇒ #ffd700

rgba32

Type:	(red, green, blue, alpha = 255: 8bit) → qolor
Alias:	rgb24

Creates a color from RGBA parameters.

If this tag can't construct a color from literal's parameters, an exception is raised.

Examples:

rgba32`${128} ${0} ${255} ${128}`  // ⇒ #808000ff

rgba32`${0xFF} ${0x80} ${0x00} ${0xCC}`  // ⇒ #ccff8000

(no alpha):

rgb24`${0} ${87} ${183}`  // ⇒ #0057b7
rgb24`${255} ${215} ${0}`  // ⇒ #ffd700