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. Note that text widgets (for example text in spotify-widget) are using color defined in theme.fg_normal.

-- https://github.com/streetturtle/awesome-wm-widget
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"

I would also recommend to install Play font as it looks good and explicitly used in some widgets. However you can easily change font in widget’s source.

Battery widget

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

This widget consists of:

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

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

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

*Note: the widget expects following icons be present in the folder:

• battery-caution-charging-symbolic.svg
• battery-empty-charging-symbolic.svg
• battery-full-charged-symbolic.svg
• battery-full-symbolic.svg
• battery-good-symbolic.svg
• battery-low-symbolic.svg
• battery-caution-symbolic.svg
• battery-empty-symbolic.svg
• battery-full-charging-symbolic.svg
• battery-good-charging-symbolic.svg
• battery-low-charging-symbolic.svg
• battery-missing-symbolic.svg

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

local battery_widget = require("awesome-wm-widgets.battery-widget.battery")

...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
		...
		battery_widget(),
		...

Batteryarc widget

This widget is more informative version of battery widget.

Depending of the battery status it could look following ways:

• - less than 15 percent
• - less than 15 percent, charging
• - between 15 and 40 percent
• - between 15 and 40 percent, charging
• - more than 40 percent
• - more than 40 percent, charging

If a battery level is low then warning popup will show up:

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Requirements

This widget requires the acpi command to be available to retrieve battery and power information.

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,
		...
        --[[default]]
		batteryarc_widget(),		
        --[[or customized]]
        batteryarc_widget({
            show_current_level = true,
            arc_thickness = 1,
        }),
	}
	...

Troubleshooting

In case of any doubts or questions please raise an issue.

Bitbucket widget

The widget shows the number of pull requests assigned to the user and when clicked shows them in the list with some additional information. When item in the list is clicked - it opens the pull request in the browser.

How it works

Widget uses cURL to query Bitbucket’s REST API. In order to be authenticated, widget uses a netrc feature of the cURL, which is basically to store basic auth credentials in a .netrc file in home folder.

Bitbucket allows using App Passwords (available in the account settings) - simply generate one for the widget and use it as password in .netrc file.

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Installation

Create a .netrc file in you home directory with following content:

machine api.bitbucket.org
login mikey@tmnt.com
password cowabunga

Then change file’s permissions to 600 (so only you can read/write it):

chmod 600 ~/.netrc

And test if it works by calling the API:

curl -s -n 'https://api.bitbucket.org/2.0/repositories/'

Also to properly setup required parameters you can use test_bitbucket_api.sh script - it uses the same curl call as widget.

Then clone/download repo and use widget in rc.lua:

local bitbucket_widget = require("awesome-wm-widgets.bitbucket-widget.bitbucket")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
		...
		-- default
		bitbucket_widget({
		    host = 'https://api.bitbucket.org',
            uuid = 'your-uuid',
            workspace = 'workspace',
            repo_slug = 'slug'

		}}),
		...

Brightness widget

This widget represents current brightness level:

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Example:

brightness_widget({
    get_brightness_cmd = 'xbacklight -get',
    inc_brightness_cmd = 'xbacklight -inc 5',
    dec_brightness_cmd = 'xbacklight -dec 5'
})

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
  

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

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

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,
        ...
        -- default
        brightness_widget(),
        -- or customized
        brightness_widget({
          get_brightness_cmd = 'xbacklight -get',
          inc_brightness_cmd = 'xbacklight -inc 5',
          dec_brightness_cmd = 'xbacklight -dec 5'
        })      
    }
        ...

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.

Brightness widget

This widget represents current brightness level:

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Example:

brightnessarc_widget({
    get_brightness_cmd = 'xbacklight -get',
    inc_brightness_cmd = 'xbacklight -inc 5',
    dec_brightness_cmd = 'xbacklight -dec 5'
    color = '/usr/share/icons/Arc/status/symbolic/brightness-display-symbolic.svg'
})

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
  

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

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

Require widget at the beginning of rc.lua:

