path: root/README

Vicious
-------
Vicious is a modular widget library for the "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
ones:

  http://git.sysphere.org/vicious/about/

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.


Usage
-----
To use vicious move it to your awesome configuration directory in
$XDG_CONFIG_HOME (usually ~/.config):

  $ mv vicious $XDG_CONFIG_HOME/awesome/

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 modules
sitting in your memory.

Then add the following to the top of your rc.lua:

  require("vicious")

Once you create a widget (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, see below for a list

    format
      - string argument or a function
        - $1, $2, $3... will be replaced by their respective value
          returned by 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 about this below

    interval
      - number of seconds between updates of the widget, 2s by
        default, also read the "Power" section below

    warg
      - some widget types require an argument to be passed, for example
        the battery ID


Other functions
---------------
Unregister a widget:
  vicious.unregister(widget, keep)

    - if keep is true widget will be suspended, waiting to be
      activated

Suspend all widgets:
  vicious.suspend()

    - example automation script for the "laptop-mode-tools" start-stop
      module: http://sysphere.org/~anrxc/local/sources/lmt-vicious.sh

Restart suspended widgets:
  vicious.activate(widget)

    - if widget is provided only that widget will be activated

Enable caching for a widget:
  vicious.enable_caching(widget_type)

    - enable caching of values returned by a widget type


Power and Caching
-----------------
When a lot of widgets are in use they, and awesome, can generate a lot
of wake-ups and also be very expensive for system resources. This is
especially important when running on battery power. It was a big
problem with awesome v2 and widgets that used shell scripts to gather
data, and with widget libraries written in languages like Ruby.

Lua is an extremely fast and efficient programming language, and
Vicious takes advantage of that. But suspending Vicious widgets is one
way to prevent them from draining your battery, despite that.

Update intervals also play a big role, and you can save a lot of power
with a smart approach. Don't use intervals like: 5, 10, 30, 60... to
avoid harmonics. If you take the 60-second mark as an example, all of
your widgets would be executed at that point. Instead think about
using only prime numbers, in that case you will have only a few
widgets executed at any given time interval. When choosing intervals
also consider what a widget actually does. Some widget types read
files that reside in memory, others call external utilities and some,
like the mbox widget, read big files.

Vicious can also cache values returned by widget types. Caching
enables you to have multiple widgets using the same widget type. With
caching its worker function gets executed only once - which is also
great for saving power.

  - Some widget types keep internal data and if you call one multiple
    times without caching, the widget that executes it first would
    modify stored values. This can lead to problems and give you
    inconsistent data. Remember it for widget types like CPU and
    Network usage, which compare the old set of data with the new one
    to calculate current usage.

  - Widget types that require a widget argument to be passed should be
    handled carefully. If you are requesting information for different
    devices then caching should not be used, because you could get
    inconsistent data.


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
  - returns 1st value as usage of all CPUs/cores, 2nd as usage of
    first CPU/core, 3rd as usage of second CPU/core etc.

vicious.widgets.cpuinf
  - provides speed and cache information for all available CPUs/cores
  - returns a table with custom keys, using CPU ID as a base:
    {cpu0 mhz}, {cpu0 ghz}, {cpu0 kb}, {cpu0 mb}, {cpu1 mhz} etc.

vicious.widgets.cpufreq
  - provides freq, voltage and governor info for a requested CPU
  - takes the CPU ID as an argument, i.e. "cpu0"
  - returns 1st value as frequency of requested CPU in MHz, 2nd in
    GHz, 3rd as voltage in mV, 4th as voltage in V and 5th as the
    governor state

vicious.widgets.thermal
  - provides temperature levels of ACPI thermal zones
  - takes the thermal zone as an argument, i.e. "TZS0"
  - returns 1st value as temperature of requested thermal zone

vicious.widgets.load
  - provides system load averages for the past 1, 5, and 15 minutes
  - returns 1st value as load average for past 1 minute, 2nd for 5
    minutes and 3rd for 15 minutes

vicious.widgets.uptime
  - provides system uptime information
  - returns 1st value as total uptime, 2nd as uptime in days, 3rd as
    uptime in hours, 4th as uptime in minutes and 5th as uptime in
    seconds

vicious.widgets.bat
  - provides state, charge, and remaining time for a requested battery
    using procfs
  - takes battery ID as an argument, i.e. "BAT0"
  - returns 1st value as state of requested battery, 2nd as charge
    level in percent and 3rd as remaining (charging or discharging)
    time

vicious.widgets.batsys
  - provides state, charge, and remaining time for a requested battery
    using sysfs
  - takes battery ID as an argument, i.e. "BAT0"
  - returns 1st value as state of requested battery, 2nd as charge
    level in percent and 3rd as remaining (charging or discharging)
    time

vicious.widgets.mem
  - provides RAM and Swap usage statistics
  - returns 1st value as memory usage in percent, 2nd as memory usage,
    3rd as total system memory, 4th as free memory, 5th as swap usage
    in percent, 6th as swap usage, 7th as total system swap and 8th as
    free swap

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
  - returns a table with custom keys, using mount points as a base:
    {/ size}, {/ used}, {/ avail}, {/ usep}, {/home size} etc.

vicious.widgets.dio
  - provides I/O statistics for requested storage devices
  - takes the disk as an argument, i.e. "hda"
  - returns a table with custom keys: {raw}, {kb} and {mb}

vicious.widgets.hddtemp
  - provides hard drive temperatures using the hddtemp daemon
  - takes the hddtemp listening port as an argument, or defaults to
    port 7634
  - returns a table with custom keys, using hard drives as a base:
    {/dev/hda} and {/dev/sda} for example

vicious.widgets.net
  - provides usage statistics for all network interfaces
  - returns a table with custom keys, using net interfaces as a base:
    {eth0 rx_b}, {eth0 tx_b}, {eth0 rx_kb}, {eth0 tx_kb}, {eth0 rx_mb},
    {eth0 tx_mb}, {eth0 rx_gb}, {eth0 tx_gb}, {eth0 down_b}, {eth0 up_b},
    {eth0 down_kb}, {eth0 up_kb}, {eth0 down_mb}, {eth0 up_mb},
    {eth0 down_gb}, {eth0 up_gb}, {eth1 rx_b} etc.

vicious.widgets.wifi
  - provides wireless information for a requested interface
  - takes the network interface as an argument, i.e. "wlan0"
  - returns a table with custom keys: {ssid}, {mode}, {chan}, {rate},
    {link} and {sign}

vicious.widgets.mbox
  - provides the subject of last e-mail in a mbox file
  - takes the full path to the mbox as an argument
  - returns 1st value as the subject of the last e-mail

vicious.widgets.mboxc
  - provides the count of total, old and new messages in mbox files
  - takes a table with full paths to mbox files as an argument
  - returns 1st value as the total count of messages, 2nd as the count
    of old messages and 3rd as the count of new messages

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
  - returns 1st value as the count of new messages and 2nd as the
    count of "old" messages lacking the Seen flag

vicious.widgets.gmail
  - provides count of new and subject of last e-mail on Gmail
  - returns a table with custom keys: {count} and {subject}

vicious.widgets.entropy
  - provides available system entropy
  - takes the poolsize as an argument, or uses Linux 2.6 default
    entropy pool of 4096-bits
  - returns 1st value as available system entropy and 2nd value as
    available entropy in percent

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
  - returns 1st value as count of tasks you forgot to do, 2nd as count
    of tasks for today, 3rd as count of tasks for the next 3 days and
    4th as count of tasks to do in the week

vicious.widgets.pacman
  - provides number of pending updates on Arch Linux
  - returns 1st value as the count of available updates

vicious.widgets.mpd
  - provides the currently playing song in MPD
  - returns 1st value as the currently playing song

vicious.widgets.volume
  - provides volume levels of requested ALSA mixers
  - takes the ALSA channel as an argument, i.e. "Master"
  - returns 1st value as the volume level of the requested channel

vicious.widgets.weather
  - provides weather information for a requested station
  - takes the ICAO station code as an argument, i.e. "LDRI"
  - returns a table with custom keys: {city}, {wind}, {windmph},
    {windkmh}, {sky}, {weather}, {tempf}, {tempc}, {humid}, {press}

vicious.widgets.date
  - provides access to os.date, with optional custom formatting;
    provided as the format string
  - returns the output of os.date(), formatted by provided sequences


Custom widget types
-------------------
Use any of the existing widget types 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 module).


