dotfiles/polybar/README.md

# Polybar module

[polybar](https://polybar.github.io/) - a fast and easy-to-use statusbar

[[_TOC_]]

## Polybar look

minimal look:

![minimal](.assets/polybar/minimal.png)

Active i3 workspaces are displayed left with current workspace highlighted, and any active i3 modes. The center contains information on the currently playing song, displaying notes if something is playing, date and time, and upcoming bib readings from the library. The right contains system information and the task tray.

with network activity:

![network](.assets/polybar/network.png)

full-load and temperature warning:

![full](.assets/polybar/full.png)

In general, the bar's colors are derived from the colors defined in xresources. It follows the base16 color template, as does every module in these dotfiles. That means the bar can be quickly re-themed using base16 color themes and the process can be automated (e.g. with styler).

## i3 workspaces

![normal](.assets/polybar/i3-normal.png) -- focus on workspace 4

The i3 workspaces module is pretty simple and self-explanatory. It shows all existing workspaces, and highlights the one that is currently active. It also highlights any workspaces on which an event took place.

![highlight](.assets/polybar/i3-highlight.png) -- focus on workspace 2, workspace 1 highlighted

Additionally, if an i3 mode is active, it will be displayed next to the workspaces in a stark color to notice the mode being active. This is slowly being deprecated in favor of sxhkd modes -- e.g. media mode is now displayed by the sxhkd module instead. The only remaining mode is resize for the moment.

![mode](.assets/polybar/i3-mode.png) -- focus on workspace 3, 'Media' mode active

Workspaces can be cycled with the mouse-wheel when hovering over the module, or can be invoked by clicking on the icons.

## sxhkd modes

The current mode of the desktop is being passed from sxhkd to polybar for display.
Its look is based on the i3 workspace mode display, though by default they appear to the right of the workspaces.

![sxhkd mode](.assets/polybar/sxhkd_mode.png) -- academia sxhkd mode activated

## Current track information

By default, the track information panel is very minimal. It simply displays a note when something is currently playing, a pause symbol when the current track is pause, and nothing at all when no track is currently available. (no media player open, all tracks stopped, etc.)

When clicked, the track metadata is revealed, displaying track artist and title. Another click toggles it off again.

![mpris](.assets/polybar/mpris.png)

When right-clicked, the current track can be toggled between playing and paused.

The `poly-mprisdisplay` script implementation requires `playerctl` available on the system to be run. It will return with an error message if the binary is not found. Symbols used can be easily customized in the script.

## Date

The standard polybar date display. Displays current date (DD/MM) and current time (24-hours) by default. On click, toggles to an expanded date display with current weekday and current week of the year.

![clock](.assets/polybar/clock.png)

![extended clock](.assets/polybar/clock_alt.png)

## Upcoming Bibtex readings

Depends on the [`bibtex`](bibtex/) module being installed, more specifically:

  * the `bib-due` script accessible as a program
  * a `$BIBFILE` environment variable pointing to the bibtex library (or at least, the relevant library of the system)
  * optionally: `rofi` (or `dmenu`) to enable listing of readings on click

Displays the library readings remaining for the week in simple numerical fashion. On click invokes the full `bib_due` script to show further information on the upcoming readings, requiring either `dmenu` or `rofi` to display them.

## System information

Contains various system-relevant details.

![system info](.assets/polybar/system.png)

If the network has activity, it shows upload and download speeds (dynamically switching between displaying Kb/s, Mb/s). The script `poly-networkspeed` as of now uses hard-coded network interface names. If network interfaces have a different name, this will need to be adjusted.

If updates for arch packages are available (from repositories or aur) it displays the number of available updates. The script `poly-archupdates` requires `yay` to be available. If checkupdates is available it will use this to check for repo packages, which can avoid partial arch updates in rare circumstances. (contained in `pacman-contrib` package)

The volume module simply displays the current pulseaudio volume as a ramped version of the volume symbol. On click it toggles mute and un-mute.

If xbacklight is available, the current display brightness is displayed as a symbol between a moon (dark) and a sun (bright).

If a battery is available, it will display its current status,  percentage, and whether it is charging.

The cpu load is displayed as a simple vertical bar, changing color at specific intervals to be more noticeable. When the cpu gets warm, a temperature warning will be displayed, along with current numeric temperature value (in °C). The correct sensor may have to be changed in the polybar config file; as well as useful limits for the display of temperature information.