NAME

yambar-particles - configuration file

DESCRIPTION

Particles are what renders the tags provided by modules. Each particle defines its own set of configuration attributes. However, the following attributes are supported by all particles:

content:


  <particle>:


    on-click: command args

content:


  <particle>:


    on-click:


      left: command-1


      wheel-up: command-3


      wheel-down: command-4

STRING

This is the most basic particle. It takes a format string, consisting of free text mixed with tag specifiers.

content:


  string:


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

EMPTY

This particle is a place-holder. While it does not render any tags, margins and decorations are rendered.

content:


  empty: {}

LIST

This particle is a list (or sequence, if you like) of other particles. It can be used to render e.g. string particles with different font and/or color formatting. Or ay other particle combinations.

But note that this means you cannot set any attributes on the list particle itself.

content:


  list:


    spacing: 5


    items:


      - string: {text: hello}


      - string: {text: world}

content:


  list:


    items:


      - string: ...


      - string: ...

content:


  - string: ...


  - string: ...

MAP

This particle maps the values of a specific tag to different particles based on conditions. 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 specifying precedence:

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

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

Note that conditions are evaluated in the order they appear. If multiple conditions are true, the first one will be used. This means that 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 is also true. The correct way of doing this would be to invert the order of the conditions:

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

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

content:


  map:


    conditions:


      tag:


        string:


        text: tag is true


      ~tag:


        string:


        text: tag is false

RAMP

This particle uses a range tag to index into an array of particles. This can be used for example to map volume to a volume-level icon, or a battery's capacity level to a battery indicator.

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, it's 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.

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

content:


  progres-bar:


    tag: tag_name


    length: 20


    start: {string: {text: ├}}


    end: {string: {text: ┤}}


    fill: {string: {text: ─}}


    empty: {string: {text: ╌}}


    indicator: {string: {text: ┼}}

SEE ALSO

yambar-tags(5), yambar-decorations(5)