vicious/README

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 ones:

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


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

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

    widget
      - if 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. Suspending widgets
is one way to prevent widgets from draining your battery.

Update intervals also play a big role, and you can save a lot of power
with a smart approach. Avoid 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 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

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. "hda"

vicious.widgets.hddtemp
  - provides hard drive temperatures using the hddtemp daemon
  - takes the hddtemp listening port as an argument, or defaults to
    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 mbox files
  - takes a table with full paths to mbox files 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 on Gmail

vicious.widgets.entropy
  - provides available system entropy
  - takes the poolsize as an argument, or uses 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 ICAO station code 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 maybe hide widgets when they return a certain
value or... you get the point.

  - 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 '<span color="white">MPD:</span> '..args[1]
      end
    end)

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


Usage examples
--------------
Remember, beside 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', 11)

  - executed every 11 seconds, takes no arguments

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

  - executed 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', name = 'hddtempwidget' })
  vicious.register(hddtempwidget, vicious.widgets.hddtemp, '${/dev/sda}°C', 19)

  - executed 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', name = 'mboxwidget' })
  vicious.register(mboxwidget, vicious.widgets.mbox, '$1', 5, '/home/user/mail/Inbox')

  - executed every 5 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}', 601)

  - executed every 10 minutes and prepends "Mail: " to the returned value

Battery widget
  batwidget = awful.widget.progressbar({ layout = awful.widget.layout.horizontal.rightleft })
  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')

  - executed 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({ layout = awful.widget.layout.horizontal.rightleft })
  cpuwidget:set_width(50)
  cpuwidget:set_max_value(100)
  cpuwidget:set_background_color('#494B4F')
  cpuwidget:set_border_color('#3F3F3F')
  cpuwidget:set_color('#FF5656')
  cpuwidget:set_gradient_colors({
    '#FF5656',
    '#88A175',
    '#AECF96' })
  vicious.register(cpuwidget, vicious.widgets.cpu, '$1', 3)

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


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
-----
Also read "awesome" manual pages:

  awesome(1)  awesomerc(5)


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

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