terminology/COLORSCHEMES.md

Color Schemes in Terminology

Terminology uses color schemes to define the usual colors used by terminal applications, and a bit more: color schemes can also have an impact on the theme used.

Configuration file

The colorschemes are stored in EET format for speed up and ease of development. This format being a bit cumbersome to edit, color schemes can be edit in an easy INI format described below.

One can have a look at data/color_schemes/Default.ini for an example.

Organisation of the file

The INI format is made of sections, where the name appears in square brackets ([ and ]), that contain keys. Every key has a name and a value, delimited by an equals sign (=).

Those value have 3 types:

• integers, mostly used to describe versions,
• strings, surrounded by double quotes (") or not,
• colors, described as hex color codes, with or without alpha channels, like #00ffcc or #00ff00aa.

Semicolons (;) at the beginning of the line indicate a comment.

The color scheme file contains the following sections that are mandatory: Main, Metadata, Colors, Normal, Bright, Faint and BrightFaint.

Main

This section has only one field version with a default of 1. In case the format has to change, this value will change.

Metadata

This describes everything that is related to the color scheme but is not actually a color! The fields are the following:

• version: an integer, this is the version of the color scheme itself
• name is the name of the color scheme. It is expected to be the same as the file name without the .ini extension
• author: who made this color scheme
• website
• license: the short code of an opensource-approved license as listed on https://spdx.org/licenses/

Colors

This section describes colors used in the UI. The fields are:

• bg: the background color of the terminal
• main: this color is used as the main color for cursor and various effects on the terminal, like change of border on focus …
• hl: a color used for an object or text when being highlighted. Usually surrounded by the main color.
• end_sel: on selections, the color of the handles used to expand or shrink the area of the selection
• tab_missed_1, tab_missed_2, tab_missed_3: the main color, the outline color and the shadow color of the number of tabs where a bell has rung, tabs that need attention.
• tab_missed_over_1, tab_missed_over_2, tab_missed_over_3: same as before but when the mouse is over that number
• tab_title_2: the outline color of the active tab title. The foreground used is Normal.def and the shadow is bg.

Normal, Bright, Faint, BrightFaint

All those sections offer the same set of colors. Normal are the base colors. Bright are a brighter version of the Normal colors, while Faint are a dimer version of the Normal colors. Finally, BrightFaint are a dimer version of the Bright colors.

They all have those fields:

• def: the default foreground color
• black, red, green, yellow, blue, magenta, cyan and white are self-explanatory
• inverse_fg and inverse_fg are the colors used when espace codes are used to reverse background and foreground. Sometimes used to display selections by the terminal applications

How to add a new color scheme

First, one has to write a color scheme file as described above. Let's say we are creating the color scheme FooBar stored in file FooBar.ini.

The Faint and BrightFaint version can be generated by using the gen_faint.py script stored in data/color_schemes/ as seen below: gen_faint.py FooBar.ini

What this script does is to pick the colors from Normal and Bright and merge them with the background color (Colors.bg) in a 70/30 proportion. This proportion is configurable, like this for a 80/20 proportion: gen_faint.py FooBar.ini 80

Now that we are happy with the content of FooBar.ini, we can call the script add_color_scheme.sh stored in data/color_schemes/ as seen below: add_color_scheme.sh eet ~/.config/terminology/colorschemes/FooBar.eet FooBar.ini

Now you should be able to select your color scheme in Terminology!