Usage examples
--------------
Start with a simple widget, like date. Then build your setup from
there, one widget at a time. Also remember that besides creating and
registering widgets you have to add them to a wibox (statusbar) in
order to actually display them.

Date widget
  datewidget = widget({ type = 'textbox' })
  vicious.register(datewidget, vicious.widgets.date, '%b %d, %R')

  - updated every 2 seconds (the default interval), uses standard
    date sequences as the format string

Memory widget
  memwidget = widget({ type = 'textbox' })
  vicious.enable_caching(vicious.widgets.mem)
  vicious.register(memwidget, vicious.widgets.mem, '$1 ($2MB/$3MB)', 13)

  - updated every 13 seconds, appends "MB" to 2nd and 3rd returned
    values and enables caching of this widget type

HDD temperature widget
  hddtempwidget = widget({ type = 'textbox' })
  vicious.register(hddtempwidget, vicious.widgets.hddtemp, '${/dev/sda}°C', 19)

  - updated every 19 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 default port is used

Mbox widget
  mboxwidget = widget({ type = 'textbox' })
  vicious.register(mboxwidget, vicious.widgets.mbox, '$1', 5, '/home/user/mail/Inbox')

  - updated every 5 seconds, provides full path to the mbox as an
    argument

Battery widget
  batwidget = awful.widget.progressbar()
  batwidget:set_width(8)
  batwidget:set_height(10)
  batwidget:set_vertical(true)
  batwidget:set_background_color('#494B4F')
  batwidget:set_border_color(nil)
  batwidget:set_color('#AECF96')
  batwidget:set_gradient_colors({ '#AECF96', '#88A175', '#FF5656' })
  vicious.register(batwidget, vicious.widgets.bat, '$2', 61, 'BAT0')

  - updated every 61 seconds, requests the current battery charge
    level and displays a progressbar, provides "BAT0" battery ID as an
    argument

