refactor: refactor styling options (#1499)

Introduce a new configuration system for styling.

CHANGELOG.md

@@ -25,14 +25,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `expanded_on_startup` is now `expanded`.
   - `left_legend` is now `cpu_left_legend`.
 - [#1472](https://github.com/ClementTsang/bottom/pull/1472): The following arguments have changed names:
-  - `mem_as_value` is now `process_memory_as_value`.
+  - `--mem_as_value` is now `process_memory_as_value`.
 - [#1472](https://github.com/ClementTsang/bottom/pull/1472): The following config fields have changed names:
   - `mem_as_value` is now `process_memory_as_value`.
 - [#1481](https://github.com/ClementTsang/bottom/pull/1481): The following config fields have changed names:
   - `disk_filter` is now `disk.name_filter`.
   - `mount_filter` is now `disk.mount_filter`.
   - `temp_filter` is now `temperature.sensor_filter`
   - `net_filter` is now `network.interface_filter`
+- [#1499](https://github.com/ClementTsang/bottom/pull/1499): Redesign how styling is configured.
+- [#1499](https://github.com/ClementTsang/bottom/pull/1499): The following arguments have changed names:
+  - `--colors` is now `--theme`
 
 ### Bug Fixes
 

docs/content/configuration/command-line-options.md

@@ -86,7 +86,7 @@ see information on these options by running `btm -h`, or run `btm --help` to dis
 
 | Option                   | Behaviour                                  |
 | ------------------------ | ------------------------------------------ |
-| `--color <COLOR SCHEME>` | Use a color scheme, use `--help` for info. |
+| `--theme <COLOR SCHEME>` | Use a color scheme, use `--help` for info. |
 
 ## Other Options
 

docs/content/configuration/config-file/flags.md

@@ -35,7 +35,6 @@ each time:
 | `default_widget_type`        | String (one of ["cpu", "proc", "net", "temp", "mem", "disk"], same as layout options)                              | Sets the default widget type, use --help for more info.          |
 | `default_widget_count`       | Unsigned Int (represents which `default_widget_type`)                                                              | Sets the n'th selected widget type as the default.               |
 | `disable_click`              | Boolean                                                                                                            | Disables mouse clicks.                                           |
-| `color`                      | String (one of ["default", "default-light", "gruvbox", "gruvbox-light", "nord", "nord-light"])                     | Use a color scheme, use --help for supported values.             |
 | `enable_cache_memory`        | Boolean                                                                                                            | Enable cache and buffer memory stats (not available on Windows). |
 | `process_memory_as_value`    | Boolean                                                                                                            | Defaults to showing process memory usage by value.               |
 | `tree`                       | Boolean                                                                                                            | Defaults to showing the process widget in tree mode.             |

docs/content/configuration/config-file/styling.md

@@ -0,0 +1,159 @@
+# Styling
+
+Various parts of the bottom can be styled, using either built-in themes or custom theming.
+
+## Precedence
+
+As there are a few ways styles can be applied to bottom, the order of which styles are prioritized are, in order of
+highest precedence to lowest precedence:
+
+1. Built-in themes set via command-line args (e.g. `btm --theme gruvbox`)
+2. Custom themes set via config file
+3. Built-in themes set via config file
+
+If nothing is set, it will fall back to the default theme.
+
+## Built-in styles
+
+bottom has a few built-in themes:
+
+- Default
+- [Nord](https://www.nordtheme.com/)
+- [Gruvbox](https://github.com/morhetz/gruvbox)
+
+These themes all also have light variants to support terminals using lighter colours.
+
+To set the theme from the command line:
+
+```bash
+btm --theme gruvbox
+```
+
+To set the theme using the config file:
+
+```toml
+[styles]
+theme = "gruvbox"
+```
+
+## Custom styling
+
+bottom's components can also be individually styled by the user to control the colour of the text style.
+
+### Colours
+
+You can configure the colours for components with strings that are either hex colours (e.g. `"#ffffff"`), RGB colours
+(e.g. `"255, 255, 255"`), or named colours. Named colours are one of the following strings:
+
+- `"Black"`
+- `"Red"`
+- `"Green"`
+- `"Yellow"`
+- `"Blue"`
+- `"Magenta"`
+- `"Cyan"`
+- `"Gray"`
+- `"DarkGray"`
+- `"LightRed"`
+- `"LightGreen"`
+- `"LightYellow"`
+- `"LightBlue"`
+- `"LightMagenta"`
+- `"LightCyan"`
+- `"White"`
+
+### Text
+
+Text can generally be styled using the following TOML table:
+
+```toml
+[field]
+# The foreground colour of text.
+color = "black"
+
+# The background colour of text.
+bg_color = "blue"
+
+# Whether to make the text bold.
+bold = false
+
+# Inline table version
+field = { color = "black", bg_color = "blue", bold = false }
+```
+
+All fields are optional; by default if `bg_color` is not set then there will be no background color.
+
+### Configuration
+
+#### CPU
+
+These can be set under `[styles.cpu]`:
+
+| Config field      | Details                                                          | Examples                                     |
+| ----------------- | ---------------------------------------------------------------- | -------------------------------------------- |
+| `all_entry_color` | The colour of the "All" CPU label                                | `all_entry_color = "Red"`                    |
+| `avg_entry_color` | The colour of the average CPU label and graph line               | `avg_entry_color = "255, 0, 255"`            |
+| `cpu_core_colors` | Colour of each CPU threads' label and graph line. Read in order. | `cpu_core_colors = ["Red", "Blue", "Green"]` |
+
+#### Memory
+
+These can be set under `[styles.memory]`:
+
+| Config field | Details                                                                        | Examples                          |
+| ------------ | ------------------------------------------------------------------------------ | --------------------------------- |
+| `ram`        | The colour of the RAM label and graph line                                     | `ram = "Red"`                     |
+| `cache`      | The colour of the cache label and graph line. Does not do anything on Windows. | `cache = "#ffffff"`               |
+| `swap`       | The colour of the swap label and graph line                                    | `swap = "255, 0, 255"`            |
+| `arc`        | The colour of the ARC label and graph line                                     | `arc = "Blue"`                    |
+| `gpus`       | Colour of each GPU's memory label and graph line. Read in order.               | `gpus = ["Red", "Blue", "Green"]` |
+
+#### Network
+
+These can be set under `[styles.network]`:
+
+| Config field | Details                                                   | Examples               |
+| ------------ | --------------------------------------------------------- | ---------------------- |
+| `rx`         | The colour of the RX (download) label and graph line      | `rx = "Red"`           |
+| `tx`         | The colour of the TX (upload) label and graph line.       | `tx = "#ffffff"`       |
+| `rx_total`   | The colour of the total RX (download) label in basic mode | `rx_total = "0, 0, 0"` |
+| `tx_total`   | The colour of the total TX (upload) label in basic mode   | `tx_total = "#000"`    |
+
+#### Battery
+
+These can be set under `[styles.battery]`:
+
+| Config field     | Details                                                                  | Examples                     |
+| ---------------- | ------------------------------------------------------------------------ | ---------------------------- |
+| `high_battery`   | The colour of the battery widget bar when the battery is over 50%        | `high_battery = "Red"`       |
+| `medium_battery` | The colour of the battery widget bar when the battery between 10% to 50% | `medium_battery = "#ffffff"` |
+| `low_battery`    | The colour of the battery widget bar when the battery is under 10%       | `low_battery = "0, 0, 0"`    |
+
+#### Tables
+
+These can be set under `[styles.tables]`:
+
+| Config field | Details                        | Examples                                                       |
+| ------------ | ------------------------------ | -------------------------------------------------------------- |
+| `headers`    | Text styling for table headers | `headers = { color = "red", bg_color = "black", bold = true }` |
+
+#### Graphs
+
+These can be set under `[styles.graphs]`:
+
+| Config field  | Details                                      | Examples                                                            |
+| ------------- | -------------------------------------------- | ------------------------------------------------------------------- |
+| `graph_color` | The general colour of the parts of the graph | `graph_color = "white"`                                             |
+| `legend_text` | Text styling for graph's legend text         | `legend_text = { color = "black", bg_color = "blue", bold = true }` |
+
+#### General widget settings
+
+These can be set under `[styles.widgets]`:
+
+| Config field      | Details                                                      | Examples                                                              |
+| ----------------- | ------------------------------------------------------------ | --------------------------------------------------------------------- |
+| `border`          | The colour of the widgets' borders                           | `border = "white"`                                                    |
+| `selected_border` | The colour of a widget's borders when the widget is selected | `selected_border = "white"`                                           |
+| `widget_title`    | Text styling for a widget's title                            | `widget_title = { color = "black", bg_color = "blue", bold = true }`  |
+| `text`            | Text styling for text in general                             | `text = { color = "black", bg_color = "blue", bold = true }`          |
+| `selected_text`   | Text styling for text when representing something selected   | `selected_text = { color = "black", bg_color = "blue", bold = true }` |
+| `disabled_text`   | Text styling for text when representing something disabled   | `disabled_text = { color = "black", bg_color = "blue", bold = true }` |

docs/content/troubleshooting.md

@@ -106,23 +106,28 @@ If your configuration files aren't working, here are a few things to try:
 
 ### Check the formatting
 
-It may be handy to refer to the automatically generated config files or the [sample configuration files](https://github.com/ClementTsang/bottom/tree/main/sample_configs).
-The config files also follow the [TOML](https://toml.io/en/) format.
+It may be handy to refer to the automatically generated config files or the
+[sample configuration files](https://github.com/ClementTsang/bottom/tree/main/sample_configs). The config files also
+follow the [TOML](https://toml.io/en/) format.
 
-Also make sure your config options are under the right table - for example, to set your temperature type, you must set it under the `[flags]` table:
+Also make sure your config options are under the right table - for example, to set your temperature type, you must
+set it under the `[flags]` table:
 
 ```toml
 [flags]
 temperature_type = "f"
 ```
 
-Meanwhile, if you want to set a custom color scheme, it would be under the `[colors]` table:
+Meanwhile, if you want to set a custom color scheme, it would be under the `[styles]` table:
 
 ```toml
-[colors]
-table_header_color="LightBlue"
+[styles.tables.headers]
+color="LightBlue"
 ```
 
+To help validate your configuration files, there is [JSON Schema](https://json-schema.org/) support if your IDE/editor
+supports it.
+
 ### Check the configuration file location
 
 Make sure bottom is reading the right configuration file. By default, bottom looks for config files at these locations:

docs/mkdocs.yml

@@ -166,7 +166,7 @@ nav:
       - "Config File":
           - configuration/config-file/index.md
           - "Flags": configuration/config-file/flags.md
-          - "Theming": configuration/config-file/theming.md
+          - "Styling": configuration/config-file/styling.md
           - "Layout": configuration/config-file/layout.md
           - "Data Filtering": configuration/config-file/data-filtering.md
           - "Processes": configuration/config-file/processes.md

sample_configs/default_config.toml

@@ -127,43 +127,57 @@
 
 # These are all the components that support custom theming.  Note that colour support
 # will depend on terminal support.
-#[colors] # Uncomment if you want to use custom colors
-# Represents the colour of table headers (processes, CPU, disks, temperature).
-#table_header_color="LightBlue"
-# Represents the colour of the label each widget has.
-#widget_title_color="Gray"
-# Represents the average CPU color.
-#avg_cpu_color="Red"
-# Represents the colour the core will use in the CPU legend and graph.
-#cpu_core_colors=["LightMagenta", "LightYellow", "LightCyan", "LightGreen", "LightBlue", "LightRed", "Cyan", "Green", "Blue", "Red"]
-# Represents the colour RAM will use in the memory legend and graph.
-#ram_color="LightMagenta"
-# Represents the colour SWAP will use in the memory legend and graph.
-#swap_color="LightYellow"
-# Represents the colour ARC will use in the memory legend and graph.
-#arc_color="LightCyan"
-# Represents the colour the GPU will use in the legend and graph.
-#gpu_core_colors=["LightGreen", "LightBlue", "LightRed", "Cyan", "Green", "Blue", "Red"]
-# Represents the colour rx will use in the network legend and graph.
-#rx_color="LightCyan"
-# Represents the colour tx will use in the network legend and graph.
-#tx_color="LightGreen"
-# Represents the colour of the border of unselected widgets.
-#border_color="Gray"
-# Represents the colour of the border of selected widgets.
-#highlighted_border_color="LightBlue"
-# Represents the colour of most text.
-#text_color="Gray"
-# Represents the colour of text that is selected.
-#selected_text_color="Black"
-# Represents the background colour of text that is selected.
-#selected_bg_color="LightBlue"
-# Represents the colour of the lines and text of the graph.
-#graph_color="Gray"
-# Represents the colours of the battery based on charge
-#high_battery_color="green"
-#medium_battery_color="yellow"
-#low_battery_color="red"
+#[styles] # Uncomment if you want to use custom styling
+
+# Built-in themes. Valid values are:
+# - "default"
+# - "default-light"
+# - "gruvbox"
+# - "gruvbox-light"
+# - "nord"
+# - "nord-light".
+#
+# This will have the lowest precedence if a custom colour palette is set,
+# or overriden if the command-line flag for a built-in theme is set.
+#theme = "default"
+
+#[styles.cpu]
+#all_entry_color = "green"
+#avg_entry_color = "red"
+#cpu_core_colors = ["light magenta", "light yellow", "light cyan", "light green", "light blue", "cyan", "green", "blue"]
+
+#[styles.memory]
+#ram = "light magenta"
+#cache = "light red"
+#swap = "light yellow"
+#arc = "light cyan"
+#gpus = ["light blue", "light red", "cyan", "green", "blue", "red"]
+
+#[styles.network]
+#rx = "light magenta"
+#tx = "light yellow"
+#rx_total = "light cyan"
+#tx_total = "light green"
+
+#[styles.battery]
+#high_battery = "green"
+#medium_battery = "yellow"
+#low_battery = "red"
+
+#[styles.tables]
+#headers = {color = "light blue"}
+
+#[styles.graphs]
+#graph_color = "gray"
+#legend_text = {color = "gray"}
+
+#[styles.widgets]
+#border = "gray"
+#selected_border = "light blue"
+#widget_title = {color = "gray"}
+#text = {color = "gray"}
+#selected_text = {color = "black", bg_color = "light blue"}
+#disabled_text = {color = "dark gray"}
 
 # Layout - layouts follow a pattern like this:
 # [[row]] represents a row in the application.

sample_configs/demo_config.toml

@@ -13,3 +13,6 @@ whole_word = false
 regex = true
 default_widget_type = "cpu"
 default_widget_count = 1
+
+[styles]
+theme = "gruvbox"