ZColor

Color handling in terminals works in distinct color kinds:

  • default color

  • named colors

  • indexed colors

  • rgb/direct colors

The default color further has the special property that it is displayed differently when uses as foreground color versus background color. That is using the default color as both foreground and background color usually yields readable high contrast text. The default color is often configurable separatly for the user of the terminal.

The named colors are 8 basic colors plus their bright variants. Terminal usually allow users to configure these colors and many users make use of that configability.

The indexed colors are divided into 3 parts. Color indicies 0-15 often correspond to the named colors, possible with some differences in handling (i.e. bright named colors might default to bold, while the same indicies might not use auto bold). The following color indicies are usually divided into a color cube and a ramp of grey tones.

The rgb colors allow direct usage of given rgb color values. The colors use 8 bit resolution for each color channel. But of course some terminals internally use lower resolution. If Tui Widgets knows the terminal does not support rgb color it internally translates them to indexed colors, because most terminals support those.

Of course terminals differ in support for color kinds. Also in some situations users expect the application to use named colors to fit with their selected color theming. Thus Tui Widgets exposes all color kinds discussed above and lets the application select which colors to use. Although the default palette uses rgb colors and the automatic conversion.

If the application uses RGB colors, it can additionally use the Tui::ZColorHSV class to ease calculation of related colors.

enum Tui::TerminalColor

The TerminalColor enum represents the named terminal colors.

enumerator black
enumerator darkGray
enumerator lightGray
enumerator brightWhite
enumerator blue
enumerator green
enumerator cyan
enumerator red
enumerator magenta
enumerator yellow
enumerator brightBlue
enumerator brightGreen
enumerator brightCyan
enumerator brightRed
enumerator brightMagenta
enumerator brightYellow
named colors

enum

description

enum (bright)

description

black (0)

black

darkGray (8)

dark grey

red (1)

red

brightRed (9)

bright red

green (2)

green

brightGreen (10)

bright green

yellow (3)

yellow

brightYellow (11)

bright yellow

blue (4)

blue

brightBlue (12)

bright blue

magenta (5)

magenta

brightMagenta (13)

bright magenta

cyan (6)

cyan

brightCyan (14)

bright cyan

lightGray (7)

light gray

brightWhite (15)

white

The following RGB colors are predefined as constants for application use in Tui::Colors:

predefined rgb values

name

description

name (bright)

description

black

black (#000000)

darkGray

dark grey (#555555)

red

red (#aa0000)

brightRed

bright red (#ff5555)

green

green (#00aa00)

brightGreen

bright green (#55ff55)

yellow

yellow (#aaaa00)

brightYellow

bright yellow (#ffff55)

blue

blue (#0000aa)

brightBlue

bright blue (#5555ff)

magenta

magenta (#aa00aa)

brightMagenta

bright magenta (#ff55ff)

cyan

cyan (#00aaaa)

brightCyan

bright cyan (#55ffff)

lightGray

light gray (#aaaaaa)

brightWhite

white (#ffffff)

class Tui::ZColor

This class represents colors in Tui Widgets. It’s copyable, assignable and supports equality comparasion.

enum ColorType
enumerator RGB
enumerator Default
enumerator Terminal
enumerator TerminalIndexed

constructors

static functions

functions


ZColor(int r, int g, int b)

Creates an ZColor instance of type RGB using r, g and b as the color values.

Tui::ZColor::ColorType colorType() const

Returns the type of color the instance represents.

int red() const
void setRed(int red)
int green() const
void setGreen(int green)
int blue() const
void setBlue(int blue)

Only for colorType() == ColorType::RGB.

Getters and setters for RGB values. If the setters are used on a color of another type the type will be changed to RGB and all other channels are set to zero.

Use Tui::ZColor fromRgb(int r, int g, int b) to create a new instance with a specific rgb color.

int terminalColorIndexed() const

Only for colorType() == ColorType::TerminalIndexed.

Returns the index of the indexed color.

Use Tui::ZColor fromTerminalColorIndexed(int color) to create a new instance with a specific indexed color.

Tui::TerminalColor terminalColor() const

Only for colorType() == ColorType::Terminal.

Returns the enum value of the named color.

Use Tui::ZColor fromTerminalColor(TerminalColor color) to create a new instance with a specific named color.

int redOrGuess() const
int greenOrGuess() const
int blueOrGuess() const

Returns the color component for RGB type colors or a guess of the color component for other color types.

Tui::ZColorHSV toHsv() const

Returns the color converted to HSV. For non RGB type colors it uses guesses for the color like redOrGuess() const and co.

uint32_t nativeValue() const

Returns the color as a termpaint color value.

Tui::ZColor defaultColor()

Returns a ZColor with the default color.

Tui::ZColor fromRgb(int r, int g, int b)

Returns a ZColor with the RGB color with components r, g and b.

Tui::ZColor fromTerminalColor(TerminalColor color)

Returns a ZColor with the terminal color color.

Tui::ZColor fromTerminalColor(int color)

Returns a ZColor with the terminal color static_cast<Tui::TerminalColor>(color).

Tui::ZColor fromTerminalColorIndexed(int color)

Returns a ZColor with the indexed color color.

Tui::ZColor fromHsv(const Tui::ZColorHSV &hsv)

Returns a ZColor with RGB type converted from the HSV color hsv.

Tui::ZColor fromHsv(double hue, double saturation, double value)

Returns a ZColor with RGB type converted from the HSV color components hue, saturation and value.

The ranges for the components are:

  • 0 <= hue <= 360

  • 0 <= saturation <= 1

  • 0 <= value <= 1

Values outside are clipped for saturation and value. Values outside for hue are wrapped back into the allowed range.

Tui::ZColor fromHsvStrict(double hue, double saturation, double value)

Like fromHsv(double hue, double saturation, double value) but only valid if the parameters are in the allowed range.

Tui::ZColor fromHsvStrict(const Tui::ZColorHSV &hsv)

Like ZColorHSV &hsv) but only valid if the components in hsv are in the allowed range.

HSV

class Tui::ZColorHSV

ZColorHSV is a simple class to store a color as hue, saturation and value.

It’s copyable, assignable and supports equality comparasion.

double hue() const
void setHue(double hue)
double saturation() const
void setSaturation(double saturation)
double value() const
void setValue(double value)

All components have getters and setters.