7.6 KiB
F00bar
Index
Introduction
f00bar is a light-weight and configurable status panel (bar, for short) for X and Wayland.
It has a number of modules that provide information in the form of tags. For example, the clock module has a date tag that contains the current date.
The modules do not know how to present the information though. This is instead done by particles. And the user, you, decides which particles (and thus how to present the data) to use.
Furthermore, each particle can have a decoration. These are things like a different background, or an graphical underline.
There is no support for images or icons. use an icon font (e.g. Font Awesome, or Material Icons) if you want a graphical representation.
There are a number of modules and particles builtin. More can be added as plugins. You can even write your own!
To summarize: a bar displays information provided by modules, using particles and decorations. How is configured by you.
Configuration
Overview
F00bar is configured using YAML, in ~/.config/f00bar/config.yml. It
must define a top-level dictionary named bar:
bar:
height: 26
location: top
background: 000000ff
Types
There are a couple types used that are specific to f00bar.
- font: this is a string in fontconfig format. Example of valid values:
- Font Awesome 5 Brands
- Font Awesome 5 Free:style=solid
- Dina:pixelsize=10:slant=italic
- Dina:pixelsize=10:weight=bold
- color: an rgba hexstring; RRGGBBAA. Examples:
- ffffffff: white, no transparancy
- 000000ff: black, no transparancy
- 00ff00ff: green, no transparancy
- ff000099: red, semi-transparent
Bar
| Name | Type | Req. | Description |
|---|---|---|---|
| height | int | yes | The height of the bar, in pixels |
| location | enum | yes | One of top or bottom |
| background | color | yes | Background color |
| monitor | string | no | Monitor to place the bar. If not specified, the primary monitor will be used. |
| left-spacing | int | no | Space, in pixels, added before each module |
| right-spacing | int | no | Space, in pixels, added after each module |
| spacing | int | no | Short-hand for setting both left-spacing and right-spacing |
| left-margin | int | no | Left-side margin, in pixels |
| right-margin | int | no | Right-side margin, in pixels |
| margin | int | no | Short-hand for setting both left-margin and right-margin |
| border | dict | no | Configures a border around the status bar |
| border.width | int | no | Width, in pixels, of the border |
| border.color | color | no | The color of the border |
| border.margin | int | no | left/rigth/top/bottom margins, from screen edge to bar. Wayland only |
| border.left-margin | int | no | left margin from screen edge to bar. Overrides border.margin. Wayland only |
| border.right-margin | int | no | right margin from screen edge to bar. Overrides border.margin. Wayland only |
| border.top-margin | int | no | top margin from screen edge to bar. Overrides border.margin. Wayland only |
| border.bottom-margin | int | no | bottom margin from screen edge to bar. Overrides border.margin. Wayland only |
| font | font | no | Default font to use in modules and particles |
| foreground | color | no | Default foreground (text) color to use |
| left | list | no | Left-aligned modules |
| center | list | no | Center-aligned modules |
| right | list | no | Right-aligned modules |
The value of each item in the left, center and right lists is a module.
Modules
Generic Configuration
All modules support the following attributes:
| Name | Type | Description |
|---|---|---|
| content | particle | A particle describing how the module's information is to be rendered |
| anchors | dict | Free-to-use dictionary, where you can put yaml anchor definitions |
Tags
Modules expose information through tags. Each tag has name, type and a value. The name and type is fixed, while the value will typically change over time.
The tags are rendered by particles. Each particle type has it's own
way of representing tag values. The simplest one is the string
particle, which renders a text representation of the tag value.
string:
text: "The current volume is {volume}"
The following tag types exist:
| Type | Description |
|---|---|
| string | Value is a string. Rendered as-is by the string particle. |
| int | Value is an integer. Rendered in base 10 by the string particle. |
| bool | Value is true or false. Rendered as "true" or "false" by the string particle. |
| float | Value is a float. Rendered in base 10, with two decimal digits by the string particle. |
| range | Value is an integer, with a minimum and maximum value. By default, string renders the value. The :min or :max suffixes may be added to instead render the min/max values (`"{tag_name:min}"). |
| realtime | Value is an integer that changes in a predictable manner (in "realtime"). This allows the particle to update itself periodically. It could for example be used to represent a playing song's position. Only supported by the progress-bar particle. However, the string particle does recognize the :unit suffix. This will be translated to "s" for a tag with "seconds" resolution, or "ms" for one with "milliseconds" resolution. |
Alsa
Monitors an alsa soundcard for volume and mute/unmute changes.
Tags
| Name | Type | Description |
|---|---|---|
| volume | range | Volume level, with min and max as start and end range values |
| muted | bool | True if muted |
Configuration
| Name | Type | Req. | Description |
|---|---|---|---|
| card | string | yes | The soundcard name. Default might work. |
| mixer | String | yes | Mixer channel to watch. Master might work. |
Example
alsa:
card: hw:PCH
mixer: Master
content: {string: {text: "{volume}"}}