Awesome WM Widgets

This is a project page of the GitHub repo with set of widgets for Awesome Window Manager

Prerequisite

To have a consistent color palette through all the widgets add following section to your theme.lua. This will also allow you to easily change colors of the widgets in one place.

theme.widget_main_color = "#74aeab"
theme.widget_red = "#e53935"
theme.widget_yelow = "#c0ca33"
theme.widget_green = "#43a047"
theme.widget_black = "#000000"
theme.widget_transparent = "#00000000"

However text widgets (for example currently playing song in spotify widget) are using theme.fg_normal color. So you need to set it as well.

Battery widget

Simple and easy-to-install widget for Awesome Window Manager.

This widget consists of:

  • an icon which shows the battery level:
    Battery Widget
  • a pop-up window, which shows up when you hover over an icon:
    Battery Widget Alternatively you can use a tooltip (check the code):
    Battery Widget
  • a pop-up warning message which appears on bottom right corner when battery level is less that 15% (you can get the image here):
    Battery Widget

Note that widget uses the Arc icon theme, so it should be installed first under /usr/share/icons/Arc/ folder.

Installation

This widget reads the output of acpi tool.

  • install acpi and check the output:
$ sudo apt-get install acpi
$ acpi
Battery 0: Discharging, 66%, 02:34:06 remaining

Then refer to the installation section of the repo.

Batteryarc widget

This widget is more informative version of battery widget.

Depending of the battery status it may look one of the following ways:

  • 10_d - less than 15 percent
  • 10_c - less than 15 percent, charging
  • 20_d - between 15 and 40 percent
  • 20_c - between 15 and 40 percent, charging
  • 80_d - more than 40 percent
  • 80_c - more than 40 percent, charging

Widget uses following beautiful variables with values:

theme.widget_main_color = "#74aeab"
theme.widget_red = "#e53935"
theme.widget_yellow = "#c0ca33"
theme.widget_green = "#43a047"
theme.widget_black = "#000000"
theme.widget_transparent = "#00000000"

which means that you need to copy the code above and paste it in your theme.lua. Otherwise you can change colors directly in the widget.

Installation

Clone repo, include widget and use it in rc.lua:

local batteryarc_widget = require("awesome-wm-widgets.batteryarc-widget.batteryarc")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
		...
		batteryarc_widget,
		...

You can get the icon for warning popup here

Troubleshooting

In case of any doubts or questions don’t hesitate to raise an issue.

Brightness widget

This widget represents current brightness level: Brightness widget

Installation

First you need to get the current brightness level. There are two options:

  • using xbacklight command (depending on your video card (I guess) it may or may not work)

    To check if it works install xbackligth and check if it works:

     sudo apt-get install xbacklight
     xbacklight -get
    

    If there is no output it means that it doesn’t work, but there is a second option:

  • using light command

    Install it from this git repo: github.com/haikarainen/light and check if it works but running

     git clone https://github.com/haikarainen/light.git && \
     cd ./light && \
     sudo make && sudo make install \
     light -G
     49.18
    

Depending on the chosen option change GET_BRIGHTNESS_CMD variable in brightness.lua.

Then clone this repo under ~/.config/awesome/:

git clone https://github.com/streetturtle/awesome-wm-widgets.git ~/.config/awesome/

Require widget at the beginning of rc.lua:

local brightness_widget = require("awesome-wm-widgets.brightness-widget.brightness")

Add widget to the tasklist:

