Delightful widgets for Awesome

This is Delightful, a set of widgets for Awesome window manager.

Delightful home page is at http://solitudo.net/software/awesome/delightful/. Also Delightful page at Awesome wiki is available at https://awesome.naquadah.org/wiki/Delightful. Screenshots showing Delightful in action are available at https://awesome.naquadah.org/wiki/Glossy_theme and https://awesome.naquadah.org/wiki/Darklooks_theme.

Why?

Why another widget system for Awesome, you ask? We already have Vicious, Wicked, Obvious, and many others.

Justifications

That is a valid question, let me try elaborating why Delightful was created.

Shiny colors

Your average Awesome widget is quite dull. Some might consider that a feature. In this case, Delightful is probably not for you. Delightful try to add some "bling" to the widgets. Not un-needed "bling" but something useful. Many Delightful widgets provide a dynamically updated icon along with the widget text. The icon might indicate the sound volume or battery level. Some of the widgets use Naughty based pop-ups and notifications to provide useful, additional information that doesn't fit the Awesome wibox. Tooltips are used always when it makes sense.

You might find Delightful widgets to have resemblance to some of the popular GNOME applets. This is not coincidental. Whether you find it a good or bad thing is up to you.

Configurable

Delightful widgets are also very configurable outside of the widget code. Besides usual configurable attributes, such as location where to display weather information or which network devices to exclude from monitoring, you also can tinker about every widget parameter, such as the widget update interval, from your Awesome rc.lua without having to edit the widget code. See the configuration section below for more information about configuring Delightful widgets and the themeing section about changing widget's appearance.

Important note! In order to maintain speedy startup, you have to alter the theme you're using when using Delightful widgets with icons. See the themeing section below for more info.

Leveraging existing functionality

Delightful doesn't try to re-invent the wheel. Widgets depend heavily on Vicious widget library. A few of the widgets just extend an existing Vicious widget by providing an icon and widget data display configuration for the Vicious widget used under the hoods. Some of the widgets provide features not available in existing Vicious widgets by implementing the Vicious widget interface and then add "the bling" on top of that.

Included widgets

Delightful features the following widgets.

Battery widget

delightful.widget.battery shows a battery indicator as an icon and a progress bar. Extends vicious.widgets.bat Vicious widget.

CPU widget

delightful.widget.cpu displays horizontal usage trend graph of all the CPUs combined. Extends vicious.widgets.cpu Vicious widget.

Date and time widget

Shows current date and time. When mouse cursor hovers over the widget, calendar is displayed as a popup. You can navigate between months by using mouse scroll wheel.

IMAP widget

delightful.widget.imap monitors one or more IMAP accounts for incoming messages. Multiple mailboxes can be monitored on each account. Number of unread messages in each monitored mailbox is displayed in the widget. When new mail arrives in one of the monitored mailboxes, some details about the message is shown in a popup. When mouse cursor hovers over the widget, details about each mailbox is shown in a popup. Widget icon indicates the status whether there are some unread mail in the monitored mailboxes. The IMAP widget implements the Vicious widget interface.

Memory widget

delightful.widget.memory displays a progress bar indicating current memory and swap usage. Extends vicious.widgets.mem Vicious widget.

Network widget

delightful.widget.network displays download and upload speeds of selected network devices of the system. An icon indicates the type of the device (wired, wireless or dialup). Extends vicious.widgets.net Vicious widget.

PulseAudio widget

delightful.widget.pulseaudio shows a PulseAudio mixer indicator as an icon and a progress bar. Mouse clicks and scroll wheel actions can used to perform various mixer-related functions such as muting the device and turn volume up and down. PulseAudio widget implements the Vicious widget interface.

Weather widget

delightful.widget.weather monitors weather status of given locations. Widget displays current temperature and an icon indicating the current weather condition. Icon is updated dynamically according to the weather and time changes. If the weather is clear, the icon indicates whether it's day or night in the monitored location. When mouse cursor hovers over the widget, details about the weather is shown in a popup. Weather widget implements the Vicious widget interface.

Dependencies

All widgets except the Date and time widget require Vicious. A tested and found-to-be-working version of Vicious is provided in under the submodules/vicious directory of the Delightful Git tree. See the downloading and install sections below for more information about the bundled Vicious. Using your existing Vicious installation or manually cloning the latest Vicious sources from the Git tree will most likely work, too.

All widgets except the Date and time widget require awesome-freedesktop for icon support. A tested and found-to-be-working version of awesome-freedesktop is provided in under the submodules/awesome-freedesktop directory of the Delightful Git tree. See the downloading and install sections below for more information about the bundled awesome-freedesktop. Using your existing awesome-freedesktop installation or manually cloning the latest awesome-freedesktop sources from the Git tree will most likely work, too.

