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 another widget system for Awesome, you ask? We already have Vicious, Wicked, Obvious, and many others.
That is a valid question, let me try elaborating why Delightful was created.
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.
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.
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.
Delightful features the following widgets.
delightful.widget.battery
shows a battery indicator as an icon and a progress
bar. Extends vicious.widgets.bat
Vicious widget.
delightful.widget.cpu
displays horizontal usage trend graph of all the CPUs
combined. Extends vicious.widgets.cpu
Vicious 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.
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.
delightful.widget.memory
displays a progress bar indicating current memory
and swap usage. Extends vicious.widgets.mem
Vicious 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.
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.
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.
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.
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.
- 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
- $
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
- Battery name under the directory
/sys/class/power_supply/
. Defaults toBAT1
. You probably don't have to change this.
- Battery name under the directory
Default configuration should work for most people.
No configuration options available at all.
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
orfalse
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.
- A table defining which mailboxes to monitor. Defaults to
Default configuration should work for most people.
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$
.
- 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
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 thesink_nums
configuration option.
- 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
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 exampleUnited Kingdom, London
. For London, UK, you have to use the full format since the GWeather XML location datafile contains many cities namedLondon
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 useHelsinki
as there's no two cities namedHelsinki
in the world.
- The city and optional country to monitor as listed in the GWeather XML location datafile. The format for full entry is
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 isf
for Fahrenheit.
- The unit to use when displaying temperatures. Defaults to
wind_speed_unit
- The unit to use when displaying wind speed. Defaults to
ms
for meters per second, other possible values arekmh
for kilometers per hour,mph
for miles per hour andkn
for knots.
- The unit to use when displaying wind speed. Defaults to
pressure_unit
- The unit to use when displaying air pressure. Defaults to
hpa
for hectopascals, other possible values areatm
for standard atmosphere andinhg
for inches of Mercury.
- The unit to use when displaying air pressure. Defaults to
visibility_unit
- The unit to use when visibility distance. Defaults to
m
for meters, other possible values arekm
kilometers,ft
for feet,yd
for yards andmi
for miles.
- The unit to use when visibility distance. Defaults to
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
orfalse
to disable or enable showing of widget icons. Default is to show icons for all widgets.
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.
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.
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
ifbg_widget
not defined
- Widget background and border color, fallback to color
fg_widget
- Widget foreground color, fallback to color
fg_normal
iffg_widget
not defined
- Widget foreground color, fallback to color
fg_center_widget
- Middle part of the widget gradient color, fallback to color
fg_widget
andfg_normal
iffg_center_widget
not defined
- Middle part of the widget gradient color, fallback to color
fg_end_widget
- End part of the widget gradient color, fallback to color
fg_widget
andfg_normal
iffg_end_widget
not defined
- End part of the widget gradient color, fallback to color
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
ifdelightful_monospace_font
not defined.
- Font used when rendering text to popups. The setting should refer to a monospaced font. Fallback to
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
.
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: © 2011 Tuomas Jormola tj@solitudo.net http://solitudo.net
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.