111 lines
2.8 KiB
Markdown
111 lines
2.8 KiB
Markdown
# How to write themes
|
|
|
|
## Introduction
|
|
`bumblebee-status` themes are simply JSON files that describe various attributes (foreground color,
|
|
background color, etc.) of the blocks that make up a status bar.
|
|
|
|
It is possible to specify each attribute at various levels:
|
|
- For a specific state of a specific module
|
|
- For a specific module
|
|
- A cycle of attributes (those are cycled through widget-by-widget)
|
|
- Default values
|
|
|
|
Looking up a value follows the "more specific rather than more generic" approach. In other words,
|
|
if a foreground color exists for the "warning" state of module "a", any less specific foreground
|
|
color value that **would** match will be ignored.
|
|
|
|
Themes are loaded from the following locations:
|
|
- `$(BUMBLEBEE_STATUS_BASE_DIR)/themes/`
|
|
- `~/.config/bumblebee-status/themes/`
|
|
|
|
## Basic structure
|
|
A very simple theme file looks like this:
|
|
```json
|
|
{
|
|
"icons": [ "awesome-fonts" ],
|
|
"defaults": {
|
|
"fg": "#000000",
|
|
"bg": "#ffffff",
|
|
"warning": {
|
|
"fg": "#ff0000",
|
|
"bg": "#ffffff"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Icons
|
|
Using the `icons` directive, it's possible to reuse icon definitions for multiple themes.
|
|
The value of the field is the **basename** of a JSON file located in `$(THEME_DIRECTORY)/icons/`.
|
|
The format of the icon file is identical to the theme itself (as the two are essentially just
|
|
merged into a single JSON.
|
|
|
|
## Color definitions and pyWAL support
|
|
`bumblebee-status` supports [github:dylanaraps/pywal](https://github.com/dylanaraps/pywal) definitions.
|
|
|
|
To make use of them, simply generate a colorset using pyWAL and reference it in the theme like
|
|
this:
|
|
|
|
```json
|
|
{
|
|
"icons": [ ... ],
|
|
"colors": [ "wal" ],
|
|
"defaults": {
|
|
"critical": {
|
|
"fg": "cursor",
|
|
"bg": "color5"
|
|
},
|
|
"warning": {
|
|
"fg": "cursor",
|
|
"bg": "color6"
|
|
},
|
|
}
|
|
}
|
|
```
|
|
|
|
Additionally, you can use the `colors` directive to set up named colors for your scheme:
|
|
|
|
```json
|
|
{
|
|
"icons": [ ... ],
|
|
"colors": [ { "red": "#ff0000", "green": "#00ff00", "black": "#000000" } ],
|
|
"defaults": {
|
|
"critical": {
|
|
"fg": "red",
|
|
"bg": "black"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Pango support
|
|
All values that accept a full text (i.e. the base level, `prefix` and `suffix`) accept a special
|
|
attribute `pango` **instead** of all other attributes. In other words, if you specify `pango`,
|
|
any other attribute on that level (foreground color, etc.) will be ignored!
|
|
|
|
Inside `pango`, you can just specify arbitrary Pango attributes, and those will be applied to a
|
|
`<span></span>` that's automatically enclosing the actual text.
|
|
|
|
## Full list of attributes
|
|
|
|
(TODO: Add explanation)
|
|
|
|
- defaults
|
|
- cycle
|
|
- icons
|
|
- warning
|
|
- critical
|
|
- fg
|
|
- bg
|
|
- separator
|
|
- padding
|
|
- pango
|
|
- prefix
|
|
- suffix
|
|
- default-separators
|
|
- separator-block-width
|
|
- <module name>
|
|
- <state>
|
|
|
|
## Examples
|
|
|
|
see [github:tobi-wan-kenobi/bumblebee-status/themes](https://github.com/tobi-wan-kenobi/bumblebee-status/tree/master/themes)
|