All widgets except the Date and time widget can use icons. Using of icons is not required, but highly recommended. See the section about themeing for more info. On Debian/Ubuntu systems you can install the package gnome-icon-theme in order to get the common icons installed and additionally the package sensors-applet if you're planning to use the CPU or Memory widgets and the package libgweather-common if you're planning to use the Weather widget.

IMAP widget requires imap.lua. A tested and found-to-be-working version of imap.lua is provided in under the submodules/imap directory of the Delightful Git tree. See the downloading and install sections below for more information about the bundled imap.lua. imap.lua requires LuaSocket and LuaSec. On Debian/Ubuntu systems you can install the packages liblua5.1-socket2 and liblua5.1-sec1 in order to get LuaSocket and LuaSec installed.

Weather widget requires Lua weather library and Lua METAR parser. A tested and found-to-be-working versions of these modules are provided under the submodules/weatherlib and submodules/metar directories of the Delightful Git tree. See the downloading and install sections below for more information about these modules. The METAR parser requires LuaSocket. On Debian/Ubuntu systems you can install the package liblua5.1-socket2 in order to get LuaSocket installed.

Weather widget can also use GWeather XML location datafile to configure weather report locations using city names instead of weather station code. See the configuring section below for more information. If using this feature, also LuaExpat needs to be installed. On Debian/Ubuntu systems you can install the packages libgweather-common and liblua5.1-expat0 in order to get GWeather XML location datafile and LuaExpat installed. Using GWeather support is highly recommended.

Calendar widget requires calendar2.lua. The module is included in this distribution. See the install section below for more information.

Downloading

Delightful can be downloaded by cloning the public Git repository at git://scm.solitudo.net/delightful.git. Gitweb interface is available at http://scm.solitudo.net/gitweb/public/delightful.git.

Installation

Clone the Delightful Git tree
- $ git clone git://scm.solitudo.net/delightful.git
Download the submodules, i.e. bundled dependencies
- $ git submodule init
- $ git submodule update
Copy Delightful under your Awesome configuration directory
- $ cp -a delightful/delightful ~/.config/awesome
If you don't have an existing Vicious installation in your Awesome setup, copy Vicious under your Awesome configuration directory
- $ cp -a delightful/submodules/vicious ~/.config/awesome
If you don't have an existing awesome-freedesktop installation in your Awesome setup, copy awesome-freedesktop under your Awesome configuration directory
- $ cp -a delightful/submodules/awesome-freedesktop/freedesktop ~/.config/awesome
If you're planning to use the IMAP widget, copy the imap.lua module in your Awesome configuration directory
- $ cp delightful/submodules/imap/lua/imap.lua/imap.lua ~/.config/awesome
If you're planning to use the Weather widget, copy the Lua weather library and Lua METAR parser in your Awesome configuration directory
- $ cp delightful/submodules/weatherlib/src/weatherlib.lua ~/.config/awesome
- $ cp delightful/submodules/metar/src/metar.lua ~/.config/awesome
If you're planning to use the Date and time widget, copy the calendar module in your Awesome configuration directory
- $ cp delightful/calendar2.lua ~/.config/awesome
If running Debian/Ubuntu system, install the dependency for common icons
- $ apt-get install gnome-icon-theme
If running Debian/Ubuntu system, and planning to use the CPU or Memory widgets, install the dependency for icons
- $ apt-get install sensors-applet
If running Debian/Ubuntu system, and planning to use the IMAP widget, install the dependency packages
- $ apt-get install liblua5.1-socket2 liblua5.1-sec1
If running Debian/Ubuntu system, and planning to use the Weather widget, install the dependency packages
- $ apt-get install libgweather-common liblua5.1-socket2

Configuration

This section documents the commonly used configuration options for each widget. For full list of available configuration options for each widget, see the comments at top of the each widget's source file under the directory delightful/widgets.

Configuration options are defined as Lua tables with keys being the configuration option name listed below and value being the configuration value. See the section about using in Awesome for info on how to actually pass the configuration to the widgets.

Battery widget

battery
- Battery name under the directory /sys/class/power_supply/. Defaults to BAT1. You probably don't have to change this.

CPU widget

Default configuration should work for most people.

Date and time widget

No configuration options available at all.

IMAP widget

You can configure multiple IMAP accounts to be monitored for messages. Each account can monitor multiple mailboxes. Each account needs to be given as a Lua table entry. For each account entry the most interesting configuration options are the following.

user
- User name of the IMAP account, mandatory
password
- Password of the IMAP account, mandatory
host
- Host name or IP address of the IMAP server, mandatory
port
- Port of the IMAP server. 143 by default if SSL disabled, 993 if SSL enabled
ssl
- true or false to enable or disable SSL for the IMAP connection. Note that only IMAPS is supported, not IMAP with STARTTLS. No SSL support by default.
mailboxes
- A table defining which mailboxes to monitor. Defaults to INBOX so not needed to be defined is you only want to monitor the inbox.