local brightnessarc_widget = require("awesome-wm-widgets.brightnessarc-widget.brightnessarc")

Add widget to the tasklist:

s.mytasklist, -- Middle widget
    { -- Right widgets
        layout = wibox.layout.fixed.horizontal,
        ...
        -- default
        brightnessarc_widget(),
        -- or customized
        brightnessarc_widget({
          get_brightness_cmd = 'xbacklight -get',
          inc_brightness_cmd = 'xbacklight -inc 5',
          dec_brightness_cmd = 'xbacklight -dec 5'
        })      
    }
        ...

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.

Calendar Widget

Calendar widget for Awesome WM - slightly improved version of the wibox.widget.calendar.

Features

• mouse support: scroll up - shows next month, scroll down - previous

• themes:

  Name	Screenshot
  nord (default)
  outrun
  light
  dark

• setup widget placement

top center - in case you clock is centered:

top right - for default awesome config:

bottom right - in case your wibar at the bottom:

How to use

This widget needs an ‘anchor’ - another widget which triggers visibility of the calendar. Default mytextclock is the perfect candidate!
Just after mytextclock is instantiated, create the widget and add the mouse listener to it.

local calendar_widget = require("awesome-wm-widgets.calendar-widget.calendar")
-- ...
-- Create a textclock widget
mytextclock = wibox.widget.textclock()
-- default
local cw = calendar_widget()
-- or customized
local cw = calendar_widget({
    theme = 'outrun',
    placement = 'bottom_right'
})
mytextclock:connect_signal("button::press", 
    function(_, _, _, button)
        if button == 1 then cw.toggle() end
    end)

CPU widget

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

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.

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Example

cpu_widget({
    width = 70,
    step_width = 2,
    step_spacing = 0,
    color = '#434c5e'
})

The config above results in the following widget:

Installation

Clone/download repo and use widget in rc.lua:

local cpu_widget = require("awesome-wm-widgets.cpu-widget.cpu-widget")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
		...
		-- default
		cpu_widget(),
		-- or custom
		cpu_widget({
            width = 70,
            step_width = 2,
            step_spacing = 0,
            color = '#434c5e'
        })
		...

Docker Widget

The widget allows to manage docker containers, namely start/stop/pause/unpause:

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Installation

Clone the repo under ~/.config/awesome/ and add widget in rc.lua:

local docker_widget = require("awesome-wm-widgets.docker-widget.docker")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
        ...
        -- default
        docker_widget(),
        -- customized
        github_activity_widget{
            number_of_containers = 5
        },

Email widget

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

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 change 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 

Storage Widget

