yambar-particles - Man Page

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:

NameTypeReqDescription
left-marginintnoSpace, in pixels, on the left side of the particle
right-marginintnoSpace, in pixels, on the right side of the particle
marginintnoShort-hand for setting both left-margin and right-margin
fontfontnoFont 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.
foregroundcolornoForeground (text) color. Just like font, this is an inherited attribute.
on-clickassociative array/stringnoWhen 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. The same applies to all attributes associated with it, below.
on-click.leftstringnoCommand to execute when the particle is left-clicked.
on-click.rightstringnoCommand to execute when the particle is right-clicked.
on-click.middlestringnoCommand to execute when the particle is middle-clicked.
on-click.wheel-upstringnoCommand to execute every time a 'wheel-up' event is triggered.
on-click.wheel-downstringnoCommand to execute every time a 'wheel-down' event is triggered.
decodecorationnoDecoration 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

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

Configuration

NameTypeReqDescription
textstringyesFormat string. Tags are spcified with {tag_name}. Some tag types have suffixes that can be appended (e.g. {tag_name:suffix}). See yambar-modules(5)).
maxintnoSets 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 "..." are included in the maximum length. I.e. if you set max to '5', you will only get 2 characters from the string.

Examples

  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.

Configuration

None

Examples

  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.

Configuration

NameTypeReqDescription
itemslistyesList of sub particles
left-spacingintnoSpace, in pixels, between the sub particles.
right-spacingintnoSpace, in pixels, between the sub particles. Note: default=2
spacingintnoShort-hand for setting both left-spacing and right-spacing

Examples

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

Many times, the only attribute you need to set is items. In this case, there is a shorter form. Instead of:

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

you can list the items directly:

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

Map

This particle maps the values of a specific tag to different particles. In addition to explicit tag values, you can also specify a default/fallback particle.

Configuration

NameTypeReqDescription
tagstringyesThe tag (name of) which values should be mapped
valuesassociative arrayyesAn associative array of tag values mapped to particles
defaultparticlenoDefault particle to use, when tag's value does not match any of the mapped values.

Examples

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

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.

Configuration

NameTypeReqDescription
tagstringyesThe range tag (name of) to use as index
itemslistyesList 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.
minintnoIf 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.
maxintnoIf 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.

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, 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.

Configuration

NameTypeReqDescription
tagstringyesThe range or realtime tag (name of) which value will be used as the progress bar's value.
lengthintyesThe size/length of the progress bar, in characters. Note that the start, end and indicator particles are not included.
startparticleyesThe progress bar's starting character
endparticleyesThe progress bar's ending character
fillparticleyesParticle to use in the completed range
emptyparticleyesParticle to use in the not-yet-completed range
indicatorparticleyesParticle 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: ┼}}

See Also

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

Referenced By

yambar(5), yambar-decorations(5), yambar-modules(5), yambar-modules-alsa(5), yambar-modules-backlight(5), yambar-modules-battery(5), yambar-modules-clock(5), yambar-modules-cpu(5), yambar-modules-foreign-toplevel(5), yambar-modules-i3(5), yambar-modules-label(5), yambar-modules-mem(5), yambar-modules-mpd(5), yambar-modules-network(5), yambar-modules-removables(5), yambar-modules-river(5), yambar-modules-script(5), yambar-modules-sway-xkb(5), yambar-modules-xkb(5), yambar-modules-xwindow(5).

2022-08-26