Awesome WM Widgets

This is a project page of the github repo with set of widgets for Awesome Window Manager plus few articles on widget creation/customization.

Installation

Clone repository under ~/.config/awesome folder. Then follow a README file of the widget.

Support

If you find anything useful here, you can:

• star a repo - this really motivates me to work on this project
• or
• or even become a sponsor

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 allows storing 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:

Note:

• host most likely should start with api.
• to get your UUID you may call curl -s -n 'https://api.bitbucket.org/2.0/user'

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 = '{123e4567-e89b-12d3-a456-426614174000}',
            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
  naughty (default)	from local theme

• 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'
    radius = 8
})
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 

Filesystem Widget

This widget shows file system disk space usage which is based on the df output. 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 fs_widgets with different mounts as arguments.

Cusomizations

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

Installation

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

  local fs_widget = require("awesome-wm-widgets.fs-widget.fs-widget")
  ...
  s.mywibox:setup {
      s.mytasklist, -- Middle widget
      { -- Right widgets
      fs_widget(), --default
      fs_widget({ mounts = { '/', '/mnt/music' } }), -- multiple mounts
  ...

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

Github Contributions Widget

The widget is inspired by the https://github-contributions.now.sh/ and relies on it’s API.

It shows the contribution graph, similar to the one on the github profile page:

You might wonder what could be the reason to have your github’s contributions in front of you all day long? The more you contribute, the nicer widget looks! Check out Thomashighbaugh’s graph:

Customization

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

Note: widget height is 21px (7 rows of 3x3 cells). So it would look nice on the wibar of 22-24px height.

Themes

Following themes are available:

Theme name	Preview
standard
classic
teal
leftpad
dracula
pink

To add a new theme, simply add a new entry in themes table (themes.lua) with the colors of your theme.

Screenshots

1000 days, with border:

365 days, no border:

Installation

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

local github_contributions_widget = require("awesome-wm-widgets.github-contributions-widget.github-contributions-widget")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
		...
		-- default
        github_contributions_widget({username = '<your username>'}),
		...

Gitlab widget

The widget shows the number of merge requests assigned to the user and when clicked shows additional information, such as

• author’s name and avatar (opens user profile page when clicked);
• MR name (opens MR when clicked);
• source and target branches;
• when was created;
• number of comments;
• number of approvals.

Customization

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

Note:

• to get the access token, go to User Settings -> Access Tokens and generate a token with api scope

Installation

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

local gitlab_widget = require("awesome-wm-widgets.gitlab-widget.gitlab")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    	layout = wibox.layout.fixed.horizontal,
		...
		-- default
        gitlab_widget{
            host = 'https://gitlab.yourcompany.com',
            access_token = 'h2v531iYASDz6McxYk4A'
        },
		...

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 Menu Widget

This widget shows a menu with options to log out from the current session, lock, reboot, suspend and power off the computer, similar to logout-popup-widget:

Installation

Clone this repo (if not cloned yet) ./.config/awesome/

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

Then add the widget to the wibar:

local logout_menu_widget = require("awesome-wm-widgets.logout-menu-widget.logout-menu")

s.mytasklist, -- Middle widget
    { -- Right widgets
        layout = wibox.layout.fixed.horizontal,
        ...
        -- default
        logout_menu_widget(),
        -- custom
        logout_menu_widget{
            font = 'Play 14',
            onlock = function() awful.spawn.with_shell('i3lock-fancy') end
        }
        ...

Customization

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

Logout Popup 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.

When the widget is shown, following shortcuts can be used:

• Escape - hide widget
• s - shutdown
• r - reboot
• u - suspend
• k - lock
• l - log out

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_popup = require("awesome-wm-widgets.logout-popup-widget.logout-popup")
      
    s.mytasklist, -- Middle widget
            { -- Right widgets
                layout = wibox.layout.fixed.horizontal,
                ...
                logout_popup.widget{},
                ...
  

Customisation

Some color themes for inspiration:

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

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.

When the widget is shown, following shortcuts can be used:

• Escape - hide widget
• s - shutdown
• r - reboot
• u - suspend
• k - lock
• l - log out

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.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', icon_size = 40, icon_margin = 16, -- outrun
    -- bg_color = "#0b0c10", accent_color = "#1f2833", text_color = '#66fce1', -- dark
    -- bg_color = "#3B4252", accent_color = "#88C0D0", text_color = '#D8DEE9', -- nord
    -- bg_color = "#282a36", accent_color = "#ff79c6", phrases = {}, -- dracula, no phrase
    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,
		...

MPRIS Widget (In progress)

Music Player Info widget cy @mgabs

Prerequisite

Install playerctl (mpris implementation), should be available in repo, e.g for Ubuntu:

sudo apt-get install playerctl

Installation

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

local mpris_widget = require("awesome-wm-widgets.mpris-widget")
...
s.mytasklist, -- Middle widget
	{ -- Right widgets
    layout = wibox.layout.fixed.horizontal,
		...
    mpris_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
            })
            ...
   

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

The widget showing current, hourly and daily weather forecast.

The 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:

The 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,
            }),
            ...
   

More screenshots

Only negative temperature:

Both positive and negative tempertature:

How it works

TBW

word clock widget

Widget displaying current time using words:

Customization

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

Installation

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

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

Screenshots

 word_clock{
    font = 'Carter One 12',
    accent_color = '#ff79c6',
    main_color = '#8be9fd',
    is_human_readable = true,
}

word_clock{
    font = 'Carter One 12',
    is_human_readable = true,
}

word_clock{
    font = 'Carter One 12',
    is_human_readable = true,
    military_time = true
}

word_clock{
    font = 'Carter One 12',
    accent_color = '#f00',
    main_color = '#0f0',
}

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.

Awesome Taglist

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"

Fade effect on a widget

Here is a nice fade-out / fade-in effect which can be applied on text/image widgets (or any other widget which supports opacity). It can be used either on click or on hover actions:

Fade effect on a widget

local fade_widget = wibox.widget {
    {
        id = 'icon',
        image = '/usr/share/icons/Yaru/24x24/apps/org.gnome.PowerStats.png',
        widget = wibox.widget.imagebox
    },
    {
        id = 'text',
        text = 'Click to fade',
        widget = wibox.widget.textbox
    },
    spacing = 4,
    layout = wibox.layout.fixed.horizontal,
    toggle_fade = function(self, is_fade)
        self:get_children_by_id('icon')[1]:set_opacity(is_fade and 0.2 or 1)
        self:get_children_by_id('icon')[1]:emit_signal('widget::redraw_needed')
        self:get_children_by_id('text')[1]:set_opacity(is_fade and 0.2 or 1)
        self:get_children_by_id('text')[1]:emit_signal('widget::redraw_needed')
    end
}

-- on click
local faded = true
fade_widget:connect_signal('button::press', function(c)
    faded = not faded
    c:toggle_fade(not faded)
end)

-- on hover
fade_widget:toggle_fade(true)
fade_widget:connect_signal('mouse::enter', function(c) c:toggle_fade(false) end)
fade_widget:connect_signal('mouse::leave', function(c) c:toggle_fade(true) end)

How it works

Let’s start by creating a simple widget which has an icon and some text:

local fade_widget = wibox.widget {
    {
        image = '/usr/share/icons/Yaru/24x24/apps/org.gnome.PowerStats.png',
        widget = wibox.widget.imagebox
    },
    {
        text = 'Click to fade',
        widget = wibox.widget.textbox
    },
    spacing = 4,
    layout = wibox.layout.fixed.horizontal
}

Fade effect can be achieved by lowering the opacity of the widget. Luckily both textbox and imagebox have opacity property, which is set to 1 by default. The cleanest way to change widget’s property (or properties of nested widgets) is to add a function which will hide all the ugliness of accessing the nested widgets inside and expose a clean API outside:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
local fade_widget = wibox.widget {
    {
        id = 'icon',
        image = '/usr/share/icons/Yaru/24x24/apps/org.gnome.PowerStats.png',
        widget = wibox.widget.imagebox
    },
    {
        id = 'text',
        text = 'Click to fade',
        widget = wibox.widget.textbox
    },
    spacing = 4,
    layout = wibox.layout.fixed.horizontal,
    toggle_fade = function(self, is_fade)
        self:get_children_by_id('icon')[1]:set_opacity(is_fade and 0.2 or 1)
        self:get_children_by_id('icon')[1]:emit_signal('widget::redraw_needed')
        self:get_children_by_id('text')[1]:set_opacity(is_fade and 0.2 or 1)
        self:get_children_by_id('text')[1]:emit_signal('widget::redraw_needed')
    end
}

Few things to note here:

• Added widget identifiers (line 3, 8) so that we can access them later - line 15-18. We are using JavaScript-like syntax, described in section Accessing widgets of the documentation
• When changing text in textbox the widget is redrawn automatically (same for the image in imagebox), however when changing opacity the redraw is not triggered, this is why we call it explicitly - line 16, 18.

Now we can easily trigger the fade effect on the widget by calling a toggle_fade(true) method. The only thing left is to add a mouse handler:

• to toggle on mouse click

local faded = true
fade_widget:connect_signal('button::press', function(c)
    faded = not faded
    c:toggle_fade(not faded)
end)

• to toggle on hover:

fade_widget:toggle_fade(true)
fade_widget:connect_signal('mouse::enter', function(c)
    c:toggle_fade(false)
end)
fade_widget:connect_signal('mouse::leave', function(c)
    c:toggle_fade(true)
end)

Lists

This type of UI element is also called menu (for example in GTK). As an example let’s create a bookmarks widget - a widget will show a static list of sites. If item in the list is clicked - the site will be opened in the browser. You can find the created widget here

Prerequisite

Create a bookmark-widget.lua file under ~/.config/awesome/tutorials folder. Then include it in your rc.lua and add widget to the wibox:

local bookmark_widget = require("tutorials.bookmark-widget.bookmark-widget")
...
s.mytasklist, -- Middle widget
{ -- Right widgets
    ...
    bookmark_widget

To have a list popup, first we need to have an “anchor” widget, clicking on which should toggle the visibility of the list, so let’s create it, it will be an icon:

local awful = require("awful")
local wibox = require("wibox")
local gears = require("gears")
local beautiful = require("beautiful")

local HOME = os.getenv('HOME')
local ICON_DIR = HOME .. '/home-dev/awesome-wm-widget-tutorial/awesome-wm-widgets/bookmark-widget/icons/'

local bookmark_widget = wibox.widget {
    {
        image = ICON_DIR .. 'bookmark.svg',
        resize = true,
        widget = wibox.widget.imagebox,
    },
    margins = 4,
    widget = wibox.container.margin
}

-- code mentioned below goes here

return bookmark_widget

Now restart awesome and boom! - you have a widget:

Widget structure

We are going to use an awful.popup as it’s quite easy to show/hide it and also to place it on the screen. On the popup we’ll add text and image widgets, arranged in a vertical list using layout.fixed layout plus container.margin and container.background to make it look nice and to change the background color on mouse hover:

Let’s start

Each item in the list will have three components: an icon, a text and an url to open when the item is clicked. Let’s represent it in lua:

local menu_items = {
    { name = 'Reddit', icon_name = 'reddit.svg', url = 'https://www.reddit.com/' },
    { name = 'StackOverflow', icon_name = 'stackoverflow.svg', url = 'http://github.com/' },
    { name = 'GitHub', icon_name = 'github.svg', url = 'https://stackoverflow.com/' },
}

Then let’s define a popup and rows (which will hold the vertical layout), to which we will add items later on:

local popup = awful.popup {
    ontop = true,
    visible = false, -- should be hidden when created
    shape = function(cr, width, height)
        gears.shape.rounded_rect(cr, width, height, 4)
    end,
    border_width = 1,
    border_color = beautiful.bg_focus,
    maximum_width = 400,
    offset = { y = 5 },
    widget = {}
}
local rows = { layout = wibox.layout.fixed.vertical }

Now we’ll just traverse over the menu_items, create a row (let’s start with a simple textbox widget), add it to rows and then add rows to the popup:

for _, item in ipairs(menu_items) do

    local row = wibox.widget {
        text = item.name,
        widget = wibox.widget.textbox
    }
    table.insert(rows, row)
end
popup:setup(rows)

The last thing left is to toggle popup visibility on mouse click on the bookmark_widget:

bookmark_widget:buttons(
    awful.util.table.join(
        awful.button({}, 1, function()
            if popup.visible then
                popup.visible = not popup.visible
            else
                 popup:move_next_to(mouse.current_widget_geometry)
            end
    end))
)

Restart awesome and click on the widget:

Make it pretty

To add an icon let’s wrap textbox in a fixed.horizontal layout and add an imagebox with an icon in front of it. Note that it’s important to set the maximum height and width of the image, otherwise it will take up all available space:

local row = wibox.widget {
    {
        image = ICON_DIR .. item.icon_name,
        forced_width = 16,
        forced_height = 16,
        widget = wibox.widget.imagebox
    },
    {
        text = item.name,
        widget = wibox.widget.textbox
    },
    layout = wibox.layout.fixed.horizontal
}

Looks ok, but icon and text are too close to each other. One way to fix it is to use a spacing property of the fixed layout, which sets the distance between widgets:

local row = wibox.widget {
    {
        image = ICON_DIR .. item.icon_name,
        forced_width = 16,
        forced_height = 16,
        widget = wibox.widget.imagebox
    },
    {
        text = item.name,
        widget = wibox.widget.textbox
    },
    spacing = 12, -- <--
    layout = wibox.layout.fixed.horizontal
}

Now let’s add margins around each item:

local row = wibox.widget {
    {
        {
            image = ICON_DIR .. item.icon_name,
            forced_width = 16,
            forced_height = 16,
            widget = wibox.widget.imagebox
        },
        {
            text = item.name,
            widget = wibox.widget.textbox
        },
        spacing = 12,
        layout = wibox.layout.fixed.horizontal
    },
    margins = 8,
    widget = wibox.container.margin
}

One more step is to wrap margins in a background. Visually it won’t change anything (unless you want to change the default color, which is bg_normal from your theme), but it will be useful later, when we will add mouse hover effect to the menu item

local row = wibox.widget {
    {
        {
            {
                image = ICON_DIR .. item.icon_name,
                forced_width = 16,
                forced_height = 16,
                widget = wibox.widget.imagebox
            },
            {
                text = item.name,
                widget = wibox.widget.textbox
            },
            spacing = 12,
            layout = wibox.layout.fixed.horizontal
        },
        margins = 8,
        widget = wibox.container.margin
    },
    bg = beautiful.bg_normal,
    widget = wibox.container.background
}

Looks good now! Let’s add some interactivity, like changing background on mouse hover, note that c in the callback function’s parameter is a row, defined above, which is a background widget, so we can set the background color with set_bg method:

row:connect_signal("mouse::enter", function(c) 
    c:set_bg(beautiful.bg_focus) 
end)
row:connect_signal("mouse::leave", function(c) 
    c:set_bg(beautiful.bg_normal) 
end)

Let’s also change a cursor:

local old_cursor, old_wibox
row:connect_signal("mouse::enter", function()
    local wb = mouse.current_wibox
    old_cursor, old_wibox = wb.cursor, wb
    wb.cursor = "hand1"
end)
row:connect_signal("mouse::leave", function()
    if old_wibox then
        old_wibox.cursor = old_cursor
        old_wibox = nil
    end
end)

Make it work

The last bit is to open the link, when mouse is clicked. We’ll use the buttons method which accepts a table of buttons. First parameter is a table with modifiers (we use none), second is a button number (1 is a left mouse button), third parameter is a callback function which is called on press action. When mouse button is clicked we want to hide the popup and open the link in the default browser. xdg-open is used exactly for that:

row:buttons(
    awful.util.table.join(
        awful.button({}, 1, function()
            popup.visible = not popup.visible
            awful.spawn.with_shell('xdg-open ' .. item.url)
        end)
    )
)

Future improvements

The menu or list widget, created above, looks pretty standard, as it has icon and text. However, playing with different layouts you can add more items to it, for example you may follow material design guidance and create lists with many components, like three-lines lists with visuals and controls. As an example here is a list from gitlab widget:

And another one from github-activity-widget:

And one more from docker widget:

Widget described above can be found here

Toggable Systray

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

Ellipsize

Ellipsizes string to a given length

local function ellipsize(text, length)
    return (text:len() > length and length > 0)
        and text:sub(0, length - 3) .. '...'
        or text
end

To time ago

Converts seconds to “time ago” represenation, like ‘1 hour ago’

local function to_time_ago(seconds)
    local days = seconds / 86400
    if days > 1 then
        days = math.floor(days + 0.5)
        return days .. (days == 1 and ' day' or ' days') .. ' ago'
    end

    local hours = (seconds % 86400) / 3600
    if hours > 1 then
        hours = math.floor(hours + 0.5)
        return hours .. (hours == 1 and ' hour' or ' hours') .. ' ago'
    end

    local minutes = ((seconds % 86400) % 3600) / 60
    if minutes > 1 then
        minutes = math.floor(minutes + 0.5)
        return minutes .. (minutes == 1 and ' minute' or ' minutes') .. ' ago'
    end
end