Memory widget

Default configuration should work for most people.

Network widget

Default configuration should work for most people. But if the widget displays status for unwanted network devices, the following configuration option is handy.

excluded_devices
- A table of Lua patterns that match network devices that are not to be monitored. For instance, if you don't want to see the idle interface eth1, you could use the pattern ^eth1$.

PulseAudio widget

Default configuration should work for most people. But if the widget displays volume mixer for unwanted audio devices, the following configuration option is handy.

sink_nums
- A table of integers that reprsents the PulseAudio sink numbers to be used. To find out the sink number(s) you want to use, run command pacmd list-sinks and examine the output. Each line with the content * index: <number> shows a possible sink number that you can use in the sink_nums configuration option.

Weather widget

It is assumed that GWeather XML location datafile is available. See the source file delightful/widgets/weather.lua for more information about configuration if you're not going to be using GWeather XML location datafile support.

You can configure multiple locations for weather monitoring. Each location needs to be given as a Lua table entry. For each location entry the most interesting configuration options are the following.

city
- The city and optional country to monitor as listed in the GWeather XML location datafile. The format for full entry is <country name>, <city name>, for example United Kingdom, London. For London, UK, you have to use the full format since the GWeather XML location datafile contains many cities named London and the first matching city is used. If the city name is globally unique, it's safe to use the simple format <city name>. For example, to monitor the capital of Finland, you can just use Helsinki as there's no two cities named Helsinki in the world.

This is really all that is needed if you're happy to use European style units. If you want to display units commonly used in the US or elsewhere, you can additionally use the following configuration options.

temperature_unit
- The unit to use when displaying temperatures. Defaults to c for Celcius, other possible value is f for Fahrenheit.
wind_speed_unit
- The unit to use when displaying wind speed. Defaults to ms for meters per second, other possible values are kmh for kilometers per hour, mph for miles per hour and kn for knots.
pressure_unit
- The unit to use when displaying air pressure. Defaults to hpa for hectopascals, other possible values are atm for standard atmosphere and inhg for inches of Mercury.
visibility_unit
- The unit to use when visibility distance. Defaults to m for meters, other possible values are km kilometers, ft for feet, yd for yards and mi for miles.

Configuration options common to all widgets

Well, all but the Date and time widget.

update_interval
- How often the widget data is being updated. Default varies for each widget from CPU widget's one second to Weather widget's 20 minutes. Most likely the default is OK for each widget.
no_icon
- true or false to disable or enable showing of widget icons. Default is to show icons for all widgets.

Themeing

Delightful widgets can use various aspects of the current Beautiful theme, though Delightful widgets should work with any unmodified theme. However, when using unmodified themes, be aware of the default icon lookup related performance notes below.

See the themes at my Awesome themes page for examples of themes with full Delightful support.

Icons

All widgets except the Date and time widget use various icons. For full list of available themable icons for each widget, see the comments at top of the each widget's source file under the directory delightful/widgets.

If an icon is not explicitly defined in the theme, default icon file name is resolved using awesome-freedesktop routines. Typically this results in dozens if not hundreds of file accesses per icon when trying to locate the icon file. If using many widgets and especially if using the Weather widget, which uses exactly one hundred icons, the automatic lookup of icons can take tens of seconds even on a fast machine. This causes Awesome to stall for the whole time icons are being looked up. So in order to get normal speedy startup, it's essential that icon names are explicitly defined in the theme being used! See the themes mentioned above for examples how to "delightfulify" your themes.

While icons are highly recommended, they are not mandatory. You can disable showing of icons by two means. Either for each widget, set the no_icon configuration option explained above to true or just don't install the packages providing the default icons that are tried to lookup. The no_icon way is recommended since this way you don't get the performance penalty with the default icon lookup explained above.

Text color

Battery, CPU, Memory, and PulseAudio widgets can use the following colors defined in the theme to color bars, graphs, and text.

bg_widget
- Widget background and border color, fallback to color bg_normal if bg_widget not defined
fg_widget
- Widget foreground color, fallback to color fg_normal if fg_widget not defined
fg_center_widget
- Middle part of the widget gradient color, fallback to color fg_widget and fg_normal if fg_center_widget not defined
fg_end_widget
- End part of the widget gradient color, fallback to color fg_widget and fg_normal if fg_end_widget not defined

Font

IMAP and Weather widgets use the following font.

delightful_monospace_font
- Font used when rendering text to popups. The setting should refer to a monospaced font. Fallback to monospace if delightful_monospace_font not defined.

Using in Awesome

This section shows what you need to add to your Awesome configuration in order to get Delightful widgets added to your Awesome desktop. In this sample, default configuration for Awesome 3.4.3 as shipped in Ubuntu 10.04 lucid is used. I'm sure you can apply this to newer default configurations or integrate as part of your non-default configuration. Of course put something meaningful in the IMAP widget configuration, remove unwanted widgets and so on.

