1yambar-particles(5)           File Formats Manual          yambar-particles(5)
2
3
4

NAME

6       yambar-particles - configuration file
7

DESCRIPTION

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
13       ┌────────────────┬─────────────────┬─────┬─────────────────────────────┐
14Name            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
86   EXAMPLES:
87       on-click as a string (handles left click):
88           content:
89             <particle>:
90               on-click: command args
91
92       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

STRING

101       This is the most basic particle. It takes a format string, consisting
102       of free text mixed with tag specifiers.
103
104   CONFIGURATION
105       ┌─────┬────────┬─────┬──────────────────┐
106Name 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
142   EXAMPLES
143           content:
144             string:
145               text: "hello, this is footag's value: {footag}"
146

EMPTY

148       This particle is a place-holder. While it does not render any tags,
149       margins and decorations are rendered.
150
151   CONFIGURATION
152       None
153
154   EXAMPLES
155           content:
156             empty: {}
157

LIST

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
163       But note that this means you cannot set any attributes on the list par‐
164       ticle itself.
165
166   CONFIGURATION
167       ┌──────────────┬──────┬─────┬──────────────────────────────────────────┐
168Name          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
182   EXAMPLES
183           content:
184             list:
185               spacing: 5
186               items:
187                 - string: {text: hello}
188                 - string: {text: world}
189
190       Many times, the only attribute you need to set is items. In this case,
191       there is a shorter form. Instead of:
192
193           content:
194             list:
195               items:
196                 - string: ...
197                 - string: ...
198
199       you can list the items directly:
200
201           content:
202             - string: ...
203             - string: ...
204

MAP

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
209           <tag> <operation> <value>
210
211       Or, for boolean tags:
212
213           <tag>
214
215       Where <tag> is the tag you would like to map, <operation> is one of:
216
217       ┌────┬────┬────┬───┬────┬───┐
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
224           "hello world"
225           "@#$%"
226
227       Negation is done with a preceding '~':
228
229           ~<tag>
230           ~<condition>
231
232       To match for empty strings, use ' "" ':
233
234           <tag> == ""
235
236       Furthermore, you may use the boolean operators:
237
238       ┌────┬────┐
239       │ && │ || │
240       └────┴────┘
241       in order to create more complex conditions:
242
243           <condition1> && <condition2>
244
245       You may surround <condition> with parenthesis for clarity or specifying
246       precedence:
247
248           (<condition>)
249           <condition1> && (<condition2> || <condition3>)
250
251       In addition to explicit tag values, you can also specify a de‐
252       fault/fallback particle.
253
254       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
258           tx-bitrate > 1000:
259           tx-bitrate > 1000000:
260
261       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
265           tx-bitrate > 1000000:
266           tx-bitrate > 1000:
267
268   CONFIGURATION
269       ┌───────────┬─────────────────┬─────┬──────────────────────────────────┐
270Name       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
280   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
294
295       For a boolean tag:
296
297           content:
298             map:
299               conditions:
300                 tag:
301                   string:
302                   text: tag is true
303                 ~tag:
304                   string:
305                   text: tag is false
306

RAMP

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
312   CONFIGURATION
313       ┌──────┬────────┬─────┬────────────────────────────────────────────────┐
314Name  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
334   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

PROGRESS-BAR

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
352       This particle also supports realtime tags, and will then auto-update
353       itself when needed.
354
355   CONFIGURATION
356       ┌──────────┬──────────┬─────┬──────────────────────────────────────────┐
357Name      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
380   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

SEE ALSO

392       yambar-tags(5), yambar-decorations(5)
393
394
395
396                                  2023-07-14               yambar-particles(5)
Impressum