Vicious

From awesome

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.

Contents 1 Understanding Vicious 2 Getting Vicious 2.1 Older awesome versions 3 Using Vicious 3.1 Example widgets 3.1.1 Date (textbox) 3.1.2 Memory usage (textbox) 3.1.3 Memory usage (progressbar) 3.1.4 CPU usage (textbox) 3.1.5 CPU usage (graph) 3.2 Wicked widgets 3.3 Awesome widgets

[edit] Understanding Vicious

Vicious widget types are a framework for creating your own awesome widgets. Before using a widget type you need to ensure that a valid source of information exists.

• 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.

[edit] 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/

[edit] 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.

[edit] Using Vicious

Your first step should be editing init.lua to comment out all the widget types you don't need, from the "Configure widgets" list. It is not required but I suggest you do so to avoid having useless widgets sitting in your memory. Then add the following to the top of your rc.lua:

   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.

[edit] 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.

[edit] Date (textbox)

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

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

[edit] Memory usage (textbox)

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

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

[edit] Memory usage (progressbar)

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

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

[edit] CPU usage (textbox)

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

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

[edit] CPU usage (graph)

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

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

[edit] 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.

[edit] 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.