In rc.lua, just before the layouts configuration add the following section

-- Delightful widgets
require('delightful.widgets.battery')
require('delightful.widgets.cpu')
require('delightful.widgets.datetime')
require('delightful.widgets.imap')
require('delightful.widgets.memory')
require('delightful.widgets.network')
require('delightful.widgets.pulseaudio')
require('delightful.widgets.weather')

-- Which widgets to install?
-- This is the order the widgets appear in the wibox.
install_delightful = {
    delightful.widgets.network,
    delightful.widgets.cpu,
    delightful.widgets.memory,
    delightful.widgets.weather,
    delightful.widgets.imap,
    delightful.widgets.battery,
    delightful.widgets.pulseaudio,
    delightful.widgets.datetime
}

-- Widget configuration
delightful_config = {
    [delightful.widgets.cpu] = {
        command = 'gnome-system-monitor',
    },
    [delightful.widgets.imap] = {
        {
            user      = 'myuser',
            password  = 'mypassword',
            host      = 'mail.example.com',
            ssl       = true,
            mailboxes = { 'INBOX', 'awesome' },
            command   = 'evolution -c mail',
        },
    },
    [delightful.widgets.memory] = {
        command = 'gnome-system-monitor',
    },
    [delightful.widgets.weather] = {
        {
            city = 'Helsinki',
            command = 'gnome-www-browser http://ilmatieteenlaitos.fi/saa/Helsinki',
        },
    },
    [delightful.widgets.pulseaudio] = {
        mixer_command = 'gnome-volume-control',
    },
}

-- Prepare the container that is used when constructing the wibox
local delightful_container = { widgets = {}, icons = {} }
if install_delightful then
    for _, widget in pairs(awful.util.table.reverse(install_delightful)) do
        local config = delightful_config and delightful_config[widget]
        local widgets, icons = widget:load(config)
        if widgets then
            if not icons then
                icons = {}
            end
            table.insert(delightful_container.widgets, awful.util.table.reverse(widgets))
            table.insert(delightful_container.icons,   awful.util.table.reverse(icons))
        end
    end
end

Then at the end of wibox creation, delete the lines

-- Add widgets to the wibox - order matters
mywibox[s].widgets = {
    {
        mylauncher,
        mytaglist[s],
        mypromptbox[s],
        layout = awful.widget.layout.horizontal.leftright
    },
    mylayoutbox[s],
    mytextclock,
    s == 1 and mysystray or nil,
    mytasklist[s],
    layout = awful.widget.layout.horizontal.rightleft
}

and replace with

local widgets_front = {
    {
        mylauncher,
        mytaglist[s],
        mypromptbox[s],
        layout = awful.widget.layout.horizontal.leftright
    },
    mylayoutbox[s],
}
local widgets_middle = {}
for delightful_container_index, delightful_container_data in pairs(delightful_container.widgets) do
    for widget_index, widget_data in pairs(delightful_container_data) do
        table.insert(widgets_middle, widget_data)
        if delightful_container.icons[delightful_container_index] and delightful_container.icons[delightful_container_index][widget_index] then
            table.insert(widgets_middle, delightful_container.icons[delightful_container_index][widget_index])
        end
    end
end
local widgets_end = {
    s == 1 and mysystray or nil,
    mytasklist[s],
    layout = awful.widget.layout.horizontal.rightleft
}
mywibox[s].widgets = awful.util.table.join(widgets_front, widgets_middle, widgets_end)

and you should be done.

This sample Delightful setup is also available as a patch file awesome-3.4.3-delightful-sample-configuration.diff in the Delightful distribution. The patch is against the stock Awesome 3.4.3 rc.lua.

Contributing

If you would like to contribute patches or new widgets, you can contact the author. See contact information below.

PS. A Git tree to pull from would be a joy.

Copyright and licensing

Licensed under the terms of the GNU General Public License Version 2.0. License terms are included in the file COPYING.

calendar2.lua included in this distribution was created by Bernd Zeimetz bernd@bzed.de and modified by Marc Dequènes Duck@DuckCorp.org. calendar2.lua is released to public domain.

TheMarex/delightful

Delightful widgets for Awesome

Why?

Justifications

Shiny colors

Configurable

Leveraging existing functionality

Included widgets

Battery widget

CPU widget

Date and time widget

IMAP widget

Memory widget

Network widget

PulseAudio widget

Weather widget

Dependencies

Downloading

Installation

Configuration

Battery widget

CPU widget

Date and time widget

IMAP widget

Memory widget

Network widget

PulseAudio widget

Weather widget

Configuration options common to all widgets

Themeing

Icons

Text color

Font

Using in Awesome

Contributing

Copyright and licensing