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 pix‐ │
17 │ │ │ │ els, on the left │
18 │ │ │ │ side of the par‐ │
19 │ │ │ │ ticle │
20 ├────────────────┼─────────────────┼─────┼──────────────────┤
21 │right-margin │ int │ no │ Space, in pix‐ │
22 │ │ │ │ els, on the │
23 │ │ │ │ right side of │
24 │ │ │ │ the particle │
25 ├────────────────┼─────────────────┼─────┼──────────────────┤
26 │margin │ int │ no │ Short-hand for │
27 │ │ │ │ setting both │
28 │ │ │ │ left-margin and │
29 │ │ │ │ right-margin │
30 ├────────────────┼─────────────────┼─────┼──────────────────┤
31 │font │ font │ no │ Font to use. │
32 │ │ │ │ Note that this │
33 │ │ │ │ is an inherited │
34 │ │ │ │ attribute; i.e. │
35 │ │ │ │ you can set it │
36 │ │ │ │ on e.g. a list │
37 │ │ │ │ particle, and it │
38 │ │ │ │ will apply to │
39 │ │ │ │ all particles in │
40 │ │ │ │ the list. │
41 ├────────────────┼─────────────────┼─────┼──────────────────┤
42 │foreground │ color │ no │ Foreground │
43 │ │ │ │ (text) color. │
44 │ │ │ │ Just like font, │
45 │ │ │ │ this is an in‐ │
46 │ │ │ │ herited attri‐ │
47 │ │ │ │ bute. │
48 ├────────────────┼─────────────────┼─────┼──────────────────┤
49 │on-click │ associative ar‐ │ no │ When set to a │
50 │ │ ray/string │ │ string, executes │
51 │ │ │ │ the string as a │
52 │ │ │ │ command when the │
53 │ │ │ │ particle is │
54 │ │ │ │ left-clicked. │
55 │ │ │ │ Tags can be │
56 │ │ │ │ used. Note that │
57 │ │ │ │ the string is │
58 │ │ │ │ not executed in │
59 │ │ │ │ a shell. The │
60 │ │ │ │ same applies to │
61 │ │ │ │ all attributes │
62 │ │ │ │ associated with │
63 │ │ │ │ it, below. │
64 ├────────────────┼─────────────────┼─────┼──────────────────┤
65 │on-click.left │ string │ no │ Command to exe‐ │
66 │ │ │ │ cute when the │
67 │ │ │ │ particle is │
68 │ │ │ │ left-clicked. │
69 ├────────────────┼─────────────────┼─────┼──────────────────┤
70 │on-click.right │ string │ no │ Command to exe‐ │
71 │ │ │ │ cute when the │
72 │ │ │ │ particle is │
73 │ │ │ │ right-clicked. │
74 ├────────────────┼─────────────────┼─────┼──────────────────┤
75 │on-click.middle │ string │ no │ Command to exe‐ │
76 │ │ │ │ cute when the │
77 │ │ │ │ particle is mid‐ │
78 │ │ │ │ dle-clicked. │
79 ├────────────────┼─────────────────┼─────┼──────────────────┤
80 │on-click.wheel- │ string │ no │ Command to exe‐ │
81 │up │ │ │ cute every time │
82 │ │ │ │ a 'wheel-up' │
83 │ │ │ │ event is trig‐ │
84 │ │ │ │ gered. │
85 ├────────────────┼─────────────────┼─────┼──────────────────┤
86 │on-click.wheel- │ string │ no │ Command to exe‐ │
87 │down │ │ │ cute every time │
88 │ │ │ │ a 'wheel-down' │
89 │ │ │ │ event is trig‐ │
90 │ │ │ │ gered. │
91 ├────────────────┼─────────────────┼─────┼──────────────────┤
92 │deco │ decoration │ no │ Decoration to │
93 │ │ │ │ apply to the │
94 │ │ │ │ particle. See │
95 │ │ │ │ yambar-decora‐ │
96 │ │ │ │ tions(5) │
97 └────────────────┴─────────────────┴─────┴──────────────────┘
98 EXAMPLES:
100 on-click as a string (handles left click):
101 content:
102 <particle>:
103 on-click: command args
104 on-click as an associative array (handles other buttons):
106 content:
107 <particle>:
108 on-click:
109 left: command-1
110 wheel-up: command-3
111 wheel-down: command-4
112
114 This is the most basic particle. It takes a format string, consisting
115 of free text mixed with tag specifiers.
116 CONFIGURATION
118 ┌─────┬────────┬─────┬──────────────────┐
119 │Name │ Type │ Req │ Description │
120 ├─────┼────────┼─────┼──────────────────┤
121 │text │ string │ yes │ Format string. │
122 │ │ │ │ Tags are spci‐ │
123 │ │ │ │ fied with │
124 │ │ │ │ {tag_name}. Some │
125 │ │ │ │ tag types have │
126 │ │ │ │ suffixes that │
127 │ │ │ │ can be appended │
128 │ │ │ │ (e.g. │
129 │ │ │ │ {tag_name:suf‐ │
130 │ │ │ │ fix}). See yam‐ │
131 │ │ │ │ bar-modules(5)). │
132 ├─────┼────────┼─────┼──────────────────┤
133 │max │ int │ no │ Sets the ren‐ │
134 │ │ │ │ dered string's │
135 │ │ │ │ maximum length. │
136 │ │ │ │ If the final │
137 │ │ │ │ string's length │
138 │ │ │ │ exceeds this, │
139 │ │ │ │ the rendered │
140 │ │ │ │ string will be │
141 │ │ │ │ truncated, and │
142 │ │ │ │ "..." will be │
143 │ │ │ │ appended. Note │
144 │ │ │ │ that the trail‐ │
145 │ │ │ │ ing "..." are │
146 │ │ │ │ included in the │
147 │ │ │ │ maximum length. │
148 │ │ │ │ I.e. if you set │
149 │ │ │ │ max to '5', you │
150 │ │ │ │ will only get 2 │
151 │ │ │ │ characters from │
152 │ │ │ │ the string. │
153 └─────┴────────┴─────┴──────────────────┘
154 EXAMPLES
156 content:
157 string:
158 text: "hello, this is footag's value: {footag}"
159
161 This particle is a place-holder. While it does not render any tags,
162 margins and decorations are rendered.
163 CONFIGURATION
165 None
166 EXAMPLES
168 content:
169 empty: {}
170
172 This particle is a list (or sequence, if you like) of other particles.
173 It can be used to render e.g. string particles with different font
174 and/or color formatting. Or ay other particle combinations.
175 But note that this means you cannot set any attributes on the list par‐
177 ticle itself.
178 CONFIGURATION
180 ┌──────────────┬──────┬─────┬──────────────────┐
181 │Name │ Type │ Req │ Description │
182 ├──────────────┼──────┼─────┼──────────────────┤
183 │items │ list │ yes │ List of sub par‐ │
184 │ │ │ │ ticles │
185 ├──────────────┼──────┼─────┼──────────────────┤
186 │left-spacing │ int │ no │ Space, in pix‐ │
187 │ │ │ │ els, between the │
188 │ │ │ │ sub particles. │
189 ├──────────────┼──────┼─────┼──────────────────┤
190 │right-spacing │ int │ no │ Space, in pix‐ │
191 │ │ │ │ els, between the │
192 │ │ │ │ sub particles. │
193 │ │ │ │ Note: default=2 │
194 ├──────────────┼──────┼─────┼──────────────────┤
195 │spacing │ int │ no │ Short-hand for │
196 │ │ │ │ setting both │
197 │ │ │ │ left-spacing and │
198 │ │ │ │ right-spacing │
199 └──────────────┴──────┴─────┴──────────────────┘
200 EXAMPLES
202 content:
203 list:
204 spacing: 5
205 items:
206 - string: {text: hello}
207 - string: {text: world}
208 Many times, the only attribute you need to set is items. In this case,
210 there is a shorter form. Instead of:
211 content:
213 list:
214 items:
215 - string: ...
216 - string: ...
217 you can list the items directly:
219 content:
221 - string: ...
222 - string: ...
223
225 This particle maps the values of a specific tag to different particles.
226 In addition to explicit tag values, you can also specify a de‐
227 fault/fallback particle.
228 CONFIGURATION
230 ┌────────┬─────────────────┬─────┬──────────────────┐
231 │Name │ Type │ Req │ Description │
232 ├────────┼─────────────────┼─────┼──────────────────┤
233 │tag │ string │ yes │ The tag (name │
234 │ │ │ │ of) which values │
235 │ │ │ │ should be mapped │
236 ├────────┼─────────────────┼─────┼──────────────────┤
237 │values │ associative ar‐ │ yes │ An associative │
238 │ │ ray │ │ array of tag │
239 │ │ │ │ values mapped to │
240 │ │ │ │ particles │
241 ├────────┼─────────────────┼─────┼──────────────────┤
242 │default │ particle │ no │ Default particle │
243 │ │ │ │ to use, when │
244 │ │ │ │ tag's value does │
245 │ │ │ │ not match any of │
246 │ │ │ │ the mapped val‐ │
247 │ │ │ │ ues. │
248 └────────┴─────────────────┴─────┴──────────────────┘
249 EXAMPLES
251 content:
252 map:
253 tag: tag_name
254 default:
255 string:
256 text: this is the default particle; the tag's value is now {tag_name}
257 values:
258 one_value:
259 string:
260 text: tag's value is now one_value
261 another_value:
262 string:
263 text: tag's value is now another_value
264
267 This particle uses a range tag to index into an array of particles.
268 This can be used for example to map volume to a volume-level icon, or a
269 battery's capacity level to a battery indicator.
270 CONFIGURATION
272 ┌──────┬────────┬─────┬──────────────────┐
273 │Name │ Type │ Req │ Description │
274 ├──────┼────────┼─────┼──────────────────┤
275 │tag │ string │ yes │ The range tag │
276 │ │ │ │ (name of) to use │
277 │ │ │ │ as index │
278 ├──────┼────────┼─────┼──────────────────┤
279 │items │ list │ yes │ List of parti‐ │
280 │ │ │ │ cles. Note that │
281 │ │ │ │ the tag value is │
282 │ │ │ │ not used as-is; │
283 │ │ │ │ its minimum and │
284 │ │ │ │ maximum values │
285 │ │ │ │ are used to map │
286 │ │ │ │ the tag's range │
287 │ │ │ │ to the particle │
288 │ │ │ │ list's range. │
289 ├──────┼────────┼─────┼──────────────────┤
290 │min │ int │ no │ If present this │
291 │ │ │ │ will be used as │
292 │ │ │ │ a lower bound │
293 │ │ │ │ instead of the │
294 │ │ │ │ tags minimum │
295 │ │ │ │ value. Tag val‐ │
296 │ │ │ │ ues falling out‐ │
297 │ │ │ │ side the defined │
298 │ │ │ │ range will get │
299 │ │ │ │ clamped to │
300 │ │ │ │ min/max. │
301 ├──────┼────────┼─────┼──────────────────┤
302 │max │ int │ no │ If present this │
303 │ │ │ │ will be used as │
304 │ │ │ │ an upper bound │
305 │ │ │ │ instead of the │
306 │ │ │ │ tags maximum │
307 │ │ │ │ value. Tag val‐ │
308 │ │ │ │ ues falling out‐ │
309 │ │ │ │ side the defined │
310 │ │ │ │ range will get │
311 │ │ │ │ clamped to │
312 │ │ │ │ min/max. │
313 └──────┴────────┴─────┴──────────────────┘
314 EXAMPLES
316 content:
317 ramp:
318 tag: capacity
319 items:
320 - string: {text: }
321 - string: {text: }
322 - string: {text: }
323 - string: {text: }
324 - string: {text: }
325
327 This particle renders a range tag's value as a progress bar. You con‐
328 trol the looks of it by defining the particles to use for the progress
329 bar's start and end, it's size, which particles to use for the range
330 that has been completed, the range that has yet to be completed, and
331 the particle to use as the progress bar's current value indicator.
332 This particle also supports realtime tags, and will then auto-update
334 itself when needed.
335 CONFIGURATION
337 ┌──────────┬──────────┬─────┬──────────────────┐
338 │Name │ Type │ Req │ Description │
339 ├──────────┼──────────┼─────┼──────────────────┤
340 │tag │ string │ yes │ The range or re‐ │
341 │ │ │ │ altime tag (name │
342 │ │ │ │ of) which value │
343 │ │ │ │ will be used as │
344 │ │ │ │ the progress │
345 │ │ │ │ bar's value. │
346 ├──────────┼──────────┼─────┼──────────────────┤
347 │length │ int │ yes │ The size/length │
348 │ │ │ │ of the progress │
349 │ │ │ │ bar, in charac‐ │
350 │ │ │ │ ters. Note that │
351 │ │ │ │ the start, end │
352 │ │ │ │ and indicator │
353 │ │ │ │ particles are │
354 │ │ │ │ not included. │
355 ├──────────┼──────────┼─────┼──────────────────┤
356 │start │ particle │ yes │ The progress │
357 │ │ │ │ bar's starting │
358 │ │ │ │ character │
359 ├──────────┼──────────┼─────┼──────────────────┤
360 │end │ particle │ yes │ The progress │
361 │ │ │ │ bar's ending │
362 │ │ │ │ character │
363 ├──────────┼──────────┼─────┼──────────────────┤
364 │fill │ particle │ yes │ Particle to use │
365 │ │ │ │ in the completed │
366 │ │ │ │ range │
367 ├──────────┼──────────┼─────┼──────────────────┤
368 │empty │ particle │ yes │ Particle to use │
369 │ │ │ │ in the not-yet- │
370 │ │ │ │ completed range │
371 ├──────────┼──────────┼─────┼──────────────────┤
372 │indicator │ particle │ yes │ Particle repre‐ │
373 │ │ │ │ senting the │
374 │ │ │ │ progress bar's │
375 │ │ │ │ current value │
376 └──────────┴──────────┴─────┴──────────────────┘
377 EXAMPLES
379 content:
380 progres-bar:
381 tag: tag_name
382 length: 20
383 start: {string: {text: ├}}
384 end: {string: {text: ┤}}
385 fill: {string: {text: ─}}
386 empty: {string: {text: ╌}}
387 indicator: {string: {text: ┼}}
388
390 yambar-tags(5), yambar-decorations(5)
391 2022-08-26 yambar-particles(5)