1yambar-particles(5) File Formats Manual yambar-particles(5)
2
6 yambar-particles - configuration file
7
9 Particles are what renders the tags provided by modules. Each particle
10 defines its own set of configuration attributes. However, the following
11 attributes are supported by all particles:
12 ┌────────────────┬─────────────────┬─────┬─────────────────────────────┐
14 │Name │ Type │ Req │ Description │
15 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
16 │left-margin │ int │ no │ Space, in pixels, on the │
17 │ │ │ │ left side of the particle │
18 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
19 │right-margin │ int │ no │ Space, in pixels, on the │
20 │ │ │ │ right side of the particle │
21 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
22 │margin │ int │ no │ Short-hand for setting both │
23 │ │ │ │ left-margin and right-mar‐ │
24 │ │ │ │ gin │
25 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
26 │font │ font │ no │ Font to use. Note that this │
27 │ │ │ │ is an inherited attribute; │
28 │ │ │ │ i.e. you can set it on e.g. │
29 │ │ │ │ a list particle, and it │
30 │ │ │ │ will apply to all particles │
31 │ │ │ │ in the list. │
32 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
33 │font-shaping │ enum │ no │ font-shaping; one of full │
34 │ │ │ │ or none. When set to full │
35 │ │ │ │ (the default), strings will │
36 │ │ │ │ be "shaped" using HarfBuzz. │
37 │ │ │ │ Requires support in fcft. │
38 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
39 │foreground │ color │ no │ Foreground (text) color. │
40 │ │ │ │ Just like font, this is an │
41 │ │ │ │ inherited attribute. │
42 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
43 │on-click │ associative ar‐ │ no │ When set to a string, exe‐ │
44 │ │ ray/string │ │ cutes the string as a com‐ │
45 │ │ │ │ mand when the particle is │
46 │ │ │ │ left-clicked. Tags can be │
47 │ │ │ │ used. Note that the string │
48 │ │ │ │ is not executed in a shell. │
49 │ │ │ │ Environment variables are │
50 │ │ │ │ not expanded. ~/ is ex‐ │
51 │ │ │ │ panded, but only in the │
52 │ │ │ │ first argument. The same │
53 │ │ │ │ applies to all attributes │
54 │ │ │ │ associated with it, below. │
55 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
56 │on-click.left │ string │ no │ Command to execute when the │
57 │ │ │ │ particle is left-clicked. │
58 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
59 │on-click.right │ string │ no │ Command to execute when the │
60 │ │ │ │ particle is right-clicked. │
61 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
62 │on-click.middle │ string │ no │ Command to execute when the │
63 │ │ │ │ particle is middle-clicked. │
64 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
65 │on-click.wheel- │ string │ no │ Command to execute every │
66 │up │ │ │ time a 'wheel-up' event is │
67 │ │ │ │ triggered. │
68 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
69 │on-click.wheel- │ string │ no │ Command to execute every │
70 │down │ │ │ time a 'wheel-down' event │
71 │ │ │ │ is triggered. │
72 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
73 │on-click.previ‐ │ string │ no │ Command to execute when the │
74 │ous │ │ │ particle is clicked with │
75 │ │ │ │ the 'previous' button. │
76 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
77 │on-click.next │ string │ no │ Command to execute when the │
78 │ │ │ │ particle is clicked with │
79 │ │ │ │ the 'next' button. │
80 ├────────────────┼─────────────────┼─────┼─────────────────────────────┤
81 │deco │ decoration │ no │ Decoration to apply to the │
82 │ │ │ │ particle. See yambar-deco‐ │
83 │ │ │ │ rations(5) │
84 └────────────────┴─────────────────┴─────┴─────────────────────────────┘
85 EXAMPLES:
87 on-click as a string (handles left click):
88 content:
89 <particle>:
90 on-click: command args
91 on-click as an associative array (handles other buttons):
93 content:
94 <particle>:
95 on-click:
96 left: command-1
97 wheel-up: command-3
98 wheel-down: command-4
99
101 This is the most basic particle. It takes a format string, consisting
102 of free text mixed with tag specifiers.
103 CONFIGURATION
105 ┌─────┬────────┬─────┬──────────────────┐
106 │Name │ Type │ Req │ Description │
107 ├─────┼────────┼─────┼──────────────────┤
108 │text │ string │ yes │ Format string. │
109 │ │ │ │ Tags are speci‐ │
110 │ │ │ │ fied with │
111 │ │ │ │ {tag_name}. Some │
112 │ │ │ │ tag types have │
113 │ │ │ │ suffixes that │
114 │ │ │ │ can be appended │
115 │ │ │ │ (e.g. │
116 │ │ │ │ {tag_name:suf‐ │
117 │ │ │ │ fix}). See yam‐ │
118 │ │ │ │ bar-modules(5)). │
119 ├─────┼────────┼─────┼──────────────────┤
120 │max │ int │ no │ Sets the ren‐ │
121 │ │ │ │ dered string's │
122 │ │ │ │ maximum length. │
123 │ │ │ │ If the final │
124 │ │ │ │ string's length │
125 │ │ │ │ exceeds this, │
126 │ │ │ │ the rendered │
127 │ │ │ │ string will be │
128 │ │ │ │ truncated, and │
129 │ │ │ │ "…" will be ap‐ │
130 │ │ │ │ pended. Note │
131 │ │ │ │ that the trail‐ │
132 │ │ │ │ ing "…" is in‐ │
133 │ │ │ │ cluded in the │
134 │ │ │ │ maximum length. │
135 │ │ │ │ I.e. if you set │
136 │ │ │ │ max to '5', you │
137 │ │ │ │ will only get 4 │
138 │ │ │ │ characters from │
139 │ │ │ │ the string. │
140 └─────┴────────┴─────┴──────────────────┘
141 EXAMPLES
143 content:
144 string:
145 text: "hello, this is footag's value: {footag}"
146
148 This particle is a place-holder. While it does not render any tags,
149 margins and decorations are rendered.
150 CONFIGURATION
152 None
153 EXAMPLES
155 content:
156 empty: {}
157
159 This particle is a list (or sequence, if you like) of other particles.
160 It can be used to render e.g. string particles with different font
161 and/or color formatting. Or ay other particle combinations.
162 But note that this means you cannot set any attributes on the list par‐
164 ticle itself.
165 CONFIGURATION
167 ┌──────────────┬──────┬─────┬──────────────────────────────────────────┐
168 │Name │ Type │ Req │ Description │
169 ├──────────────┼──────┼─────┼──────────────────────────────────────────┤
170 │items │ list │ yes │ List of sub particles │
171 ├──────────────┼──────┼─────┼──────────────────────────────────────────┤
172 │left-spacing │ int │ no │ Space, in pixels, between the sub parti‐ │
173 │ │ │ │ cles. │
174 ├──────────────┼──────┼─────┼──────────────────────────────────────────┤
175 │right-spacing │ int │ no │ Space, in pixels, between the sub parti‐ │
176 │ │ │ │ cles. Note: default=2 │
177 ├──────────────┼──────┼─────┼──────────────────────────────────────────┤
178 │spacing │ int │ no │ Short-hand for setting both left-spacing │
179 │ │ │ │ and right-spacing │
180 └──────────────┴──────┴─────┴──────────────────────────────────────────┘
181 EXAMPLES
183 content:
184 list:
185 spacing: 5
186 items:
187 - string: {text: hello}
188 - string: {text: world}
189 Many times, the only attribute you need to set is items. In this case,
191 there is a shorter form. Instead of:
192 content:
194 list:
195 items:
196 - string: ...
197 - string: ...
198 you can list the items directly:
200 content:
202 - string: ...
203 - string: ...
204
206 This particle maps the values of a specific tag to different particles
207 based on conditions. A condition takes either the form of:
208 <tag> <operation> <value>
210 Or, for boolean tags:
212 <tag>
214 Where <tag> is the tag you would like to map, <operation> is one of:
216 ┌────┬────┬────┬───┬────┬───┐
218 │ == │ != │ >= │ > │ <= │ < │
219 └────┴────┴────┴───┴────┴───┘
220 and <value> is the value you would like to compare it to. If the value
221 contains any non-alphanumerical characters, you must surround it with '
222 " ' :
223 "hello world"
225 "@#$%"
226 Negation is done with a preceding '~':
228 ~<tag>
230 ~<condition>
231 To match for empty strings, use ' "" ':
233 <tag> == ""
235 Furthermore, you may use the boolean operators:
237 ┌────┬────┐
239 │ && │ || │
240 └────┴────┘
241 in order to create more complex conditions:
242 <condition1> && <condition2>
244 You may surround <condition> with parenthesis for clarity or specifying
246 precedence:
247 (<condition>)
249 <condition1> && (<condition2> || <condition3>)
250 In addition to explicit tag values, you can also specify a de‐
252 fault/fallback particle.
253 Note that conditions are evaluated in the order they appear. If multi‐
255 ple conditions are true, the first one will be used. This means that in
256 a configuration such as:
257 tx-bitrate > 1000:
259 tx-bitrate > 1000000:
260 the second condition would never run, since whenever the second condi‐
262 tion is true, the first is also true. The correct way of doing this
263 would be to invert the order of the conditions:
264 tx-bitrate > 1000000:
266 tx-bitrate > 1000:
267 CONFIGURATION
269 ┌───────────┬─────────────────┬─────┬──────────────────────────────────┐
270 │Name │ Type │ Req │ Description │
271 ├───────────┼─────────────────┼─────┼──────────────────────────────────┤
272 │conditions │ associative ar‐ │ yes │ An associative array of condi‐ │
273 │ │ ray │ │ tions (see above) mapped to par‐ │
274 │ │ │ │ ticles │
275 ├───────────┼─────────────────┼─────┼──────────────────────────────────┤
276 │default │ particle │ no │ Default particle to use, none of │
277 │ │ │ │ the conditions are true │
278 └───────────┴─────────────────┴─────┴──────────────────────────────────┘
279 EXAMPLES
281 content:
282 map:
283 default:
284 string:
285 text: this is the default particle; the tag's value is now {tag_name}
286 conditions:
287 tag == one_value:
288 string:
289 text: tag's value is now one_value
290 tag == another_value:
291 string:
292 text: tag's value is now another_value
293 For a boolean tag:
296 content:
298 map:
299 conditions:
300 tag:
301 string:
302 text: tag is true
303 ~tag:
304 string:
305 text: tag is false
306
308 This particle uses a range tag to index into an array of particles.
309 This can be used for example to map volume to a volume-level icon, or a
310 battery's capacity level to a battery indicator.
311 CONFIGURATION
313 ┌──────┬────────┬─────┬────────────────────────────────────────────────┐
314 │Name │ Type │ Req │ Description │
315 ├──────┼────────┼─────┼────────────────────────────────────────────────┤
316 │tag │ string │ yes │ The range tag (name of) to use as index │
317 ├──────┼────────┼─────┼────────────────────────────────────────────────┤
318 │items │ list │ yes │ List of particles. Note that the tag value is │
319 │ │ │ │ not used as-is; its minimum and maximum values │
320 │ │ │ │ are used to map the tag's range to the parti‐ │
321 │ │ │ │ cle list's range. │
322 ├──────┼────────┼─────┼────────────────────────────────────────────────┤
323 │min │ int │ no │ If present this will be used as a lower bound │
324 │ │ │ │ instead of the tags minimum value. Tag values │
325 │ │ │ │ falling outside the defined range will get │
326 │ │ │ │ clamped to min/max. │
327 ├──────┼────────┼─────┼────────────────────────────────────────────────┤
328 │max │ int │ no │ If present this will be used as an upper bound │
329 │ │ │ │ instead of the tags maximum value. Tag values │
330 │ │ │ │ falling outside the defined range will get │
331 │ │ │ │ clamped to min/max. │
332 └──────┴────────┴─────┴────────────────────────────────────────────────┘
333 EXAMPLES
335 content:
336 ramp:
337 tag: capacity
338 items:
339 - string: {text: }
340 - string: {text: }
341 - string: {text: }
342 - string: {text: }
343 - string: {text: }
344
346 This particle renders a range tag's value as a progress bar. You con‐
347 trol the looks of it by defining the particles to use for the progress
348 bar's start and end, it's size, which particles to use for the range
349 that has been completed, the range that has yet to be completed, and
350 the particle to use as the progress bar's current value indicator.
351 This particle also supports realtime tags, and will then auto-update
353 itself when needed.
354 CONFIGURATION
356 ┌──────────┬──────────┬─────┬──────────────────────────────────────────┐
357 │Name │ Type │ Req │ Description │
358 ├──────────┼──────────┼─────┼──────────────────────────────────────────┤
359 │tag │ string │ yes │ The range or realtime tag (name of) │
360 │ │ │ │ which value will be used as the progress │
361 │ │ │ │ bar's value. │
362 ├──────────┼──────────┼─────┼──────────────────────────────────────────┤
363 │length │ int │ yes │ The size/length of the progress bar, in │
364 │ │ │ │ characters. Note that the start, end and │
365 │ │ │ │ indicator particles are not included. │
366 ├──────────┼──────────┼─────┼──────────────────────────────────────────┤
367 │start │ particle │ yes │ The progress bar's starting character │
368 ├──────────┼──────────┼─────┼──────────────────────────────────────────┤
369 │end │ particle │ yes │ The progress bar's ending character │
370 ├──────────┼──────────┼─────┼──────────────────────────────────────────┤
371 │fill │ particle │ yes │ Particle to use in the completed range │
372 ├──────────┼──────────┼─────┼──────────────────────────────────────────┤
373 │empty │ particle │ yes │ Particle to use in the not-yet-completed │
374 │ │ │ │ range │
375 ├──────────┼──────────┼─────┼──────────────────────────────────────────┤
376 │indicator │ particle │ yes │ Particle representing the progress bar's │
377 │ │ │ │ current value │
378 └──────────┴──────────┴─────┴──────────────────────────────────────────┘
379 EXAMPLES
381 content:
382 progres-bar:
383 tag: tag_name
384 length: 20
385 start: {string: {text: ├}}
386 end: {string: {text: ┤}}
387 fill: {string: {text: ─}}
388 empty: {string: {text: ╌}}
389 indicator: {string: {text: ┼}}
390
392 yambar-tags(5), yambar-decorations(5)
393 2023-07-14 yambar-particles(5)