.\" Generated by scdoc 1.11.5
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "yambar\-particles" "5" "2026\-10\-30"
.PP
.SH NAME
yambar\-particles \- configuration file
.PP
.SH DESCRIPTION
.PP
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:
.PP
.TS
allbox;l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx.
T{
\fBName\fR
T}	T{
\fBType\fR
T}	T{
\fBReq\fR
T}	T{
\fBDescription\fR
T}
T{
left\-margin
T}	T{
int
T}	T{
no
T}	T{
Space, in pixels, on the left side of the particle
T}
T{
right\-margin
T}	T{
int
T}	T{
no
T}	T{
Space, in pixels, on the right side of the particle
T}
T{
margin
T}	T{
int
T}	T{
no
T}	T{
Short\-hand for setting both \fIleft\-margin\fR and \fIright\-margin\fR
T}
T{
font
T}	T{
font
T}	T{
no
T}	T{
Font to use.\& Note that this is an inherited attribute; i.\&e.\& you can set it on e.\&g.\& a \fIlist\fR particle, and it will apply to all particles in the list.\&
T}
T{
font\-shaping
T}	T{
enum
T}	T{
no
T}	T{
font\-shaping; one of \fIfull\fR or \fInone\fR.\& When set to \fIfull\fR (the default), strings will be "shaped" using HarfBuzz.\& Requires support in fcft.\&
T}
T{
foreground
T}	T{
color
T}	T{
no
T}	T{
Foreground (text) color.\& Just like \fIfont\fR, this is an inherited attribute.\&
T}
T{
on\-click
T}	T{
associative array/string
T}	T{
no
T}	T{
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 \fBnot\fR executed in a shell.\& Environment variables are not expanded.\& \fB\(ti/\fR is expanded, but only in the first argument.\& The same applies to all attributes associated with it, below.\&
T}
T{
on\-click.\&left
T}	T{
string
T}	T{
no
T}	T{
Command to execute when the particle is left\-clicked.\&
T}
T{
on\-click.\&right
T}	T{
string
T}	T{
no
T}	T{
Command to execute when the particle is right\-clicked.\&
T}
T{
on\-click.\&middle
T}	T{
string
T}	T{
no
T}	T{
Command to execute when the particle is middle\-clicked.\&
T}
T{
on\-click.\&wheel\-up
T}	T{
string
T}	T{
no
T}	T{
Command to execute every time a '\&wheel\-up'\& event is triggered.\&
T}
T{
on\-click.\&wheel\-down
T}	T{
string
T}	T{
no
T}	T{
Command to execute every time a '\&wheel\-down'\& event is triggered.\&
T}
T{
on\-click.\&previous
T}	T{
string
T}	T{
no
T}	T{
Command to execute when the particle is clicked with the '\&previous'\& button.\&
T}
T{
on\-click.\&next
T}	T{
string
T}	T{
no
T}	T{
Command to execute when the particle is clicked with the '\&next'\& button.\&
T}
T{
deco
T}	T{
decoration
T}	T{
no
T}	T{
Decoration to apply to the particle.\& See \fByambar\-decorations\fR(5)
T}
.TE
.sp 1
.SS EXAMPLES:
.PP
\fBon\-click\fR as a string (handles left click):
.nf
.RS 4
content:
  <particle>:
    on\-click: command args
.fi
.RE
.PP
\fBon\-click\fR as an associative array (handles other buttons):
.nf
.RS 4
content:
  <particle>:
    on\-click:
      left: command\-1
      wheel\-up: command\-3
      wheel\-down: command\-4
.fi
.RE
.PP
.SH STRING
.PP
This is the most basic particle.\& It takes a format string, consisting
of free text mixed with tag specifiers.\&
.PP
.SS CONFIGURATION
.PP
.TS
allbox;l l l l
l l l l
l l l l.
T{
\fBName\fR
T}	T{
\fBType\fR
T}	T{
\fBReq\fR
T}	T{
\fBDescription\fR
T}
T{
text
T}	T{
string
T}	T{
yes
T}	T{
Format string.\& Tags are specified with \fI{tag_name}\fR.\& Some tag types have suffixes that can be appended (e.\&g.\& \fI{tag_name:suffix}\fR).\& See \fByambar\-modules\fR(5)).\&
T}
T{
max
T}	T{
int
T}	T{
no
T}	T{
Sets the rendered string'\&s maximum length.\& If the final string'\&s length exceeds this, the rendered string will be truncated, and "…"  will be appended.\& Note that the trailing "…" is \fBincluded\fR in the maximum length.\& I.\&e.\& if you set \fImax\fR to '\&5'\&, you will only get \fB4\fR characters from the string.\&
T}
.TE
.sp 1
.SS EXAMPLES
.PP
.nf
.RS 4
content:
  string:
    text: "hello, this is footag\&'s value: {footag}"
