yambar-particles(5)

NAME

yambar-particles(5) — the particles configuration file, from the File Formats Manual. Hii bestie 💖

DESCRIPTION

Okay so particles are literally the thing that renders the tags your modules give you. Each particle defines its own set of configuration attributes. However, the following attributes are supported by all particles:

Common attributes 💅

• left-margin — type: int, required: no; space, in pixels, on the left side of the particle.
• right-margin — type: int, required: no; space, in pixels, on the right side of the particle.
• margin — type: int, required: no; short-hand for setting both left-margin and right-margin.
• font — type: font, required: no; the font to use. Note that this is an inherited attribute; i.e. you can set it on e.g. a list particle, and it will apply to all particles in the list. Slay.
• font-shaping — type: enum, required: no; font-shaping; one of full or none. When set to full (the default), strings will be "shaped" using HarfBuzz. Requires support in fcft.
• foreground — type: color, required: no; foreground (text) color. Just like font, this is an inherited attribute.
• on-click — type: associative array/string, required: no; when set to a string, executes the string as a command when the particle is left-clicked. Tags can be used. Note that the string is not executed in a shell. Environment variables are not expanded. ~/ is expanded, but only in the first argument. The same applies to all attributes associated with it, below.
• on-click.left — type: string, required: no; command to execute when the particle is left-clicked.
• on-click.right — type: string, required: no; command to execute when the particle is right-clicked.
• on-click.middle — type: string, required: no; command to execute when the particle is middle-clicked.
• on-click.wheel-up — type: string, required: no; command to execute every time a 'wheel-up' event is triggered.
• on-click.wheel-down — type: string, required: no; command to execute every time a 'wheel-down' event is triggered.
• on-click.previous — type: string, required: no; command to execute when the particle is clicked with the 'previous' button.
• on-click.next — type: string, required: no; command to execute when the particle is clicked with the 'next' button.
• deco — type: decoration, required: no; decoration to apply to the particle. See yambar-decorations(5).

---

EXAMPLES ✨

on-click as a string (handles left click):

content:
  <particle>:
    on-click: command args

on-click as an associative array (handles other buttons):

content:
  <particle>:
    on-click:
      left: command-1
      wheel-up: command-3
      wheel-down: command-4

💖 STRING 💖

Okay so this is like the most basic particle ever — the starter pack, the vanilla ice cream of particles 🍦. It takes a format string, which is just free text mixed with tag specifiers. That's it. That's the whole vibe.

✨ CONFIGURATION ✨

• text — string, required 💅 — the format string itself. You specify tags with {tag_name}. Some tag types have suffixes you can append (like {tag_name:suffix}). Go check yambar-modules(5) for the tea on that one 🫖.
• max — int, optional — sets the rendered string's maximum length. If the final string's length exceeds this, the rendered string gets truncated and "…" gets appended. Important bestie: that trailing "…" counts toward the maximum length. So like, if you set max to '5', you will only get 4 characters from the string 😭. Math is math.

🎀 EXAMPLES 🎀

content:
  string:
    text: "hello, this is footag's value: {footag}"

---

🦋 EMPTY 🦋

This particle is literally just a place-holder. It doesn't render any tags, but the margins and decorations do get rendered. So it's giving invisible-but-present, main character energy that refuses to be seen 👻.

✨ CONFIGURATION ✨

None. Nothing. Zero. Nada 🙈.

🎀 EXAMPLES 🎀

content:
  empty: {}

---

🌈 LIST 🌈

