Vicious

Vicious is a modular widget library for awesome, 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 ones.

Understanding Vicious
Vicious widget types are a framework for creating your own awesome widgets. Vicious contains modules that gather data about your system, and a few helper functions that make it easier to register timers, suspend widgets and so on.


 * What about Wicked?
 * It wasn't modular.
 * What about Obvious?
 * By design it's the opposite of vicious.
 * What about Bashets?
 * Targets a different profile of users.


 * Vicious guidelines:
 * Widgets should be modular, you plug-in widgets that you need and ignore the rest.
 * Widget type is small, 10+ lines, module with a worker function that crunches data and returns it raw.
 * How data will be formatted, colored red or blue, should be defined somewhere else (rc.lua most likely).
 * Likewise, it is not our job to register button bindings, tooltips or naughty notifications.
 * Widgets should not be expensive for system resources, especially when running on battery power.
 * Widgets should be easy to install, so at this point they don't rely on third party Lua libraries.

Getting Vicious
Vicious is hosted on http://git.sysphere.org/vicious/ where you can download the tarball of the latest release/tag, or get the development code with git. Git access is provided over http, you can clone the repo with:

$ git clone http://git.sysphere.org/vicious

Once you extract the tarball, or clone the repository, you should move vicious to your awesome configuration directory in $XDG_CONFIG_HOME (usually ~/.config).

$ mv vicious $XDG_CONFIG_HOME/awesome/

On Ubuntu
Ubuntu repository contains a package called "awesome-extra", which includes Vicious library. Just type:

$ sudo aptitude install awesome-extra

On Arch Linux
Arch Community repository contains the package vicious. Just type:

$ sudo pacman -S vicious

Older awesome versions
Vicious tag v1.0.11 is the last release compatible with awesome versions prior to 3.4. In v1.0.12 vicious was ported to the new timers infrastructure and awful widgets, there is no backward compatibility. However, bug fixes and improvements were backported and last recommended release to use with older awesome versions is v1.0.11.4.

Using Vicious
Vicious loads only widget types you intend to use, and register in your awesome configuration, to avoid having useless modules sitting in your memory. To start using Vicious add the following to the top of your rc.lua:

vicious = require("vicious")

From there you can register any (textbox, graph or a progressbar) widget by calling the vicious.register function. Included README file explains all of this in more detail, and covers everything from available functions and a description of widget types to actual examples.

Example widgets

 * Start with a simple widget, like date. Then build your setup from there, one widget at a time.
 * Remember that besides creating widgets you have to add them to a wibox (statusbar) to actually display them.

Date (textbox)
This widget displays date and time. In this example it is updated every 60 seconds.

For awesome 3.4

-- Initialize widget datewidget = widget({ type = "textbox" }) -- Register widget vicious.register(datewidget, vicious.widgets.date, "%b %d, %R", 60)

For awesome 3.5

-- Initialize widget datewidget = wibox.widget.textbox -- Register widget vicious.register(datewidget, vicious.widgets.date, "%b %d, %R", 60)

To get a list of all the available date formats, type man strftime in a shell

Memory usage (textbox)
This example displays the relative memory usage, usage in MB and total system memory, updated every 13 seconds.

For awesome 3.4

-- Initialize widget memwidget = widget({ type = "textbox" }) -- Register widget vicious.register(memwidget, vicious.widgets.mem, "$1% ($2MB/$3MB)", 13)

For awesome 3.5

-- Initialize widget memwidget = wibox.widget.textbox -- Register widget vicious.register(memwidget, vicious.widgets.mem, "$1% ($2MB/$3MB)", 13)

Memory usage (progressbar)
This example displays the relative memory usage in a progressbar, updated every 13 seconds.

For awesome 3.4

-- Initialize widget memwidget = awful.widget.progressbar -- Progressbar properties memwidget:set_width(8) memwidget:set_height(10) memwidget:set_vertical(true) memwidget:set_background_color("#494B4F") memwidget:set_border_color(nil) memwidget:set_color("#AECF96") memwidget:set_gradient_colors({ "#AECF96", "#88A175", "#FF5656" }) -- Register widget vicious.register(memwidget, vicious.widgets.mem, "$1", 13)

For awesome 3.5 

-- Initialize widget memwidget = awful.widget.progressbar -- Progressbar properties memwidget:set_width(8) memwidget:set_height(10) memwidget:set_vertical(true) memwidget:set_background_color("#494B4F") memwidget:set_border_color(nil) memwidget:set_color({ type = "linear", from = { 0, 0 }, to = { 10,0 }, stops = { {0, "#AECF96"}, {0.5, "#88A175"},                    {1, "#FF5656"}}}) -- Register widget vicious.register(memwidget, vicious.widgets.mem, "$1", 13)

CPU usage (textbox)
This example displays CPU usage of all available CPUs/cores, updated every 2 seconds (the default interval).

For awesome 3.4

-- Initialize widget cpuwidget = widget({ type = "textbox" }) -- Register widget vicious.register(cpuwidget, vicious.widgets.cpu, "$1%")

For awesome 3.5

-- Initialize widget cpuwidget = wibox.widget.textbox -- Register widget vicious.register(cpuwidget, vicious.widgets.cpu, "$1%")

CPU usage (graph)
This example displays a graph with CPU usage of all available CPUs/cores, updated every 2 seconds (the default interval).

For awesome 3.4

-- Initialize widget cpuwidget = awful.widget.graph -- Graph properties cpuwidget:set_width(50) cpuwidget:set_background_color("#494B4F") cpuwidget:set_color("#FF5656") cpuwidget:set_gradient_colors({ "#FF5656", "#88A175", "#AECF96" }) -- Register widget vicious.register(cpuwidget, vicious.widgets.cpu, "$1")

For awesome 3.5

-- Initialize widget cpuwidget = awful.widget.graph -- Graph properties cpuwidget:set_width(50) cpuwidget:set_background_color("#494B4F") cpuwidget:set_color({ type = "linear", from = { 0, 0 }, to = { 10,0 }, stops = { {0, "#FF5656"}, {0.5, "#88A175"},                    {1, "#AECF96" }}}) -- Register widget vicious.register(cpuwidget, vicious.widgets.cpu, "$1")

MPD Status (textbox)
This example displays the artist and the song which that are currently playing with MPD. This example also shows how a format function can be used to manipulate the output.

 For awesome 3.4 

-- Initialize widget mpdwidget = widget({ type = "textbox" }) -- Register widget vicious.register(mpdwidget, vicious.widgets.mpd,   function (widget, args)        if args["{state}"] == "Stop" then             return " - "        else             return args["{Artist}"]..' - '.. args["{Title}"]        end    end, 10)

 For awesome 3.5 

-- Initialize widget mpdwidget = wibox.widget.textbox -- Register widget vicious.register(mpdwidget, vicious.widgets.mpd,   function (mpdwidget, args)        if args["{state}"] == "Stop" then             return " - "        else             return args["{Artist}"]..' - '.. args["{Title}"]        end    end, 10)

Wicked widgets
Switching from Wicked to Vicious is straightforward. There are small differences in the API:


 * Caching is entirely controlled by users.
 * Using a string widget type is not allowed.
 * Padding is not provided by vicious helpers.

Awesome widgets
If you want to know more about awesome widget types and objects, how they work, their properties and so on... read the Widgets in awesome page. If you plan to use graph or progressbar widgets then you must read it, vicious users always make the same mistake when adding these widget types to the wibox.