.\" Generated by scdoc 1.11.3
.\" 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-modules" "5" "2024-04-20"
.PP
.SH NAME
yambar-modules - configuration file
.PP
.SH DESCRIPTION
.PP
Modules are what monitors your system and provides data for the status
bar.\&
.PP
All modules expose their data through \fBtags\fR.\& Each tag has a \fBname\fR,
\fBtype\fR and \fBvalue\fR.\& The name and type is fixed, while the value
typically changes over time.\& See \fByambar-tags\fR(5).\&
.PP
The tags are rendered by \fIparticles\fR.\& Each particle has its own way of
representing tag values.\& The simplest one is the \fIstring\fR particle,
which renders a text representation of the tag value.\& See
\fByambar-particles\fR(5).\&
.PP
Note that all the examples showed below have been kept simple.\& Here
are a couple of tips that will improve the looks:
.PP
.SS Use list particles to change font and/or color
.PP
The \fIstring\fR particle, for example, cannot change font or colors in
the middle of its string.\& To do this, you need to wrap multiple
\fIstring\fR particles in a \fIlist\fR particle.\&
.PP
This can be useful if you want to use an icon font for a glyph since
the default fallback fonts provided by fontconfig may not favor your
icon font.\&
.PP
Also remember there is a short version for lists (see
\fByambar-particles\fR(5))
.PP
For example, to render \fIbacklight\fR as " 20%", you could use:
.PP
.nf
.RS 4
content:
  - string:
      font: Font Awesome 6 Free:style=solid:pixelsize=14
      text: 
  - string:
      font: Adobe Helvetica:pixelsize=12
      text: "{percent}%"
.fi
.RE
.PP
.SS Use map particles to handle 'state'
.PP
Several modules have a \fIstate\fR tag that can be used to render
different particles depending on the module'\&s state.\&
.PP
For example, you might want different things to be shown for a
\fInetwork\fR interface that is \fBdown\fR or \fBup\fR.\& You could further
differentiate between an \fBup\fR interface that has or has not an IP
address assigned to it.\&
.PP
Below is an example, where a wired connection is not renderer at all
when disconnected.\&
.PP
When connected, it is rendered in the default text color if it is up
and also has an IPv4 address.\& If it is up, but does not have an IPv4
address, it is rendered in a semi-transparent white color.\&
.PP
Finally, if it is down, or in any other unknown state, it is rendered
in red.\&
.PP
.nf
.RS 4
content:
  map:
    conditions:
      ~carrier: {empty: {}}
      carrier:
        map:
          default: {string: {text: , font: *awesome, foreground: ffffff66}}
          conditions:
            state == up:
              map:
                default: {string: {text: , font: *awesome}}
                conditions:
                  ipv4 == "": {string: {text: , font: *awesome, foreground: ffffff66}}
.fi
.RE
.PP
.SS Use yaml anchors
.PP
You often end up using the same definitions in a lot of places.\& This
is particular true for fonts.\& But it can also be true when mapping
state.\&
.PP
In these cases, you can define an anchor point, either at top-level,
or in a module'\&s \fIanchors\fR attribute:
.PP
.nf
.RS 4
awesome: &awesome Font Awesome 6 Free:style=solid:pixelsize=14

.fi
.RE
.PP
Then reference it in your particle definitions:
.PP
.nf
.RS 4
content:
  string: {text: , font: *awesome}
.fi
.RE
.PP
.SH GENERIC CONFIGURATION
.PP
Each module defines its own configuration format.\& However, the
following attributes are supported by all modules:
.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{
content
T}	T{
particle
T}	T{
yes
T}	T{
A particle describing how the module'\&s information is to be rendered.\& See \fByambar-particles\fR(5)
T}
T{
anchors
T}	T{
associative array
T}	T{
no
T}	T{
Free-to-use associative array, where you can put yaml anchor definitions
T}
T{
font
T}	T{
font
T}	T{
no
T}	T{
Font to use in the content particle.\& This is an inherited attribute.\&
T}
T{
foreground
T}	T{
color
T}	T{
no
T}	T{
Foreground (text) color of the content particle.\& This is an inherited attribute.\&
T}
.TE
.sp 1
.SH BUILT-IN MODULES
.PP
Available modules have their own pages:
.PP
\fByambar-modules-alsa\fR(5)
.PP
\fByambar-modules-backlight\fR(5)
.PP
\fByambar-modules-battery\fR(5)
.PP
\fByambar-modules-clock\fR(5)
.PP
\fByambar-modules-cpu\fR(5)
.PP
\fByambar-modules-disk-io\fR(5)
.PP
\fByambar-modules-dwl\fR(5)
.PP
\fByambar-modules-foreign-toplevel\fR(5)
.PP
\fByambar-modules-i3\fR(5)
.PP
\fByambar-modules-label\fR(5)
.PP
\fByambar-modules-mem\fR(5)
.PP
\fByambar-modules-mpd\fR(5)
.PP
\fByambar-modules-network\fR(5)
.PP
\fByambar-modules-pipewire\fR(5)
.PP
\fByambar-modules-pulse\fR(5)
.PP
\fByambar-modules-removables\fR(5)
.PP
\fByambar-modules-river\fR(5)
.PP
\fByambar-modules-script\fR(5)
.PP
\fByambar-modules-sway-xkb\fR(5)
.PP
\fByambar-modules-sway\fR(5)
.PP
\fByambar-modules-xkb\fR(5)
.PP
\fByambar-modules-xwindow\fR(5)
.PP
.SH SEE ALSO
.PP
\fByambar-particles\fR(5), \fByambar-tags\fR(5), \fByambar-decorations\fR(5)
.PP