Crate lazybar_core

This is a lightweight, event-driven status bar for EWMH-compliant window managers on X11.

It uses tokio in combination with existing event APIs to poll as rarely as possible. For example, the Inotify panel uses Linux’s inotify to monitor the contents of a file.

You’re welcome to use this crate as a library if you want to expand on the functionality included herein, but its intentended use case is to hold most of the logic for lazybar.

At runtime, it reads a configuration file located at $XDG_CONFIG_HOME/lazybar/config.toml, and this documentation will focus on accepted syntax for that file. See panels for panel-specific information.

The general structure of the file is as follows:

Top-level tables:

• bars: each subtable defines a bar, and the name is used as a command line argument to run that bar.
• ramps: each subtable defines a ramp with the same name, and those names are referenced by panel tables (see below).
• panels: each subtable defines a panel with the same name, and those names are referenced by bar tables.
• attrs: each subtable defines a set of attributes that can be referenced by panels.
• bgs: each subtable defines a background configuration (shape, color) that can be referenced by attrs.
• highlights: each subtable defines a highlight, or partial background, that can be reference by panels.
• images: each value is a path to an image that can be rendered on a panel by referencing its key.
• consts: each value is a string that can be substituted into any other string by using %{key}. This format can also be used to reference environment variables using %{env:KEY}.

Other than images and consts, none of these tables need to be declared explicitly, as they hold no values of their own. [bars.example] is sufficient to define a bar named example. Any values in these top level tables will be ignored, along with any top level table with a different name. See https://toml.io/ for more information.

Note: types are pretty flexible, and config will try its best to figure out what you mean, but if you have issues, make sure that your types are correct.

Example Config

[bars.top]
monitor = "eDP-1"
position = "top"
height = 36
transparent = true # allows for transparency
bg = "#0000" # rgba format is required for transparency
default_attrs = "default"
margin_left = 10
margin_internal = 10
margin_right = 10
ipc = true
panels_left = ["xwindow"]
panels_center = ["clock"]
panels_right = ["pulseaudio","separator","network","separator","battery"]

[bars.bottom]
monitor = "eDP-1"
position = "bottom"
height = 36
transparent = true
bg = "#0000"
default_attrs = "default"
margin_left = 0
margin_internal = 10
margin_right = 10
ipc = true
panels_left = ["xworkspaces"]
panels_center = ["mpd"]
panels_right = ["temp","separator","cpu","separator","memory","separator","systray"]

[highlights.cyan]
underline_height = 5
underline_color = "#0ff"

[attrs.default]
bg = "default"
fg = "#ccc"
font = "FiraCode Nerd Font Mono 10"

[attrs.none]
bg = "none"

[attrs.manual]
bg = "manual"

[attrs.mpd]
bg = "none"
fg = "#fff"

[attrs.active_blocks]
bg = "active"
[attrs.nonempty_blocks]
bg = "nonempty"
fg = "#aaa"
[attrs.inactive_blocks]
bg = "inactive"
fg = "#777"

[bgs.default]
style = "bubble_prop"
radius = 12
color = "#000"

[bgs.manual]
style = "bubble"
border = 8
radius = 12
color = "#000"

# bubble backgrounds with a radius of 0 are rectangles
[bgs.active]
style = "bubble_prop"
radius = 0
color = "#444"

[bgs.inactive]
style = "bubble_prop"
radius = 0
color = "#0000"

[bgs.nonempty]
style = "bubble_prop"
radius = 0
color = "#0000"

[bgs.none]
style = "none"

[panels.xworkspaces]
type = "xworkspaces"
attrs_active = "active_blocks"
attrs_nonempty = "nonempty_blocks"
attrs_inactive = "inactive_blocks"
highlight_active = "cyan"

[panels.xwindow]
type = "xwindow"
max_width = 100

[panels.temp]
type = "temp"
format = "<span foreground='#0ff'>TEMP</span> %temp%°C"
zone = 7
interval = 2

# systray has known issues with bars that aren't transparent
[panels.systray]
type = "systray"
size = 24
padding = 0
sort = "window_name_lower"

[panels.memory]
type = "memory"
format = "<span foreground='#0ff'>RAM</span> %percentage_used%%"

[panels.cpu]
type = "cpu"
format = "<span foreground='#0ff'>CPU</span> %percentage%%"
interval = 2

[panels.pulseaudio]
type = "pulseaudio"
attrs = "manual"
ramp_unmuted = "pa"
ramp_muted = "pa_muted"
click_left = "toggle"
scroll_up = "increment"
scroll_down = "decrement"
unit = 1

[panels.network]
type = "network"
if_name = "wlan0"
# if_name = "eth0"
format_connected = "<span foreground='#0ff'>%ifname%</span> %essid% %local_ip%"
format_disconnected = "<span foreground='#0ff'>%ifname%</span> <span foreground='#888'>disconnected</span>"