s.mytasklist, -- Middle widget
    { -- Right widgets
        layout = wibox.layout.fixed.horizontal,
        ...
        brightness_widget,
        ...

Controls

In order to change brightness by shortcuts you can add them to the globalkeys table in the rc.lua:

awful.key({ modkey         }, ";", function () awful.spawn("light -A 5") end, {description = "increase brightness", group = "custom"}),
awful.key({ modkey, "Shift"}, ";", function () awful.spawn("light -U 5") end, {description = "decrease brightness", group = "custom"}),

On laptop you can use XF86MonBrightnessUp and XF86MonBrightnessDown keys.

CPU widget

This widget shows the average CPU load among all cores of the machine:

screenshot

When the load is more than 80% the graph becomes red. You can easily customize the widget by changing colors, step width, step spacing, width and interval.

How it works

To measure the load I took Paul Colby’s bash script and rewrote it in Lua, which was quite simple. So awesome simply reads the first line of /proc/stat:

$ cat /proc/stat | grep '^cpu '
cpu  197294 718 50102 2002182 3844 0 2724 0 0 0

and calculates the percentage.

Installation

  1. Clone this repo under ~/.config/awesome/

     git clone https://github.com/streetturtle/awesome-wm-widgets.git ~/.config/awesome/
    
  2. Require spotify-widget at the beginning of rc.lua:

     local cpu_widget = require("awesome-wm-widgets.cpu-widget.cpu-widget")
    
  3. Add widget to the tasklist:

     s.mytasklist, -- Middle widget
         { -- Right widgets
             layout = wibox.layout.fixed.horizontal,
             ...
             cpu_widget,
             ...
    

Email widget

This widget consists of an icon with counter which shows number of unread emails: email icon and a popup message which appears when mouse hovers over an icon: email popup

Note that widget uses the Arc icon theme, so it should be installed first under /usr/share/icons/Arc/ folder.

Installation

To install it put email.lua and email-widget folder under ~/.config/awesome. Then

  • in email.lua cahnge path to python scripts;
  • in python scripts add your credentials (note that password should be encrypted using pgp for example);
  • add widget to awesome:
require("email")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
		...
		email_icon,
        email_widget,
		...      

How it works

This widget uses the output of two python scripts, first is called every 20 seconds - it returns number of unread emails and second is called when mouse hovers over an icon and displays content of those emails. For both of them you’ll need to provide your credentials and imap server. For testing they can simply be called from console:

python ~/.config/awesome/email/count_unread_emails.py 
python ~/.config/awesome/email/read_emails.py 

MPD Widget

Music Player Daemon widget by @raphaelfournier.

Prerequisite

Install mpd (Music Player Daemon itself) and mpc (Music Player Client - program for controlling mpd), both should be available in repo, e.g for Ubuntu:

sudo apt-get install mpd mpc

Set them up and then just follow the installation section of the repo.

Ram widget

This widget shows the RAM usage. When clicked another widget appears with more detailed information:

screenshot

Installation

  1. Clone this repo under ~/.config/awesome/

     git clone https://github.com/streetturtle/awesome-wm-widgets.git ~/.config/awesome/
    
  2. Require spotify-widget at the beginning of rc.lua:

     local ram_widget = require("awesome-wm-widgets.ram-widget.ram-widget")
    
  3. Add widget to the tasklist:

     s.mytasklist, -- Middle widget
         { -- Right widgets
             layout = wibox.layout.fixed.horizontal,
             ...
             ram_widget,
             ...
    

Spotify widget

This widget displays currently playing song on Spotify for Linux client: screenshot and consists of two parts:

  • status icon which shows if music is currently playing
  • artist and name of the current song playing

Controls

  • left click - play/pause
  • scroll up - play next song
  • scroll down - play previous song

Dependencies

Note that widget uses the Arc icon theme, so it should be installed first under /usr/share/icons/Arc/ folder.

Installation

  1. Install sp - CLI client for Spotify for Linux:

     $ sudo git clone https://gist.github.com/fa6258f3ff7b17747ee3.git ~/dev/
     $ sudo ln -s ~/dev/sp /usr/local/bin/
    

    Check if it works by running sp help.

  2. Get an ‘id’ and ‘secret’ from developer.spotify.com and paste it in the header of the sp (SP_ID and SP_SECRET) - this enables search feature.

  3. Clone this repo under ~/.config/awesome/

     git clone https://github.com/streetturtle/awesome-wm-widgets.git ~/.config/awesome/
    
  4. Require spotify-widget at the beginning of rc.lua:

     local spotify_widget = require("awesome-wm-widgets.spotify-widget.spotify")
    
  5. Add widget to the tasklist:

     s.mytasklist, -- Middle widget
         { -- Right widgets
             layout = wibox.layout.fixed.horizontal,
             ...
             spotify_widget,
             ...
    

Volume widget

Simple and easy-to-install widget for Awesome Window Manager which represents the sound level: Volume Widget

Note that widget uses the Arc icon theme, so it should be installed first under /usr/share/icons/Arc/ folder.

Installation

  • clone/copy volume.lua file;

  • include volume.lua and add volume widget to your wibox in rc.lua:

require("volume")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
		...
		volume_widget,
		...      
  • Optional step. In Arc icon theme the muted audio level icon (Volume-widget looks like 0 level icon, which could be a bit misleading. So I decided to use original muted icon for low audio level, and the same icon, but colored in red for muted audio level. Fortunately icons are in svg format, so you can easily recolor them with sed, so it would look like this (Volume Widget)):
 cd /usr/share/icons/Arc/status/symbolic && 
 sudo cp audio-volume-muted-symbolic.svg audio-volume-muted-symbolic_red.svg && 
 sudo sed -i 's/bebebe/ed4737/g' ./audio-volume-muted-symbolic_red.svg 

Control volume

To mute/unmute click on the widget. To increase/decrease volume scroll up or down when mouse cursor is over the widget.

If you want to control volume level by keyboard shortcuts add following lines in shortcut section of the rc.lua (the commands could be slightly different depending on your PC configuration):

awful.key({ modkey}, "[", function () awful.spawn("amixer -D pulse sset Master 5%-") end, {description = "increase volume", group = "custom"}),
awful.key({ modkey}, "]", function () awful.spawn("amixer -D pulse sset Master 5%+") end, {description = "decrease volume", group = "custom"}),
awful.key({ modkey}, "\", function () awful.spawn("amixer -D pulse set Master +1 toggle") end, {description = "mute volume", group = "custom"}),

Volumearc widget

Almost the same as volumebar widget, but using arcchart:

screenshot

Installation

  1. Clone this repo under ~/.config/awesome/

     git clone https://github.com/streetturtle/awesome-wm-widgets.git ~/.config/awesome/
    
  2. Require volumearc widget at the beginning of rc.lua:

     local volumearc_widget = require("awesome-wm-widgets.volumearc-widget.volumearc")
    
  3. Add widget to the tasklist:

     s.mytasklist, -- Middle widget
         { -- Right widgets
             layout = wibox.layout.fixed.horizontal,
             ...
             volumearc_widget,
             ...
    

Control volume

To mute/unmute click on the widget. To increase/decrease volume scroll up or down when mouse cursor is over the widget.

If you want to control volume level by keyboard shortcuts add following lines in shortcut section of the rc.lua (the commands could be slightly different depending on your PC configuration):

awful.key({ modkey}, "[", function () awful.spawn("amixer -D pulse sset Master 5%-") end, {description = "increase volume", group = "custom"}),
awful.key({ modkey}, "]", function () awful.spawn("amixer -D pulse sset Master 5%+") end, {description = "decrease volume", group = "custom"}),
awful.key({ modkey}, "\", function () awful.spawn("amixer -D pulse set Master +1 toggle") end, {description = "mute volume", group = "custom"}),

Volumebar widget

Almost the same as volume widget, but more minimalistic:

screenshot

Supports

  • scroll up - increase volume,
  • scroll down - decrease volume,
  • left click - mute/unmute.

Installation

  1. Clone this repo under ~/.config/awesome/

     git clone https://github.com/streetturtle/awesome-wm-widgets.git ~/.config/awesome/
    
  2. Require volumearc widget at the beginning of rc.lua:

     local volumebar_widget = require("awesome-wm-widgets.volumebar-widget.volumebar")
    
  3. Add widget to the tasklist:

     s.mytasklist, -- Middle widget
         { -- Right widgets
             layout = wibox.layout.fixed.horizontal,
             ...
             volumebar_widget,
             ...
    

Control volume

To mute/unmute click on the widget. To increase/decrease volume scroll up or down when mouse cursor is over the widget.

If you want to control volume level by keyboard shortcuts add following lines in shortcut section of the rc.lua (the commands could be slightly different depending on your PC configuration):

awful.key({ modkey}, "[", function () awful.spawn("amixer -D pulse sset Master 5%-") end, {description = "increase volume", group = "custom"}),
awful.key({ modkey}, "]", function () awful.spawn("amixer -D pulse sset Master 5%+") end, {description = "decrease volume", group = "custom"}),
awful.key({ modkey}, "\", function () awful.spawn("amixer -D pulse set Master +1 toggle") end, {description = "mute volume", group = "custom"}),

Troubleshooting

If the bar is not showing up, try to decrease top or bottom margin - widget uses hardcoded margins for vertical alignment, so if your wibox is too small then bar is simply hidden by the margins.

Weather widget

Weather Widget

Note that widget uses the Arc icon theme, so it should be installed first under /usr/share/icons/Arc/ folder.

Installation

  1. Install lua socket - to make HTTP calls to get the weather information.

     $ sudo apt-get install lua-socket
    
  2. Download json parser for lua from github.com/rxi/json.lua and place it under ~/.config/awesome/ (don’t forget to star a repo ):

     wget -P ~/.config/awesome/ https://raw.githubusercontent.com/rxi/json.lua/master/json.lua
    
  3. Clone this repo under ~/.config/awesome/:

     git clone https://github.com/streetturtle/awesome-wm-widgets.git ~/.config/awesome/
    
  4. Get Open Weather Map app id here: openweathermap.org/appid and place it in ~/.config/awesome/awesome-wm-widgets/secrets.lua, or directly in the widget. Don’t forget to set also your city.

  5. Require weather widget at the beginning of rc.lua:

     local weather_widget = require("awesome-wm-widgets.weather-widget.weather")
    
  6. Add widget to the tasklist:

     s.mytasklist, -- Middle widget
         { -- Right widgets
             layout = wibox.layout.fixed.horizontal,
             ...
             weather_widget,
             ...
    

You can read how it works in more details here

Spotify Shell

demo

Features

  1. Supports following commands (same as sp client):
    • play/pause/next;
    • any other string will start a search and play the first result for a given search query;
    • feh - shows the current artwork with feh;
  2. Stores history and allows navigate through it;

  3. Highly customizable

Controls

Keyboard navigation (copied from awful.prompt API documentation page):

Name Usage
CTRL+A beginning-of-line
CTRL+B backward-char
CTRL+C cancel
CTRL+D delete-char
CTRL+E end-of-line
CTRL+J accept-line
CTRL+M accept-line
CTRL+F move-cursor-right
CTRL+H backward-delete-char
CTRL+K kill-line
CTRL+U unix-line-discard
CTRL+W unix-word-rubout
CTRL+BACKSPAC unix-word-rubout
SHIFT+INSERT paste
HOME beginning-of-line
END end-of-line
CTRL+R reverse history search, matches any history entry containing search term.
CTRL+S forward history search, matches any history entry containing search term.
CTRL+UP ZSH up line or search, matches any history entry starting with search term.
CTRL+DOWN ZSH down line or search, matches any history entry starting with search term.
CTRL+DELETE delete the currently visible history entry from history file. This does not delete new commands or history entries under user editing.

Installation

  1. Install sp - CLI client for Spotify for Linux:

     $ sudo git clone https://gist.github.com/fa6258f3ff7b17747ee3.git ~/dev/
     $ sudo ln -s ~/dev/sp /usr/local/bin/
    

    Check if it works by running sp help.

  2. Get an ‘id’ and ‘secret’ from developer.spotify.com and paste it in the header of the sp (SP_ID and SP_SECRET) - this enables search feature.

  3. Clone this repo under ~/.config/awesome/

     git clone https://github.com/streetturtle/awesome-wm-widgets.git ~/.config/awesome/
    
  4. Require spotify-shell at the beginning of rc.lua:

     local spotify_shell = require("awesome-wm-widgets.spotify-shell.spotify-shell")
    
  5. Add a shortcut which will show Spotify Shell widget:

     awful.key({ modkey, }, "d", function () spotify_shell.launch() end, {description = "spotify shell", group = "music"}),
    
  6. It uses icon from Papirus Icon Theme. So you should either install this icon theme, or download an icon you want to use and provide path to it in spotify-shell.lua.

Translate Shell

This widget allows quickly translate words or phrases without opening a browser - just using Awesome. To provide direction of the translation add the 2 letters code of the source and target languages at the end of the phrase, for example hello enfr will translate hello from English to French. This widget is based on Yandex.Translate API.

demo

Controls

  • Mod4 + c - opens a translate prompt;
  • left click on the popup widget - copies the translation to the clipboard and closes widget;
  • right click on the popup widget - copies text to translate to the clipboard and closes widget.

Installation

  1. Clone repo under ~/.config/awesome/

     git clone https://github.com/streetturtle/awesome-wm-widgets.git ~/.config/awesome/
    
  2. Get an API key and paste it in translate.lua as value of the API_KEY variable
  3. Require widget in rc.lua:

     local translate = require("awesome-wm-widgets.translate-widget.translate")
    
  4. Add a shortcut to run translate prompt:

     awful.key({ modkey }, "c",
               function()
                   translate.show_translate_prompt()
               end,
               { description = "run translate prompt", group = "launcher" }
     ),
    

Here is nice-looking and super easy way to customize taglist. The idea is simple - literally write ‘awesome’ or ‘awesomewm’ (if you want to keep 9 tags) in the taglist using characters from the Awesome logo.

To do it you need to install a font which was generated from the svg images of the letters from the logo. Download it from here and place it under ~/.local/share/fonts. Then name your tags in rc.lua using it. The font has two types of letters: uppercase are for the bold characters:

awful.tag({ "A", "W", "E", "S", "O", "M", "E", "W", "M"},

awesome-taglist

and lowercase for the outline characters:

awful.tag({ "a", "w", "e", "s", "o", "m", "e", "w", "m"},

awesome-taglist

To have same colors as on the screenshots, use following configuration:

theme.lua

theme.taglist_fg_focus    = "#3992af"
theme.taglist_fg_occupied = "#164b5d"
theme.taglist_fg_urgent   = "#ED7572"
theme.taglist_fg_empty    = "#828282"
theme.taglist_spacing     = 2
theme.taglist_font        = "awesomewm 11"

Taglist

Here is a trick to toggle system tray visibility in Awesome using keyboard shortcut. The reason to do that is pretty simple - it looks ugly in some themes. In my case I don’t like two things about it:

  • I didn’t manage to make it transparent which is quite important since I am using transparent tasklist and widgets. I tried wibox.widget.systray.opacity property which doesn’t work as well as setting an alpha channel for beautiful.bg_systray.

  • Colors of the apps are very different from theme colors which makes systray look flashy and disturbing:

systray screenshot

On the other hand not showing it at all will make interaction with some apps pretty difficult. So having a keyboard shortcut which toggles its visibility sounds like a good solution for the problems mentioned above.

To do it create a systray widget inside awful.screen.connect_for_each_screen function:

awful.screen.connect_for_each_screen(function(s)
    ...
    s.systray = wibox.widget.systray()
    s.systray.visible = false
    ...

Then add it to the the wibox: replace default wibox.widget.systray() by s.systray inside s.mywibox:setup method:

s.mywibox:setup {
    ...
    s.mytasklist, -- Middle widget
    {
        ...
        s.systray
    ...

Almost done, the only thing left is a shortcut, I use mod + =:

awful.key({ modkey }, "=", function ()
    awful.screen.focused().systray.visible = not awful.screen.focused().systray.visible
    end, {description = "Toggle systray visibility", group = "custom"})
)