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

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

static functions

defaultColor()

fromHsv(const Tui::ZColorHSV &hsv)

fromHsv(double hue, double saturation, double value)

fromHsvStrict(double hue, double saturation, double value)

fromHsvStrict(const Tui::ZColorHSV &hsv)

fromRgb(int r, int g, int b)

fromTerminalColor(TerminalColor color)

fromTerminalColor(int color)

fromTerminalColorIndexed(int color)

functions

blue() const

blueOrGuess() const

green() const

greenOrGuess() const

nativeValue() const

red() const

redOrGuess() const

setBlue(int blue)

setGreen(int green)

setRed(int red)

terminalColor() const

terminalColorIndexed() const

toHsv() const

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.