F00bar

Index

1. Introduction
2. Configuration
   1. Overview
   2. Types
   3. Bar
3. Modules
   1. Alsa
   2. backlight
   3. battery
   4. clock
   5. i3
   6. label
   7. mpd
   8. network
   9. removables
   10. xkb
   11. xwindow
4. Particles
   1. empty
   2. list
   3. map
   4. progress 1.bar
   5. ramp
   6. string
5. Decorations
   1. background
   2. stack
   3. underline

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

• alsa
• backlight
• battery
• clock
• i3
• label
• mpd
• network
• removables
• xkb
• xwindow

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}"}}

Backlight

Battery

Clock

I3

Label

Mpd

Network

Removables

Xkb

Xwindow

Particles

• empty
• list
• map
• progress-bar
• ramp
• string

Empty

List

Map

Progress-bar

Ramp

String

Decorations

• background
• stack
• underline

Background

Stack

Underline