This particle is a list (or sequence, if that's more your vibe) of other particles. You can use it to render like, string particles with different font and/or color formatting. Or any other particle combinations honestly, go off 💅.

But heads up — this means you cannot set any attributes on the list particle itself. It's a container, not a participant, iykyk.

✨ CONFIGURATION ✨

• items — list, required — the list of sub particles 🧚
• left-spacing — int, optional — space, in pixels, between the sub particles.
• right-spacing — int, optional — space, in pixels, between the sub particles. Note: default=2 👀
• spacing — int, optional — short-hand for setting both left-spacing and right-spacing at once. Slay, efficiency 💖

🎀 EXAMPLES 🎀

content:
  list:
    spacing: 5
    items:
      - string: {text: hello}
      - string: {text: world}

A lot of the time, the only attribute you actually need to set is items. And for those times, there's a shorter form 🎉. So instead of:

content:
  list:
    items:
      - string: ...
      - string: ...

you can just list the items directly:

content:
  - string: ...
  - string: ...

Not me loving a shortcut 🫶.

---

🔥 MAP 🔥

This particle maps the values of a specific tag to different particles based on conditions. So like, tag says one thing → show this, tag says another thing → show that. Very choose-your-own-adventure ⭐.

A condition takes either the form of:

<tag> <operation> <value>

Or, for boolean tags:

<tag>

Where <tag> is the tag you would like to map, <operation> is one of:

==, !=, >=, >, <=, <

and <value> is the value you would like to compare it to. If the value contains any non-alphanumerical characters, you must surround it with ":

"hello world"
"@#$%"

Negation is done with a preceding ~:

~<tag>
~<condition>

To match for empty strings, use "":

<tag> == ""

Furthermore, you may use the boolean operators:

&&, ||

in order to create more complex conditions:

<condition1> && <condition2>

You may surround <condition> with parenthesis for clarity or for specifying precedence:

(<condition>)
<condition1> && (<condition2> || <condition3>)

In addition to explicit tag values, you can also specify a default/fallback particle 💜.

Lowkey crucial bestie: conditions are evaluated in the order they appear. If multiple conditions are true, the first one will be used. So in a configuration such as:

tx-bitrate > 1000:
tx-bitrate > 1000000:

the second condition would never run, since whenever the second condition is true, the first one is also true 💀. The correct way of doing this would be to invert the order of the conditions:

tx-bitrate > 1000000:
tx-bitrate > 1000:

✨ CONFIGURATION ✨

• conditions — associative array, required — an associative array of conditions (see above) mapped to particles 🎀
• default — particle, optional — the default particle to use when none of the conditions are true. Your safety net, your fallback bestie 🫶

🎀 EXAMPLES 🎀

content:
  map:
    default:
      string:
        text: this is the default particle; the tag's value is now {tag_name}
    conditions:
      tag == one_value:
        string:
          text: tag's value is now one_value
      tag == another_value:
        string:
          text: tag's value is now another_value

For a boolean tag:

content:
  map:
    conditions:
      tag:
        string:
        text: tag is true
      ~tag:
        string:
        text: tag is false

Periodt. 💅

🎀 RAMP 🎀

Okay bestie, RAMP is the particle that uses a range tag to index into an array of particles. It’s giving “map a value to a whole vibe”: for example, map volume to a volume-level icon, or a battery’s capacity level to a battery indicator. 🔋✨

⚙️ CONFIGURATION ⚙️

• tag — string · Req: yes. The range tag (name of) to use as index.
• items — list · Req: yes. List of particles. Note that the tag value is not used as-is; its minimum and maximum values are used to map the tag’s range to the particle list’s range. 🧚
• min — int · Req: no. If present this will be used as a lower bound instead of the tag’s minimum value. Tag values falling outside the defined range will get clamped to min/max. 💅
• max — int · Req: no. If present this will be used as an upper bound instead of the tag’s maximum value. Tag values falling outside the defined range will get clamped to min/max. 💅

✨ EXAMPLES ✨

        content:
          ramp:
            tag: capacity
            items:
              - string: {text: }
              - string: {text: }
              - string: {text: }
              - string: {text: }
              - string: {text: }

---

💖 PROGRESS-BAR 💖

This particle renders a range tag’s value as a progress bar. You control the looks of it by defining the particles to use for the progress bar’s start and end, its size, which particles to use for the range that has been completed, the range that has yet to be completed, and the particle to use as the progress bar’s current value indicator. It’s a whole aesthetic. 🎨

This particle also supports realtime tags, and will then auto-update itself when needed. No cap. ⏱️

⚙️ CONFIGURATION ⚙️

• tag — string · Req: yes. The range or realtime tag (name of) which value will be used as the progress bar’s value.
• length — int · Req: yes. The size/length of the progress bar, in characters. Note that the start, end and indicator particles are not included. 📏
• start — particle · Req: yes. The progress bar’s starting character.
• end — particle · Req: yes. The progress bar’s ending character.
• fill — particle · Req: yes. Particle to use in the completed range.
• empty — particle · Req: yes. Particle to use in the not-yet-completed range.
• indicator — particle · Req: yes. Particle representing the progress bar’s current value.

✨ EXAMPLES ✨

        content:
          progres-bar:
            tag: tag_name
            length: 20
            start: {string: {text: ├}}
            end: {string: {text: ┤}}
            fill: {string: {text: ─}}
            empty: {string: {text: ╌}}
            indicator: {string: {text: ┼}}

Bestie, the example key is literally progres-bar — keep it exactly like that if you copy this. 🙈

---

👀 SEE ALSO 👀

Go peek at yambar-tags(5) and yambar-decorations(5) too, bestie 🫶

---

That’s the tea ☕ — source/version yambar-particles(5), dated 2024-04-22. Byeee, go make your bar cute 💖🌈✨