.\" Generated by scdoc 1.11.2
.\" 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" "2022-12-17"
.P
.SH NAME
yambar-particles - configuration file
.P
.SH DESCRIPTION
.P
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:
.P
.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.\& 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:
.P
\fBon-click\fR as a string (handles left click):
.nf
.RS 4
content:
  <particle>:
    on-click: command args
.fi
.RE
.P
\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
.P
.SH STRING
.P
This is the most basic particle.\& It takes a format string, consisting
of free text mixed with tag specifiers.\&
.P
.SS CONFIGURATION
.P
.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
.P
.nf
.RS 4
content:
  string:
    text: "hello, this is footag\&'s value: {footag}"
.fi
.RE
.P
.SH EMPTY
.P
This particle is a place-holder.\& While it does not render any tags,
margins and decorations are rendered.\&
.P
.SS CONFIGURATION
.P
None
.P
.SS EXAMPLES
.P
.nf
.RS 4
content:
  empty: {}
.fi
.RE
.P
.SH LIST
.P
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.\&
.P
But note that this means you \fBcannot\fR set any attributes on the \fIlist\fR
particle itself.\&
.P
.SS CONFIGURATION
.P
.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
.P
.nf
.RS 4
content:
  list:
    spacing: 5
    items:
      - string: {text: hello}
      - string: {text: world}
.fi
.RE
.P
Many times, the only attribute you need to set is \fIitems\fR.\& In this
case, there is a shorter form.\& Instead of:
.P
.nf
.RS 4
content:
  list:
    items:
      - string: \&.\&.\&.
      - string: \&.\&.\&.
.fi
.RE
.P
you can list the items directly:
.P
.nf
.RS 4
content:
  - string: \&.\&.\&.
  - string: \&.\&.\&.
.fi
.RE
.P
.SH MAP
.P
This particle maps the values of a specific tag to different
particles based on conditions.\& A condition takes either the form of:
.P
.nf
.RS 4
<tag> <operation> <value>
.fi
.RE
.P
Or, for boolean tags:
.P
.nf
.RS 4
<tag>
.fi
.RE
.P
Where <tag> is the tag you would like to map, <operation> is one of:
.P
.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:
.P
.nf
.RS 4
"hello world"
"@#$%"
.fi
.RE
.P
Negation is done with a preceding '\&~'\&:
.P
.nf
.RS 4
~<tag>
~<condition>
.fi
.RE
.P
To match for empty strings, use '\& "" '\&:
.P
.nf
.RS 4
<tag> == ""
.fi
.RE
.P
Furthermore, you may use the boolean operators:
.P
.TS
allbox;c c.
T{
 &&
T}	T{
||
T}
.TE
.sp 1
in order to create more complex conditions:
.P
.nf
.RS 4
<condition1> && <condition2>
.fi
.RE
.P
You may surround <condition> with parenthesis for clarity or
specifying precedence:
.P
.nf
.RS 4
(<condition>)
<condition1> && (<condition2> || <condition3>)
.fi
.RE
.P
In addition to explicit tag values, you can also specify a
default/fallback particle.\&
.P
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:
.P
.nf
.RS 4
tx-bitrate > 1000:
tx-bitrate > 1000000:
.fi
.RE
.P
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:
.P
.nf
.RS 4
tx-bitrate > 1000000:
tx-bitrate > 1000:
.fi
.RE
.P
.P
.SS CONFIGURATION
.P
.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
.P
.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
.P
For a boolean tag:
.P
.nf
.RS 4
content:
  map:
    conditions:
      tag:
        string:
        text: tag is true
      ~tag:
        string:
        text: tag is false
.fi
.RE
.P
.SH RAMP
.P
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.\&
.P
.SS CONFIGURATION
.P
.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
.P
.nf
.RS 4
content:
  ramp:
    tag: capacity
    items:
      - string: {text: }
      - string: {text: }
      - string: {text: }
      - string: {text: }
      - string: {text: }
.fi
.RE
.P
.SH PROGRESS-BAR
.P
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.\&
.P
This particle also supports \fIrealtime\fR tags, and will then auto-update
itself when needed.\&
.P
.SS CONFIGURATION
.P
.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
.P
.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
.P
.SH SEE ALSO
.P
\fByambar-tags\fR(5), \fByambar-decorations\fR(5)