.fi
.RE
.PP
.SH EMPTY
.PP
This particle is a place\-holder.\& While it does not render any tags,
margins and decorations are rendered.\&
.PP
.SS CONFIGURATION
.PP
None
.PP
.SS EXAMPLES
.PP
.nf
.RS 4
content:
  empty: {}
.fi
.RE
.PP
.SH LIST
.PP
This particle is a list (or sequence, if you like) of other
particles.\& It can be used to render e.\&g.\& \fIstring\fR particles with
different font and/or color formatting.\& Or ay other particle
combinations.\&
.PP
But note that this means you \fBcannot\fR set any attributes on the \fIlist\fR
particle itself.\&
.PP
.SS CONFIGURATION
.PP
.TS
allbox;l l l lx
l l l lx
l l l lx
l l l lx
l l l lx.
T{
\fBName\fR
T}	T{
\fBType\fR
T}	T{
\fBReq\fR
T}	T{
\fBDescription\fR
T}
T{
items
T}	T{
list
T}	T{
yes
T}	T{
List of sub particles
T}
T{
left\-spacing
T}	T{
int
T}	T{
no
T}	T{
Space, in pixels, \fBbetween\fR the sub particles.\&
T}
T{
right\-spacing
T}	T{
int
T}	T{
no
T}	T{
Space, in pixels, \fBbetween\fR the sub particles.\& Note: default=2
T}
T{
spacing
T}	T{
int
T}	T{
no
T}	T{
Short\-hand for setting both \fIleft\-spacing\fR and \fIright\-spacing\fR
T}
.TE
.sp 1
.SS EXAMPLES
.PP
.nf
.RS 4
content:
  list:
    spacing: 5
    items:
      \- string: {text: hello}
      \- string: {text: world}
.fi
.RE
.PP
Many times, the only attribute you need to set is \fIitems\fR.\& In this
case, there is a shorter form.\& Instead of:
.PP
.nf
.RS 4
content:
  list:
    items:
      \- string: \&.\&.\&.
      \- string: \&.\&.\&.
.fi
.RE
.PP
you can list the items directly:
.PP
.nf
.RS 4
content:
  \- string: \&.\&.\&.
  \- string: \&.\&.\&.
.fi
.RE
.PP
.SH MAP
.PP
This particle maps the values of a specific tag to different
particles based on conditions.\& A condition takes either the form of:
.PP
.nf
.RS 4
<tag> <operation> <value>
.fi
.RE
.PP
Or, for boolean tags:
.PP
.nf
.RS 4
<tag>
.fi
.RE
.PP
Where <tag> is the tag you would like to map, <operation> is one of:
.PP
.TS
allbox;c c c c c c.
T{
 ==
T}	T{
!\&=
T}	T{
>=
T}	T{
>
T}	T{
<=
T}	T{
<
T}
.TE
.sp 1
and <value> is the value you would like to compare it to.\& \fBIf the
value contains any non\-alphanumerical characters, you must
surround it with '\& " '\& \fR:
.PP
.nf
.RS 4
"hello world"
"@#$%"
.fi
.RE
.PP
Negation is done with a preceding '\&\(ti'\&:
.PP
.nf
.RS 4
~<tag>
~<condition>
.fi
.RE
.PP
To match for empty strings, use '\& "" '\&:
.PP
.nf
.RS 4
<tag> == ""
.fi
.RE
.PP
Furthermore, you may use the boolean operators:
.PP
.TS
allbox;c c.
T{
 &&
T}	T{
||
T}
.TE
.sp 1
in order to create more complex conditions:
.PP
.nf
.RS 4
<condition1> && <condition2>
.fi
.RE
.PP
You may surround <condition> with parenthesis for clarity or
specifying precedence:
.PP
.nf
.RS 4
(<condition>)
<condition1> && (<condition2> || <condition3>)
.fi
.RE
.PP
In addition to explicit tag values, you can also specify a
default/fallback particle.\&
.PP
Note that conditions are evaluated in the order they appear.\& \fBIf
multiple conditions are true, the first one will be used\fR.\& This means
that in a configuration such as:
.PP
.nf
.RS 4
tx\-bitrate > 1000:
tx\-bitrate > 1000000:
.fi
.RE
.PP
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:
.PP
.nf
.RS 4
tx\-bitrate > 1000000:
tx\-bitrate > 1000:
.fi
.RE
.PP
.PP
.SS CONFIGURATION
.PP
.TS
allbox;l l l lx
l l l lx
l l l lx.
T{
\fBName\fR
T}	T{
\fBType\fR
T}	T{
\fBReq\fR
T}	T{
\fBDescription\fR
T}
T{
conditions
T}	T{
associative array
T}	T{
yes
T}	T{
An associative array  of conditions (see above) mapped to particles
T}
T{
default
T}	T{
particle
T}	T{
no
T}	T{
Default particle to use, none of the conditions are true
T}
.TE
.sp 1
.SS EXAMPLES
.PP
.nf
.RS 4
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

