1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
How to write a 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.
To create an "icon-only" widget (e.g. the play/pause/forward/rewind buttons
of a media player), you need to do the following:
1. In the module, create a widget, and set its state to a descriptive value
(for example `widget.set("state", "next")`
2. In the theme's icon definition JSON, define a `prefix` for that state:
.. code:: json
{
"spotify": {
"next": { "prefix": "<next icon>" }
},
}
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
-----------------------
This list specifies the names of all attributes, their JSON type and a short description.
defaults, object
Container to specify fallback values, in case nothing more specific matches.
Can itself contain any of the other attributes (to e.g. specify a default background
color).
cycle, array of objects
Similar to defaults, but specifies a list of containers that is iterated for each
widget being drawn. Effectively, this allows alternating attribute values for
widgets (for a powerline effect, for example)
icons, array of strings
Allows loading of external JSON files and merging them into the current one (adding fields
that do not exist in the current JSON, but not overwriting existing values). In practice, this
is used to load common icon sets (hence the name).
warning, object
Specifies attributes such as foreground or background colors for a widget that is in state
"warning"
critical, object
Specifies attributes such as foreground or background colors for a widget that is in state
"critical"
fg, string
Specifies foreground (text) color
bg, string
Specifies background (block) color
separator, string
Specifies a string that will be used as separator between two widgets
padding, string
Specifies a string that will be used as padding at the beginning and end of each widget
pango, object
Specifies `pango <https://developer.gnome.org/platform-overview/stable/tech-pango.html>`_ markup
attributes. Once this attribute is encountered, all other text formatting, such as `fg` or `bg`
are ignored for this widget!
prefix, string
Specifies a string that will be used as prefix for matching widgets
suffix, string
Specifies a string that will be used as suffix for matching widgets
default-separators, boolean
If set to true, the default i3bar separators are drawn, otherwise not
separator-block-width, integer
Specifies the width of the i3bar default separators, if they are drawn
<module name>, object
Container to specify values matching a specific module
<state>, object
Container to specify values matching a specific state of a widget
Note that it is also possible to nest containers, for example, it is possible to embed a "state"
object inside a specific "module" object to have formatting specific to one module, depending
on the state of a widget.
In concrete terms, this is used, for example, by multiple mediaplayer modules (cmus, deadbeef, etc.)
to have specific formatting for play/pause, etc, for that single widget only, like this:
.. code-block:: json
{
"cmus": {
"playing": {
"prefix": "play"
}
}
}
Examples
--------
see
`github:tobi-wan-kenobi/bumblebee-status/themes <https://github.com/tobi-wan-kenobi/bumblebee-status/tree/main/themes>`__
|
