billiob pushed a commit to branch master. http://git.enlightenment.org/apps/terminology.git/commit/?id=81943d470f0e06ecb4d5d8f919632db9f3af7b75
commit 81943d470f0e06ecb4d5d8f919632db9f3af7b75 Author: Boris Faure <[email protected]> Date: Sun Nov 22 12:26:14 2020 +0100 add documentation on color schemes --- COLORSCHEMES.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 25 +++++++++--- THEME.md => THEMES.md | 45 +++++++++++++++++++- 3 files changed, 173 insertions(+), 8 deletions(-) diff --git a/COLORSCHEMES.md b/COLORSCHEMES.md new file mode 100644 index 0000000..84844bd --- /dev/null +++ b/COLORSCHEMES.md @@ -0,0 +1,111 @@ +# 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 > FooBar_with_faint.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 > FooBar_with_faint.ini` + +Now that we are happy with the content of `FooBar_with_faint.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.eet FooBar_with_faint.ini` + +Now you should be able to select your color scheme in Terminology! + + diff --git a/README.md b/README.md index a3813aa..367211a 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,25 @@ Note: to make terminology work with input methods in general you need: ``` +Themes +------ + +Apart from the ones shipped with Terminology, themes can be stored in +`~/.config/terminology/themes/` . + +Documentation on themes is written in [THEMES.md](THEMES.md). + + +Color Schemes +------------- + +Terminology ships with some common color schemes. + +To know how to modify or add some new color schemes, please read +[COLORSCHEMES.md](COLORSCHEMES.md). + + + Mouse controls -------------- @@ -111,12 +130,6 @@ Default key controls -Themes ------- - -Apart from the ones shipped with Terminology, themes can be stored in -`~/.config/terminology/themes/` . - Companion tools --------------- diff --git a/THEME.md b/THEMES.md similarity index 74% rename from THEME.md rename to THEMES.md index d29338b..a61bef7 100644 --- a/THEME.md +++ b/THEMES.md @@ -1,13 +1,54 @@ +# Themes in Terminology + This document describes how Terminology interacts with themes and what needs to be handled by themes. See `ChangeLog.theme` on changes related to themes. +# Color classes + +Based on the chosen color scheme, Terminology sets the following color classes +on all the following edje groups: + +* `BG`: the background color of the terminal +* `FG`: the default foreground color +* `CURSOR`: the color of the cursor +* `GLOW`: the color in the UI to ouline elements +* `HIGHLIGHT`: the color used as main color when an elemeent is highlighted +* `GLOW_TXT`: text colors with some glow +* `GLOW_TXT_HIGHLIGHT`: text with glow that is highlighted +* `END_SELECTION`: on selections, the color of the handles used to expand or shrink + the area of the selection +* `TAB_MISSED`: the number of tabs where a bell has rung, tabs that need + attention +* `TAB_MISSED_OVER`: same but when the mouse is over that number +* `TAB_TITLE`: the colors of the active tab title +* `BG_SENDFILE` is the background color when there is a sendfile action. See + `man tysend`. It is set to `#404040`. + +The following table explains how color classes are set from color scheme +values: + +| Color Class | Object color | Outline color | Shadow color | +| -------------------- | ---------------- | ---------------- | ------------- | +| `BG` | `Colors.bg` | `Colors.bg` | `Colors.bg` | +| `FG` | `Normal.def` | `Normal.def` | `Normal.def` | +| `CURSOR` | `Colors.main` | `Colors.main` | `Colors.main` | +| `GLOW` | `Colors.main` | `Colors.main` | `Colors.main` | +| `GLOW_TXT_HIGHLIGHT` | `Colors.hl` | `Colors.main` | `Colors.main` | +| `END_SELECTION` | `Colors.end_sel` | `Colors.end_sel` | `Colors.end_sel` | +| `TAB_MISSED` | `Colors.tab_missed_1` | `Colors.tab_missed_2` | `Colors.tab_missed_3` | +| `TAB_MISSED_OVER` | `Colors.tab_missed_1` | `Colors.tab_missed_2` | `Colors.tab_missed_3` | +| `TAB_TITLE` | `Normal.def` | `Colors.tab_title_2` | `Colors.bg` | +| `BG_SENDFILE` | `#404040` | `#404040` | `#404040` | + + + +Let's dive into the edje groups that Terminology uses. +# `terminology/base` Windows contain group `terminology/base`. - -# `terminology/base` Contains what is global to a window. ## Swallowed parts --