[panels.mpd]
type = "mpd"
fg = "#fff"
attrs = "mpd"
progress_bar = true
max_width = 30
strategy = "scroll"
scroll_interval = 300
format_playing = "%shuffle% %main% <span font_size='20pt' rise='-5pt'>%prev% %toggle% %next%</span>"
format_paused = "%shuffle% %main% <span font_size='20pt' rise='-5pt'>%prev% %toggle% %next%</span>"
format_main = "%title% - %artist%"
format_shuffle = "<span font_size='25pt' rise='-7.5pt'>󰒟</span>"
format_prev = "󰒮"
format_toggle_playing = "󰏤"
format_toggle_paused = "󰐊"
format_next = "󰒭"

[panels.battery]
type = "battery"
format_full = "<span foreground='#0ff'>chom</span>"

[panels.clock]
type = "clock"
precisions = ["seconds","minutes"]
# toggle seconds
formats = ["<span foreground='#0ff'>%Y-%m-%d %T</span>","<span foreground='#0ff'>%Y-%m-%d %H:%M</span>"]
click_left = "cycle"
click_right = "cycle_back"

[panels.separator]
type = "separator"
attrs = "none"
format = " "
dependence = "left"

[ramps.pa]
0 = "<span font_size='25pt' rise='-7.5pt'>󰕿</span> "
1 = "<span font_size='25pt' rise='-7.5pt'>󰖀</span> "
2 = "<span font_size='25pt' rise='-7.5pt'>󰕾</span> "

[ramps.pa_muted]
0 = "<span font_size='25pt' rise='-7.5pt'>󰸈</span> "
1 = "<span font_size='25pt' rise='-7.5pt'>󰖁</span> "

Re-exports

• pub use builders::BarConfig;

Modules

• actions
  Configuration options for click/scroll events on panels.
• attrs
  Configuration options for colors and fonts.
• background
  Background configuration options.
• bar
  The bar itself and bar-related utility structs and functions.
• builders
  Builder structs for non-panel items, courtesy of derive_builder. See panels::builders for panel builders.
• cleanup
  Functions to ease a clean shutdown.
• common
  Common configuration for panels.
• image
  Support for embedding images onto the bar
• ipc
  Support for inter-process communication, like that provided by the lazybar-msg crate.
• macros
  Macros used internally which may be of use to other developers.
• panels
  Panels that can be added to the bar. A new panel must implement PanelConfig.
• parser
  The parser for the config.toml file.

Macros

• array_to_struct
  Defines a struct to hold format strings, along with a constructor.
• interned_atoms
  Holds a collection of X atoms, lazily checking their values as they’re retrieved.

Structs

• ButtonIndex
  Describes the position and size of a clickable button.
• Color
  The color
• Highlight
  Describes a bar to be drawn below a workspace name
• ManagedIntervalStream
  Custom [IntervalStream]
• ManagedIntervalStreamBuilder
  Builder for ManagedIntervalStream.
• Margins
  Describes the minimum width of gaps around panel groups.
• Ramp
  Utility data structure to display one of several strings based on a value in a range, like a volume icon.
• UnixStreamWrapper
  A wrapper struct to read indefinitely from a UnixStream and send the results through a channel.

Enums

• Alignment
  Describes where on the bar a panel should appear.
• ManagedIntervalStreamBuilderError
  Error type for ManagedIntervalStreamBuilder
• Position
  Describes where on the screen the bar should appear.

Traits

• PanelConfig
  The trait implemented by all panels. Provides support for parsing a panel and turning it into a PanelStream.

Functions

• get_table_from_config
  Removes a value from a given config table and returns an attempt at parsing it into a table
• markup_escape_text
• remove_array_from_config
  Removes a value from a given config table and returns an attempt at parsing it into an array
• remove_bool_from_config
  Removes a value from a given config table and returns an attempt at parsing it into a bool
• remove_color_from_config
  Removes a value from a given config table and returns an attempt at parsing it into a color
• remove_float_from_config
  Removes a value from a given config table and returns an attempt at parsing it into a float
• remove_string_from_config
  Removes a value from a given config table and returns an attempt at parsing it into a string
• remove_uint_from_config
  Removes a value from a given config table and returns an attempt at parsing it into a uint
• replace_consts
  Replaces references to constants (of the form %{const_name}) with their respective constants.

Type Aliases

• CursorFn
  This function receives a MouseEvent and determines what the cursor name should be. See CursorInfo::Dynamic for more details.
• IndexCache
  A cache for the position of clickable buttons.
• PanelDrawFn
  A function that can be called repeatedly to draw the panel. The cairo::Context will have its current point set to the top left corner of the panel. The second and third parameters are the x and y coordinates of that point relative to the top left corner of the bar.
• PanelEndpoint
  The channel endpoint associated with a panel.
• PanelHideFn
  A function that will be called whenever the panel is hidden. Use this to pause polling, unmap a child window, or make any other state changes that can be cheaply reversed.
• PanelRunResult
  The return type of the PanelConfig::run function.
• PanelShowFn
  A function that will be called whenever the panel is shown. Use this to resume polling, remap a child window, or make any other state changes that can be cheaply reversed.
• PanelShutdownFn
  A function that is called for each panel before the bar shuts down.
• PanelStream
  A stream that produces panel changes when the underlying data source changes.