133 lines
3.2 KiB
ReStructuredText
133 lines
3.2 KiB
ReStructuredText
|
How to write a new theme
|
|||
|
|
========================
|
|||
|
|
|
|||
|
|
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:
|
|||
|
|
|
|||
|
|
.. code:: 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:
|
|||
|
|
|
|||
|
|
.. code:: 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:
|
|||
|
|
|
|||
|
|
.. code:: 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>`__
|