.fi
.RE
.PP
For a boolean tag:
.PP
.nf
.RS 4
content:
  map:
    conditions:
      tag:
        string:
        text: tag is true
      ~tag:
        string:
        text: tag is false
.fi
.RE
.PP
.SH RAMP
.PP
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.\&
.PP
.SS CONFIGURATION
.PP
.TS
allbox;l l l lx
l l l lx
l l l lx
l l l lx
l l l lx.
T{
\fBName\fR
T}	T{
\fBType\fR
T}	T{
\fBReq\fR
T}	T{
\fBDescription\fR
T}
T{
tag
T}	T{
string
T}	T{
yes
T}	T{
The range tag (name of) to use as index
T}
T{
items
T}	T{
list
T}	T{
yes
T}	T{
List of particles.\& Note that the tag value is \fBnot\fR used as\-is; its minimum and maximum values are used to map the tag'\&s range to the particle list'\&s range.\&
T}
T{
min
T}	T{
int
T}	T{
no
T}	T{
If present this will be used as a lower bound instead of the tags minimum value.\&  Tag values falling outside the defined range will get clamped to min/max.\&
T}
T{
max
T}	T{
int
T}	T{
no
T}	T{
If present this will be used as an upper bound instead of the tags maximum value.\&  Tag values falling outside the defined range will get clamped to min/max.\&
T}
.TE
.sp 1
.SS EXAMPLES
.PP
.nf
.RS 4
content:
  ramp:
    tag: capacity
    items:
      \- string: {text: }
      \- string: {text: }
      \- string: {text: }
      \- string: {text: }
      \- string: {text: }
.fi
.RE
.PP
.SH PROGRESS\-BAR
.PP
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.\&
.PP
This particle also supports \fIrealtime\fR tags, and will then auto\-update
itself when needed.\&
.PP
.SS CONFIGURATION
.PP
.TS
allbox;l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx
l l l lx.
T{
\fBName\fR
T}	T{
\fBType\fR
T}	T{
\fBReq\fR
T}	T{
\fBDescription\fR
T}
T{
tag
T}	T{
string
T}	T{
yes
T}	T{
The range or realtime tag (name of) which value will be used as the progress bar'\&s value.\&
T}
T{
length
T}	T{
int
T}	T{
yes
T}	T{
The size/length of the progress bar, in characters.\& Note that the \fIstart\fR, \fIend\fR and \fIindicator\fR particles are \fBnot\fR included.\&
T}
T{
start
T}	T{
particle
T}	T{
yes
T}	T{
The progress bar'\&s starting character
T}
T{
end
T}	T{
particle
T}	T{
yes
T}	T{
The progress bar'\&s ending character
T}
T{
fill
T}	T{
particle
T}	T{
yes
T}	T{
Particle to use in the completed range
T}
T{
empty
T}	T{
particle
T}	T{
yes
T}	T{
Particle to use in the not\-yet\-completed range
T}
T{
indicator
T}	T{
particle
T}	T{
yes
T}	T{
Particle representing the progress bar'\&s current value
T}
.TE
.sp 1
.SS EXAMPLES
.PP
.nf
.RS 4
content:
  progres\-bar:
    tag: tag_name
    length: 20
    start: {string: {text: ├}}
    end: {string: {text: ┤}}
    fill: {string: {text: ─}}
    empty: {string: {text: ╌}}
    indicator: {string: {text: ┼}}
.fi
.RE
.PP
.SH SEE ALSO
.PP
\fByambar\-tags\fR(5), \fByambar\-decorations\fR(5)