How to write a theme

Writing a new theme is relatively straight-forward:

• Place a new JSON-formatted file into <i3bumblebee folder>/bumblebee/themes/ (the name of the file is the name of the theme)
• Fill the file with your requirements

Depending on the complexity of the theme, the second part can be either easy or slightly tricky :)

The theme configuration is considered in the following order:

• If there is a configuration for the specific module and its state, use it
• Otherwise, fall back to the module-specific configuration
• If no module-specific configuration exists, fall back to the "defaults" configuration
• If no configuration if found in "defaults", fall back to the defaults set in the i3 configuration

The following attributes are currently supported:

• prefix is data that is printed before the data element (e.g. an icon if you use a font that supports it)
• suffix is data that is printed after the data element
• fg is the font color
• bg is the background color
• cycle is a list that can be used instead of plain fg and bg colors to make the modules cycle through a set of colors (e.g. to alternate between two sets). See the solarized theme for an example of this
• default-separators can be used in the defaults section to either enable (True) or disable (False) the default i3bar separators
• separator can be used in the defaults section to specify a custom separator, if the default separator is disabled
• All other sections are treated as "state" specific formatting information. For example, when a module is in "critical" or "warning" state, it will look for critical and warning sections, respectively, to retieve formatting information, and only then fall back to default.

Furthermore, each module can have separate configurations and separate states. The states are determined by the modules themselves, and in the theme, it is possible to specify all of the items above also on a per-status level.

For a full example of a theme that uses all capabilities, please have a look at solarized-powerline.json.

A very simple example could look like this (it's actually the current default.json:

{
        "icons": [ "ascii" ],
        "defaults": {
                "urgent": true,
                "fg": "#aabbcc"
        }
}

Iconset configuration files are placed into the <i3bumblebee folder>/bumblebee/themes/icons/ subdirectory, but are identical to the main configuration file content-wise. Really, those files are simply merged into the main file (from left to right), to fill in any missing information. I.e. the main file can override icon files, but not vice versa.