vicious
=======
vicious is a modular widget library for "awesome" window manager,
derived from the "Wicked" widget library. It has some of the old
Wicked widget types, a few of them rewritten, and a good number of new
widgets.
Usage
-----
To use vicious, copy it to the ~/.config/awesome directory, edit
init.lua and comment out all the widgets you don't need, from the
"Configure widgets" list. Then add:
require("vicious")
...to the top of your rc.lua.
Once you create a widget (as a: textbox, graph or a progressbar) call
vicious.register() to register it with vicious:
vicious.register(widget, type, format, interval, warg)
widget - widget created with widget() or awful.widget (in case of a
graph or a progressbar)
type - one of the available widget types (a list is below)
format - a string argument or a function
+ string
- $1, $2, $3... will be replaced by their respective value
returned from the widget type
- some widget types return tables with custom keys, in that
case use: ${key}
+ function
- function(widget, args) can be used to manipulate data
returned by the widget type, more below
interval - number of seconds between updates of the widget
warg - some widgets require an argument to be passed, i.e. the
battery ID
Other Functions
---------------
Unregister
vicious.unregister(widget, keep)
keep - if true the widget will be suspended, waiting to be activated
Suspend - suspend all widgets, used when running on battery power
vicious.suspend()
- if you want it to happen automatically, see the example script for
the laptop-mode-tools start-stop programs module:
http://sysphere.org/~anrxc/local/sources/lmt-vicious.sh
Activate - restart all suspended, or unregistered but kept, widgets
vicious.activate(widget)
widget - if provided, only that widget will be activated
Regregister
vicious.regregister(reg)
- vicious.register() and vicious.unregister() both return a reg object, this
contains information about the widget and the updates that should be sent to
it, you can pass this reg object into regregister after unregistering it, and
it will be reregistered (or activated if it was only suspended).
Caching
vicious.enable_caching(type)
- by default caching is enabled for all widget types, with caching
you can have multiple widgets using the same (widget type)function
and it gets executed only once
Widget types
------------
Widget types consist of worker functions that take the "format"
argument given to vicious.register as the first argument, "warg" as
the second, and return a table of values to insert in the format
string.
vicious.widgets.cpu
- provides CPU usage for all available CPUs/cores
vicious.widgets.cpuinf
- provides speed and cache information for all available CPUs/cores
vicious.widgets.cpufreq
- provides freq, voltage and governor info for a requested CPU
- takes the CPU ID as an argument, i.e. "cpu0"
vicious.widgets.thermal
- provides temperature levels of ACPI thermal zones
- takes the thermal zone as an argument, i.e. "TZS0"
vicious.widgets.load
- provides system load averages for the past 1, 5, and 15 minutes
vicious.widgets.uptime
- provides system uptime information
vicious.widgets.bat
- provides state, charge, and remaining time for a requested battery
- takes battery ID as an argument, i.e. "BAT0"
vicious.widgets.batat
- provides state, charge, and remaining time for all batteries using
acpitool
vicious.widgets.mem
- provides RAM and Swap usage statistics
vicious.widgets.fs
- provides file system disk space usage
- takes an (optional) argument which, if true, includes remote file
systems, only local file systems are included by default
vicious.widgets.dio
- provides I/O statistics for requested storage devices
- takes the disk as an argument, i.e. "/dev/hda"
vicious.widgets.hddtemp
- provides hard drive temperatures using the hddtemp daemon
- takes the hddtemp listening port as an argument, or fallbacks to
default port 7634
vicious.widgets.net
- provides usage statistics for all network interfaces
vicious.widgets.wifi
- provides wireless information for a requested interface
- takes the network interface as an argument, i.e. "wlan0"
vicious.widgets.mbox
- provides the subject of last e-mail in a mbox file
- takes the full path to the mbox as an argument
vicious.widgets.mboxc
- provides the count of total, old and new messages in a mbox
- takes the full path to the mbox as an argument
vicious.widgets.mdir
- provides a number of new and unread messages in a Maildir
structure
- takes the full path to the Maildir structure as an argument
vicious.widgets.gmail
- provides count of new and subject of last e-mail in a Gmail inbox
- takes a table with Gmail login information as an argument
vicious.widgets.entropy
- provides available system entropy
- takes the poolsize as an argument, or fallbacks to Linux 2.6
default entropy pool of 4096-bits
vicious.widgets.org
- provides agenda statistics for Emacs org-mode
- takes a table with full paths to agenda files, that will be
parsed, as an argument
vicious.widgets.pacman
- provides number of pending updates on Arch Linux
vicious.widgets.mpd
- provides the currently playing song in MPD
vicious.widgets.volume
- provides volume levels of requested ALSA mixers
- takes the ALSA channel as an argument, i.e. "Master"
vicious.widgets.weather
- provides weather information for a requested station
- takes the weather station ID as an argument, i.e. "LDRI"
vicious.widgets.date
- provides access to os.date, with optional custom formatting;
provided as the format string
Custom widget types
-------------------
Use any of the existing widgets as a starting point for your
own. Write a quick worker function that does the work and plug it
in. How data will be formatted, will it be red or blue, should be
defined in rc.lua (or somewhere else, outside the actual widget).
Format functions
----------------
You can use a function instead of a string as the format parameter, so
you are able to check the value returned by the widget type and change
it. You can change the color of the battery widget when it goes below
a certain point, or hide widgets when they return a certain value,
or...
- do not confuse this with just coloring the widget, in those cases
standard markup can be inserted into the format string
The format function will get the widget as its first argument, and a
table with the values otherwise inserted into the format string as its
second argument, and should return the text to be used for the widget.
Example widget
mpdwidget = widget({ type = 'textbox', name = 'mpdwidget' })
vicious.register(mpdwidget,vicious.widgets.mpd,
function (widget, args)
if args[1] == "Stopped" then return ''
else return 'MPD: '..args[1]
end
end)
- hides the mpd widget when there is no song playing, executed every
second (the default interval)
Usage examples
--------------
Remember, besides creating and registering widgets you have to add them
to a wibox in order to display them.
MPD widget
mpdwidget = widget({ type = 'textbox', name = 'mpdwidget' })
vicious.register(mpdwidget, vicious.widgets.mpd, '$1', 15)
- executed every 15 seconds, takes no arguments
Memory widget
memwidget = widget({ type = 'textbox', name = 'memwidget' })
vicious.register(memwidget, vicious.widgets.mem, '$1 ($2MB/$3MB)', 10)
- executed every 10 seconds, appends "MB" to 2nd and 3rd argument
File system widget
fswidget = awful.widget.progressbar({ layout = awful.widget.layout.horizontal.rightleft })
-- after setting progressbar properties, you can register with:
vicious.register(fswidget, vicious.widgets.fs, '${/home usep}', 120, true)
- executed every 120 seconds, requests the value of the ${/home usep}
key (/home usage in percent), enables support for remote file systems
HDD temperature widget
hddtempwidget = widget({ type = 'textbox', name = 'hddtempwidget' })
vicious.register(hddtempwidget, vicious.widgets.hddtemp, '${/dev/sda}°C', 240)
- executed every 240 seconds, requests the temperature level of the
${/dev/sda} key/disk and appends "°C" to the returned value, does
not provide the port argument so it fallbacks to default
Battery widget
batwidget = awful.widget.progressbar({ layout = awful.widget.layout.horizontal.rightleft })
-- after setting progressbar properties, you can register with:
vicious.register(batwidget, vicious.widgets.bat, '$2', 60, 'BAT0')
- executed every 60 seconds, provides "BAT0" battery ID as an
argument
CPU usage widget
cpuwidget = awful.widget.graph({ layout = awful.widget.layout.horizontal.rightleft })
-- after setting graph properties, you can register with:
vicious.register(cpuwidget, vicious.widgets.cpu, '$1', 2)
- executed every 2 seconds, feeds the graph with total usage
percentage of all CPUs/cores
Mbox widget
mboxwidget = widget({ type = 'textbox', name = 'mboxwidget' })
vicious.register(mboxwidget, vicious.widgets.mbox, '$1', 240, '/home/user/mail/Inbox')
- executed every 240 seconds, provides full path to the mbox as an
argument
Gmail widget
gmailwidget = widget({ type = 'textbox', name = 'gmailwidget' })
vicious.register(gmailwidget, vicious.widgets.gmail, 'Mail: ${count}', 600, {'user', 'pass'})
- executed every 10 minutes, provides a table with login information
as an argument, prepends "Mail: " to the returned value
All other widgets are used in the same manner, read each widget you
are interested in to see what data it returns. You can also use
authors rc.lua as a reference to see how it all fits into the big
picture:
http://git.sysphere.org/awesome-configs/
Other
-----
You should read "awesome" manual pages:
awesome(1) awesomerc(5)
Authors
-------
Vicious, written by:
Adrian C. (anrxc)
Wicked, written by:
Lucas de Vries