# 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.