This widget shows disk usage. When clicked another widget appears with more detailed information. By default it monitors the “/” mount. It can be configured with a list of mounts to monitor though only the first will show in the wibar. To have multiple mounts displayed on the wibar simply define multiple storage_widgets with different mounts as arguments.

  local storage_widget = require("awesome-wm-widgets.storage-widget.storage-widget")
  ...
  s.mywibox:setup {
      s.mytasklist, -- Middle widget
      { -- Right widgets
      storage_widget(), --default
      wibox.widget.textbox(':'),
      storage_widget({ mounts = { '/', '/mnt/musicj' } }), -- multiple mounts
  ...

Installation

Please refer to the installation section of the repo.

Gerrit widget

It shows number of currently assigned reviews in Gerrit to the user (by default) :

when clicked it shows reviews in a list:

left click on an item will open review in the default browser, right click will copy the review number, which you can use to checkout this review by running git-review -d <review number>.

Also, if a new review is assigned to the user, there will be a pop-up:

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Prerequisite

• curl - is used to communicate with gerrit’s REST API
• setup netrc which is used to store username and password in order to call API’s endpoints.

Installation

1. This widget relies on Gerrit REST API, so you need to have a permission to access it. You also need to setup netrc, as widget uses curl to communicate with API and you have to be authenticated. To test if you have access to API and netrc setup is correct run following command, you should have a json response:

     curl  -s --request GET --netrc https://gerrit-host.com/a/changes/\?q\=status:open+AND+NOT+is:wip+AND+is:reviewer | tail -n +2
   

   Note: tail -n +2 is needed to skip first line of the response, as gerrit returns some characters there in order to prevent XSS hacks.

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 (if not cloned yet) under ~/.config/awesome/:

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

4. Require widget at the top of the rc.lua:

    local gerrit_widget = require("awesome-wm-widgets.gerrit-widget.gerrit")
   

5. Add widget to the tasklist:

    s.mytasklist, -- Middle widget
        { -- Right widgets
            layout = wibox.layout.fixed.horizontal,
            ...
            --default
            gerrit_widget({host = 'https://gerrit.tmnt.com'}),
            --customized
            gerrit_widget({
                host = 'https://gerrit.tmnt.com',
                query = 'is:reviewer AND is:wip'
            })
            ...
   

GitHub Activity Widget

Widget shows recent activities on GitHub. It is very similar to the GitHub’s “All activity” feed on the main page:

Mouse click on the item opens repo/issue/pr depending on the type of the activity. Mouse click on user’s avatar opens user GitHub profile.

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Installation

Clone repo under ~/.config/awesome/ and add widget in rc.lua:

local github_activity_widget = require("awesome-wm-widgets.github-activity-widget.github-activity-widget")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
        ...
        -- default
        github_activity_widget{
            username = 'streetturtle',
        },
        -- customized
        github_activity_widget{
            username = 'streetturtle',
            number_of_events = 5
        },

How it works

Everything starts with this timer, which gets recent activities by calling GitHub Events API and stores the response under /.cache/awmw/github-activity-widget/activity.json directory:

gears.timer {
    timeout   = 600,   -- calls every ten minutes
    call_now  = true,
    autostart = true,
    callback  = function()
        spawn.easy_async(string.format(UPDATE_EVENTS_CMD, username, CACHE_DIR), function(stdout, stderr)
            if stderr ~= '' then show_warning(stderr) return end
        end)
    end
}

There are several reasons to store output in a file and then use it as a source to build the widget, instead of calling it everytime the widget is opened:

• activity feed does not update that often
• events API doesn’t provide filtering of fields, so the output is quite large (300 events)
• it’s much faster to read file from filesystem

Next important part is rebuild_widget function, which is called when mouse button clicks on the widget on the wibar. It receives a json string which contains first n events from the cache file. Those events are processed by jq (get first n events, remove unused fields, slightly change the json structure to simplify serialization to lua table). And then it builds a widget, row by row in a loop. To display the text part of the row we already have all neccessary information in the json string which was converted to lua table. But to show an avatar we should download it first. This is done in the following snippet. First it creates a template and then checks if file already exists, and sets it in template, otherwise, downloads it asynchronously and only then sets in:

local avatar_img = wibox.widget {
    resize = true,
    forced_width = 40,
    forced_height = 40,
    widget = wibox.widget.imagebox
}

if gfs.file_readable(path_to_avatar) then
    avatar_img:set_image(path_to_avatar)
else
    -- download it first
    spawn.easy_async(string.format(
            DOWNLOAD_AVATAR_CMD,
            CACHE_DIR,
            event.actor.id,
            event.actor.avatar_url), 
            -- and then set
            function() avatar_img:set_image(path_to_avatar) end)
end

Jira widget

The widget shows the number of tickets assigned to the user and when clicked shows them in the list with some additional information. When item in the list is clicked - it opens the issue in browser.

How it works

Widget uses cURL to query Jira’s REST API. In order to be authenticated, widget uses a netrc feature of the cURL, which is basically to store basic auth credentials in a .netrc file in home folder.

If you are on Atlassian Cloud, then instead of providing a password in netrc file you can set an API token which is a safer option, as you can revoke/change the token at any time.

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Installation

Create a .netrc file in you home directory with following content:

machine turtlejira.com
login mikey@tmnt.com
password cowabunga

Then change file’s permissions to 600 (so only you can read/write it):

chmod 600 ~/.netrc

And test if it works by calling the API:

curl -s -n 'https://turtleninja.com/rest/api/2/search?jql=assignee=currentuser()+AND+resolution=Unresolved'

Clone/download repo and use widget in rc.lua:

local jira_widget = require("awesome-wm-widgets.jira-widget.jira")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
		...
		-- default
		jira_widget({host = 'http://jira.tmnt.com'}),
		...

Logout widget

Widget which allows to perform lock, reboot, log out, power off and sleep actions. It can be called either by a shortcut, or by clicking on a widget in wibar.

Installation

Clone this (if not cloned yet) and the awesome-buttons repos under ./.config/awesome/

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

Then

• to show by a shortcut - define a shortcut in globalkeys:

    local logout = require("awesome-wm-widgets.experiments.logout-widget.logout")
    ...
    globalkeys = gears.table.join(
    ...
        awful.key({ modkey }, "l", function() logout.launch() end, {description = "Show logout screen", group = "custom"}),
  

• to show by clicking on a widget in wibar - add widget to the wibar:

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

Customisation

Some color themes for inspiration:

logout.launch{
    bg_color = "#261447", accent_color = "#ff4365", text_color = '#f706cf', -- outrun
    -- bg_color = "#0b0c10", accent_color = "#1f2833", text_color = '#66fce1', -- dark
    -- bg_color = "#3B4252", accent_color = "#88C0D0", text_color = '#D8DEE9', -- nord
    phrases = {"exit(0)", "Don't forget to be awesome.", "Yippee ki yay!"},
}

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

Installation

To use this widget clone repo under ~/.config/awesome/ and then add it in rc.lua:

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

Net Speed Widget

The widget and readme is in progress

Pomodoro Widget

:construction: This widget is under construction :construction_worker:

Installation

This widget is based on @jsspencer’ pomo - a simple pomodoro timer. So first install/clone it anywhere you like, then either

• in widget’s code provide path to the pomo.sh, or
• add pomo.sh to the PATH, or
• make a soft link in /usr/local/bin/ to it:

   sudo ln -sf /opt/pomodoro/pomo.sh /usr/local/bin/pomo
  

Note that by default widget’s code expects third way and calls script by pomo.

Ram widget

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

Installation

Please refer to the installation section of the repo.

Spotify widget

This widget displays currently playing song on Spotify for Linux client:

Some features:

• status icon which shows if music is currently playing
• artist and name of the current song
• dim widget if spotify is paused
• trim long artist/song names
• tooltip with more info about the song

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.

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Example:

spotify_widget({
    font = 'Ubuntu Mono 9',
    play_icon = '/usr/share/icons/Papirus-Light/24x24/categories/spotify.svg',
    pause_icon = '/usr/share/icons/Papirus-Dark/24x24/panel/spotify-indicator.svg',
    dim_when_paused = true,
    dim_opacity = 0.5,
    max_length = -1,
    show_tooltip = false
})

Gives following widget

Playing:

Paused:

Installation

First you need to have spotify CLI installed, it uses dbus to communicate with spotify-client:

git clone https://gist.github.com/fa6258f3ff7b17747ee3.git
cd ./fa6258f3ff7b17747ee3 
chmod +x sp
sudo cp ./sp /usr/local/bin/

Then clone repo under ~/.config/awesome/ and add widget in rc.lua:

local spotify_widget = require("awesome-wm-widgets.spotify-widget.spotify")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
		...
        -- default        
        spotify_widget(),
        -- customized
        spotify_widget({
           font = 'Ubuntu Mono 9',
           play_icon = '/usr/share/icons/Papirus-Light/24x24/categories/spotify.svg',
           pause_icon = '/usr/share/icons/Papirus-Dark/24x24/panel/spotify-indicator.svg'
        }),
		...      

Stackoverflow widget

When clicked, widget shows latest questions from stackoverflow.com with a given tag(s).

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Installation

1. Clone this repo (if not cloned yet) under ~/.config/awesome/:

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

2. Require widget at the top of the rc.lua:

    local stackoverflow_widget = require("awesome-wm-widgets.stackoverflow-widget.stackoverflow")
   

3. Add widget to the tasklist:

    s.mytasklist, -- Middle widget
        { -- Right widgets
            layout = wibox.layout.fixed.horizontal,
            ...
            --default
            stackoverflow_widget(),
            --customized
            stackoverflow_widget({
                limit = 10
            })
            ...
   

Storage Widget

This widget shows disk usage. When clicked another widget appears with more detailed information. By default it monitors the “/” mount. It can be configured with a list of mounts to monitor though only the first will show in the wibar. To have multiple mounts displayed on the wibar simply define multiple storage_widgets with different mounts as arguments.

  local storage_widget = require("awesome-wm-widgets.storage-widget.storage-widget")
  ...
  s.mywibox:setup {
      s.mytasklist, -- Middle widget
      { -- Right widgets
      storage_widget(), --default
      wibox.widget.textbox(':'),
      storage_widget({ mounts = { '/', '/mnt/musicj' } }), -- multiple mounts
  ...

Installation

Please refer to the installation section of the repo.

ToDo Widget

This widget displays a list of to do items and allows to mark item as done/undone, delete an item and create new ones:

Installation

Widget persists todo items as a JSON, so in order to simplify JSON serialisation/deserialisation download a json.lua from this repository: https://github.com/rxi/json.lua under ~/.config/awesone folder. And don’t forget to star a repo :)

Then clone this repository under ~/.config/awesome/ and add the widget in rc.lua:

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

Also note that widget uses Arc Icons and expects them to be installed under /usr/share/icons/Arc/.

Theming

Widget uses your theme’s colors. In case you want to have different colors, without changing your theme, please create an issue for it. I’ll extract them as a widget parameters.

Volume widget

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

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

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Installation

• clone/copy volume.lua file;

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

local volume_widget = require("awesome-wm-widgets.volume-widget.volume")
...
        s.mytasklist, -- Middle widget
        { -- Right widgets
           ...
            volume_widget({display_notification = true}),
           ...

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: IF you have notification activated, a notification will pop-up on key press

--  Key bindings
globalkeys = gears.table.join(
  awful.key(
    {},
    'XF86AudioRaiseVolume',
    volume_widget.raise,
    {description = 'volume up', group = 'hotkeys'}
  ),
  awful.key(
    {},
    'XF86AudioLowerVolume',
    volume_widget.lower,
    {description = 'volume down', group = 'hotkeys'}
  ),
  awful.key(
    {},
    'XF86AudioMute',
    volume_widget.toggle,
    {description = 'toggle mute', group = 'hotkeys'}
  ),

Icons

• Optional step. In Arc icon theme the muted audio level icon () 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 ():

 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

Pulse or ALSA only

Try running this command:

amixer -D pulse sget Master

If that prints something like this, then the default setting of ‘pulse’ is probably fine:

Simple mixer control 'Master',0
  Capabilities: pvolume pvolume-joined pswitch pswitch-joined
  Playback channels: Mono
  Limits: Playback 0 - 64
  Mono: Playback 64 [100%] [0.00dB] [on]

If it prints something like this:

$ amixer -D pulse sget Master
ALSA lib pulse.c:243:(pulse_connect) PulseAudio: Unable to connect: Connection refused

amixer: Mixer attach pulse error: Connection refused

then set volume_audio_controller to alsa_only in widget constructor:

volume_widget({
    volume_audio_controller = 'alsa_only'
})

Volumearc widget

Almost the same as volumebar widget, but using arcchart:

Supports

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

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Example:

volumearc_widget({
    main_color = '#af13f7',
    mute_color = '#ff0000',
    thickness = 5,
    height = 25,
    button_press = function(_, _, _, button)   -- Overwrites the button press behaviour to open pavucontrol when clicked
        if (button == 1) then awful.spawn('pavucontrol --tab=3', false)
        end
    end
})

The config above results in the following widget:

Installation

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

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

2. Require volumearc widget at the beginning of rc.lua:

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

Volumebar widget

Almost the same as volume widget, but more minimalistic:

Supports

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

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Example:

 volumebar_widget({
    main_color = '#af13f7',
    mute_color = '#ff0000',
    width = 80,
    shape = 'rounded_bar',
    margins = 8
})

Above config results in following widget:

Installation

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

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

2. Require volumebar 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,
            ...
            --[[default]]
            volumebar_widget(),
            --[[or customized]]
            volumebar_widget({
                main_color = '#af13f7',
                mute_color = '#ff0000',
                width = 80,
                shape = 'rounded_bar', -- octogon, hexagon, powerline, etc
                -- bar's height = wibar's height minus 2x margins
                margins = 8
            }),
   
            ...
   

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

Widget showing current, hourly and daily weather forecast.

Widget consists of three sections:

• current weather, including humidity, wind speed, UV index
• hourly forecast for the next 24 hours
• daily forecast for the next five days

Customization

It is possible to customize widget by providing a table with all or some of the following config parameters:

Icons:

Widget comes with two predefined icon packs:

• weather-underground-icons taken from here
• VitalyGorbachev taken from here

To add your custom icons, create a folder with the pack name under /icons and use the folder name in widget’s config. There should be 18 icons, preferably 128x128 minimum. Icons should also respect the naming convention, please check widget’s source.

Examples:

Custom font, icons

weather_curl_widget({
    api_key='<your-key>',
    coordinates = {45.5017, -73.5673},
    time_format_12h = true,
    units = 'imperial',
    both_units_widget = true,
    font_name = 'Carter One',
    icons = 'VitalyGorbachev',
    show_hourly_forecast = true,
    show_daily_forecast = true,
}),

Only current weather

weather_curl_widget({
    api_key='<your-key>',
    coordinates = {45.5017, -73.5673},
}),

Installation

1. 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
   

2. Clone this repo under ~/.config/awesome/:

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

3. Get Open Weather Map app id here: openweathermap.org/appid.

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

    local weather_widget = require("awesome-wm-widgets.weather-widget.weather")
   

5. Add widget to the tasklist:

    s.mytasklist, -- Middle widget
        { -- Right widgets
            layout = wibox.layout.fixed.horizontal,
            ...
            --default
            weather_widget({
                api_key='<your-key>',
                coordinates = {45.5017, -73.5673},
            }),
            ,
            --customized
            weather_curl_widget({
                api_key='<your-key>',
                coordinates = {45.5017, -73.5673},
                time_format_12h = true,
                units = 'imperial',
                both_units_widget = true,
                font_name = 'Carter One',
                icons = 'VitalyGorbachev',
                show_hourly_forecast = true,
                show_daily_forecast = true,
            }),
            ...
   

How it works

TBW

Awesome Buttons

Here I want to share a way of creating fancy looking interactive buttons:

Prerequisite

Add the section below to your rc.lua, which will be used as a canvas:

local buttons_example = wibox {
    visible = true,
    bg = '#2E3440',
    ontop = true,
    height = 1E00,
    width = 200,
    shape = function(cr, width, height)
        gears.shape.rounded_rect(cr, width, height, 3)
    end
}

local button = {} -- <- code examples go here

buttons_example:setup {
    button,
    valigh = 'center',
    layout = wibox.container.place
}

awful.placement.top(buttons_example, { margins = {top = 40}, parent = awful.screen.focused()})

Button

Buttons usually consist of text, icon or both. Let’s start with a simple text button:

local button = wibox.widget{
    text = "I'm a button!",
    widget = wibox.widget.textbox
}

For the image button replace the textbox by the imagebox. For the icon and text button, combine both of them in the fixed horizontal layout:

{
    {
        {
            image = icon,
            resize = true,
            forced_height = 20,
            widget = wibox.widget.imagebox
        },
        margins = 4,
        widget = wibox.container.margin
    },
    {
        {
            text = 'Click me!',
            widget = wibox.widget.textbox
        },
        top = 4, bottom = 4, right = 8,
        widget = wibox.container.margin
    },
    layout = wibox.layout.align.horizontal
}

Next step is to add some margins and a background. For background we’ll use wibox.container.background, it allows to set the background itself (bg = '#4C566A'). By using alpha channel it’s possible to make a transparent background (bg = '#00000000') which will be useful in the next step when adding hover effect. Apart from a background, it also sets shape and borders, which allows to create ‘outline’ buttons (shape_border_width = 1, shape_border_color = '#4C566A'). These three types are shown in the example below:

local button = wibox.widget{
    {
        {
            text = "I'm a button!",
            widget = wibox.widget.textbox
        },
        top = 4, bottom = 4, left = 8, right = 8,
        widget = wibox.container.margin
    },
    bg = '#4C566A', -- basic
    bg = '#00000000', --tranparent
    shape_border_width = 1, shape_border_color = '#4C566A', -- outline
    shape = function(cr, width, height) 
        gears.shape.rounded_rect(cr, width, height, 4) 
    end,
    widget = wibox.container.background
}

Hover effects

Now the button looks like a button, but doesn’t behave like one. First thing is to change colors when mouse cursor hovers over the button. To do it we can leverage the signals: mouse::enter and mouse::leave. When using signals, we have access the to widget, so it’s pretty simple to change the color. Below I use alpha channel to darken the color of the button a bit, for all three types of button discussed above it works well:

button_basic:connect_signal("mouse::enter", function(c) c:set_bg("#00000066") end)
button_basic:connect_signal("mouse::leave", function(c) c:set_bg('#4C566A') end)
button_tranparent:connect_signal("mouse::enter", function(c) c:set_bg("#00000066") end)
button_tranparent:connect_signal("mouse::leave", function(c) c:set_bg('#00000000') end)
button_outline:connect_signal("mouse::enter", function(c) c:set_bg("#00000066") end)
button_outline:connect_signal("mouse::leave", function(c) c:set_bg('#00000000') end)

Note that you need to set the initial color of the button for the mouse::leave signal.

Second thing is to change the cursor:

local old_cursor, old_wibox
button_basic:connect_signal("mouse::enter", function(c)
    c:set_bg("#00000066")
    local wb = mouse.current_wibox
    old_cursor, old_wibox = wb.cursor, wb
    wb.cursor = "hand1" 
end)
button_basic:connect_signal("mouse::leave", function(c)
    c:set_bg('#4C566A')
    if old_wibox then
        old_wibox.cursor = old_cursor
        old_wibox = nil
    end
end)

Button click effects

Another effect is changing the color of the button when the button is pressed/released:

button_basic:connect_signal("button::press", function(c) c:set_bg("#000000") end)
button_basic:connect_signal("button::release", function(c) c:set_bg('#00000066') end)

Onclick action

To perform some action when the button is clicked you need to handle press/release signal. The important part here is to properly handle the button which was used, otherwise any click will trigger the function execution:

button_basic:connect_signal("button::press", function(c, _, _, button) 
    if button == 1 then  naughty.notify{text = 'Left click'} 
    elseif button == 2 then naughty.notify{text = 'Wheel click'} 
    elseif button == 3 then naughty.notify{text = 'Right click'} 
    end
end)

Summary

As you can see it is pretty easy to create interactive nice-looking buttons. But if you use multiple buttons in your widget, you may have quite a lot of boilerplate code. To solve this issue I created an awesome-buttons library, which simplifies this process:

awesomebuttons.with_text{ type = 'flat', text = 'Ola', color = '#f8f', text_size = 12 },
awesomebuttons.with_icon{ type = 'outline', icon = 'zoom-in', color = '#f8f', shape = 'rounded_rect' },
awesomebuttons.with_icon_and_text{ icon = 'check-circle', text = 'With Icon!', color = '#f48' },

Please refer to the repo’s README for more details. It is still in progress.

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

and lowercase for the outline characters:

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

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:

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