# Lemonbuddy [![Build Status](https://travis-ci.org/jaagr/lemonbuddy.svg?branch=master)](https://travis-ci.org/jaagr/lemonbuddy) [![MIT License](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000?style=plastic)](https://github.com/jaagr/lemonbuddy/blob/master/LICENSE) A fast and easy-to-use tool for creating status bars. **Lemonbuddy** aims to help users build beautiful and highly customizable status bars for their desktop environment, without the need of having a black belt in shell scripting. Heres a few screenshots showing you what it can look like: [![sample screenshot](http://i.imgur.com/xvlw9iHt.png)](http://i.imgur.com/xvlw9iH.png) [![sample screenshot](http://i.imgur.com/cYQOuRrt.png)](http://i.imgur.com/cYQOuRr.png) [![sample screenshot](http://i.imgur.com/A6spiZZt.png)](http://i.imgur.com/A6spiZZ.png) [![sample screenshot](http://i.imgur.com/TY5a5r9t.png)](http://i.imgur.com/TY5a5r9.png) Please note that the project still is in early development, so please report any problems by [creating an issue ticket](https://github.com/jaagr/lemonbuddy/issues/new). ## Table of Contents * [Introduction](#introduction) * [Getting started](#getting-started) * [Dependencies](#dependencies) * [Building from source](#building-from-source) * [Running](#running) * [Launching the bar in your wm's bootstrap routine](#launching-the-bar-in-your-wms-bootstrap-routine) * [Configuration](#configuration) * [Fonts](#fonts) * [Syntax and DSL](#syntax-and-dsl) * [Application settings](#application-settings) * [Bar settings](#bar-settings) * [Modules](#modules) * [internal/backlight](#module-internalbacklight) * [internal/battery](#module-internalbattery) * [internal/bspwm](#module-internalbspwm) * [internal/cpu](#module-internalcpu) * [internal/date](#module-internaldate) * [internal/i3](#module-internali3) * [internal/memory](#module-internalmemory) * [internal/mpd](#module-internalmpd) * [internal/network](#module-internalnetwork) * [internal/volume](#module-internalvolume) * [custom/menu](#module-custommenu) * [custom/script](#module-customscript) * [custom/text](#module-customtext) * [Example configurations](#example-configurations) * [License](#license) ## Introduction The main purpose of **Lemonbuddy** is to help users create awesome status bars. It has built-in functionality to generate content for the most commonly used widgets, such as: - Playback controls and status display for [MPD](https://www.musicpd.org/) using [libmpdclient](https://www.musicpd.org/libs/libmpdclient/) - [ALSA](http://www.alsa-project.org/main/index.php/Main_Page) volume controls - Workspace and desktop panel for [bspwm](https://github.com/baskerville/bspwm) and [i3](https://github.com/i3/i3) - CPU and memory load indicator - Battery display - Network connection details - Backlight level - Date and time label - Time-based shell script execution - Command output tailing - User-defined menu tree - And more... Each bar contains a set of modules, which in turn defines a set of formatting rules and options. Read more about [how the configuration works](#configuration). ## Getting started If you are using **Arch Linux**, you can install the AUR package [lemonbuddy-git](https://aur.archlinux.org/packages/lemonbuddy-git/) to get the latest version, or [lemonbuddy](https://aur.archlinux.org/packages/lemonbuddy/) for the latest stable release. For **Void Linux** users, the application can be installed using XBPS: `xbps-install -S lemonbuddy`. If you create a package for any other distribution, please consider contributing the template so that we can make the application available for more people. ### Dependencies A compiler with c++14 support. For example [`clang`](http://clang.llvm.org/get_started.html). - cmake - boost - xcb-util-wm - libXft - python2 Optional dependencies for module support: - wireless_tools (required for `internal/network` support) - alsa-lib (required for `internal/volume` support) - libmpdclient (required for `internal/mpd` support) - jsoncpp (required for `internal/i3` support) ~~~ sh $ pacman -S cmake python2 boost xcb-util-wm libxft wireless_tools alsa-lib libmpdclient jsoncpp $ xbps-install cmake boost-devel libxcb-util-dev alsa-lib-devel i3-devel libmpdclient-devel jsoncpp-devel wireless_tools-devel $ apt-get install cmake libxcb1-dev xcb-proto python-xcbgen libboost-dev libiw-dev libasound2-dev libmpdclient-dev libjsoncpp-dev libfreetype6-dev ~~~ ### Building from source Please [report any problems](https://github.com/jaagr/lemonbuddy/issues/new) you run into when building the project. It helps alot. ~~~ sh $ git clone --branch 2.0.0-beta --recursive https://github.com/jaagr/lemonbuddy $ mkdir lemonbuddy/build $ cd lemonbuddy/build $ cmake -DCMAKE_BUILD_TYPE=Release .. $ sudo make install ~~~ ## Running Before customizing the bar, make sure everything works as expected by trying out one of the example configurations installed with the application. The following code will get you started: ~~~ sh # Create the config root directory $ mkdir -p ${XDG_CONFIG_HOME:-$HOME/.config}/lemonbuddy $ cd ${XDG_CONFIG_HOME:-$HOME/.config}/lemonbuddy # Copy sample config for the running wm (uses a wm agnostic config as fallback) $ __wm=$(pgrep -l -x "(bspwm|i3)"); __prefix=$(which lemonbuddy) $ cp "${__prefix%%/bin*}/share/examples/lemonbuddy/config${__wm:+.${__wm##* }}" config # Launch the bar # (where "example" is the name of the bar as defined by [bar/NAME] in the config) $ lemonbuddy example ~~~ > **NOTE:** In case the bar output looks odd, it's probably because you're > missing he fonts defined in the config. Update the config or install the > missing fonts. ## Launching the bar in your wm's bootstrap routine Create an executable file containing the startup logic, for example `$HOME/.config/lemonbuddy/launch.sh`: ~~~ sh #!/usr/bin/env sh # Terminate already running bar instances killall -q lemonbuddy # Launch bar1 and bar2 lemonbuddy bar1 & lemonbuddy bar2 & echo "Bars launched..." ~~~ Make it executable: ~~~ sh $ chmod +x $HOME/.config/lemonbuddy/launch.sh ~~~ If you are using **bspwm**, add the following line to `bspwmrc`: ~~~ sh $HOME/.config/lemonbuddy/launch.sh ~~~ If you are using **i3**, add the following line to your configuration: ~~~ sh exec_always --no-startup-id $HOME/.config/lemonbuddy/launch.sh ~~~ ## Configuration The configuration syntax is a work in progress. Please [create an issue ticket](https://github.com/jaagr/lemonbuddy/issues/new) and let me know how you think we can improve it. The values used in the examples below are to be considered placeholder values, and the resulting output might not be award-winning. ### Fonts When working with unicode symbols, remember that fonts render the symbols differently. Changing font can drastically improve the quality of your bar. [Unifont](http://unifoundry.com/unifont.html) has great unicode coverage, which makes it really useful. Also try different icon fonts, such as [Font Awesome](http://fontawesome.io/icons), [Material Icons](https://design.google.com/icons) and my personal favorite: [Siji](https://github.com/stark/siji). *TODO: Describe usage in configuration...* ### Syntax and DSL *TODO: Clarify...* The configuration syntax is based on the `ini` file format. ~~~ ini [section/name] str = My string ; Hint: Quote the value to keep the spaces str = " My string" bool = true bool = on int = 10 float = 10.0 ; Values for a defined bar can be referenced using: key = ${bar/top.foreground} ; Values for the current bar can be referenced using: key = ${BAR.foreground} ; Other values can be referenced using: key = ${section.key} ; Environment variables can be referenced using: key = ${env:VAR_NAME} ~~~ ~~~ ini [section/name] ; Most modules define a format-N field ; For example, the mpd module defines the following formats: ; format-online = ... ; format-offline = ... ; ; Each format exposes the following fields: ; format[-NAME]-padding = N (unit: whitespaces) ; format[-NAME]-margin = N (unit: whitespaces) ; (See "Bar settings" for more details on "spacing") ; format[-NAME]-spacing = N (unit: whitespaces) ; (This value will displace the format block horizontally by +/-N pixels) ; format[-NAME]-offset = N (unit: pixels) ; format[-NAME]-foreground = #aa[rrggbb] ; format[-NAME]-background = #aa[rrggbb] ; format[-NAME]-underline = #aa[rrggbb] ; ^ ; | the underline and overline color is always the same ; v ; format[-NAME]-overline = #aa[rrggbb] ; ; The rest of the drawtypes follow the same pattern. ; ; label-NAME[-(foreground|background|(under|over)line|font|padding|maxlen|ellipsis)] = ? ; icon-NAME[-(foreground|background|(under|over)line|font|padding)] = ? ; ramp-NAME-[0-9]+[-(foreground|background|(under|over)line|font|padding)] = ? ; animation-NAME-[0-9]+[-(foreground|background|(under|over)line|font|padding)] = ? ; ; bar-NAME-width = N (unit: characters) ; bar-NAME-format = (tokens: %fill% %indicator% %empty%) ; bar-NAME-foreground-[0-9]+ = #aarrggbb ; bar-NAME-indicator[-(foreground|background|(under|over)line|font|padding)] = ; bar-NAME-fill[-(foreground|background|(under|over)line|font|padding)] = ; bar-NAME-empty[-(foreground|background|(under|over)line|font|padding)] = ; ; Example: ; format-online = format-offline = format-offline-offset = -8 ; Cap the song label without trailing ellipsis label-song-maxlen = 30 label-song-ellipsis = false ; By only specifying alpha value, it will be applied to the bar's default foreground label-time-foreground = #66 label-offline =  mpd is off label-offline-foreground = #66 icon-play =  icon-pause =  icon-stop =  bar-progress-width = 30 bar-progress-indicator = | bar-progress-fill = █ bar-progress-empty = █ bar-progress-empty-foreground = #44 ~~~ ### Application settings ~~~ ini [settings] ; Limit the amount of update events within a set timeframe: ; - "Allow updates within of time" ; Default values: throttle-limit = 3 throttle-ms = 60 ~~~ ### Bar settings ~~~ ini [bar/example] ; Use the following command to list available outputs: ; If unspecified, the application will pick the first one it finds. ; $ xrandr -q | grep " connected" | cut -d ' ' -f1 monitor = HDMI1 ; Omit the % to specify the width in pixels width = 100% height = 30 ; Offset value defined in pixels offset-x = 0 offset-y = 0 ; Put the bar at the bottom of the screen bottom = true ; Weather to force docking mode or not ; If you are using i3wm it's recommended to use the default value ; Default: false dock = true ; This value is used as a multiplier when adding spaces between elements spacing = 3 ; Height of under-/overline lineheight = 14 ; Colors background = #ee222222 foreground = #eefafafa linecolor = ${bar/example.background} ; Borders ; Size to be used for all borders border-size = 2 ; Color to be used for all borders border-color = #ff9900 ; Per-border values ;border-top = 1 ;border-top-color = #ff9900 ;border-bottom = 2 ;border-bottom-color = #5d00ff ;border-left = 3 ;border-right-color = #ff0059 ; Number of spaces to add at the beginning/end of the bar padding-left = 5 padding-right = 2 ; Amount of spaces to add before/after each module module-margin-left = 3 module-margin-right = 3 ; Fonts are defined using: ; font-0 = NotoSans-Regular:size=8;0 font-1 = MaterialIcons:size=10;0 font-2 = Termsynu:size=8;-1 font-3 = FontAwesome:size=10;0 ; The separator will be inserted between the output of each module separator = | ; Value to be used to set the WM_NAME atom ; This defaults to "lemonbuddy-[BAR]_[MONITOR]" wm-name = mybar ; Locale used to localize module output (for example date) ;locale = sv_SE.UTF-8 ; Define what modules to output modules-left = cpu ram modules-center = label modules-right = clock ; Position of the tray container ; If undefined, tray support will be disabled ; ; Available positions: ; left ; right tray-position = right ; Restack the bar window and put it above the ; selected window manager's root ; ; Fixes the issue where the bar is being drawn ; on top of fullscreen window's ; ; Currently supported WM's: ; bspwm ; i3 ; Default: none wm-restack = bspwm ~~~ ### Modules #### Module `internal/backlight` ~~~ ini [module/backlight] type = internal/backlight ; Use the following command to list available cards: ; $ ls -1 /sys/class/backlight/ card = intel_backlight ~~~ ##### Extra formatting (example) ~~~ ini ; Available tags: ;