CPU usage widget
  cpuwidget = awful.widget.graph()
  cpuwidget:set_width(50)
  cpuwidget:set_background_color('#494B4F')
  cpuwidget:set_color('#FF5656')
  cpuwidget:set_gradient_colors({ '#FF5656', '#88A175', '#AECF96' })
  vicious.register(cpuwidget, vicious.widgets.cpu, '$1', 3)

  - updated every 3 seconds, feeds the graph with total usage
    percentage of all CPUs/cores


Format functions
----------------
You can use a function instead of a string as the format parameter.
Then you are able to check the value returned by the widget type and
change it or perform some action. You can change the color of the
battery widget when it goes below a certain point, hide widgets when
they return a certain value or maybe use string.format for padding.

  - 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
  mpdwidget = widget({ type = 'textbox' })
  vicious.register(mpdwidget,vicious.widgets.mpd,
    function (widget, args)
      if   args[1] == "Stopped" then return ''
      else return '<span color="white">MPD:</span> '..args[1]
      end
    end)

  - hides the mpd widget when there is no song playing, updated every
    2 seconds (the default interval)

Example
  uptimewidget = widget({ type = 'textbox' })
  vicious.register(uptimewidget, vicious.widgets.uptime,
    function (widget, args)
      return string.format('Uptime: %2dd %02d:%02d ', args[2], args[3], args[4])
    end, 61)

  - uses string.format for padding uptime values to a minimum amount
    of digits, updated every 61 seconds


Other
-----
Read "awesome" manual pages:

  awesome(1)  awesomerc(5)

Authors "awesome" configuration:

  http://git.sysphere.org/awesome-configs/


Authors
-------
Vicious, written by:
  Adrian C. (anrxc) <anrxc@sysphere.org>

Wicked, written by:
  Lucas de Vries <lucas@glacicle.com>