From a8dc5c6f6d2f8572f7a7a5458ab969defdb47ded Mon Sep 17 00:00:00 2001 From: "Adrian C. (anrxc)" Date: Thu, 30 Jul 2009 04:44:22 +0200 Subject: Added basic documentation as a README file. The README explains some basics. Also fixed a typo in the dio widget description, that I noticed while writing documentation. --- README | 256 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..a3e081c --- /dev/null +++ b/README @@ -0,0 +1,256 @@ +Description +----------- + +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. You can read more about why and how it was written, here: + + http://sysphere.org/~anrxc/j/archives/2009/07/09/vicious_widgets_for_awesome_wm + + +Usage +----- + +To use vicious, 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, field, argument or padding) + +widget - widget created with widget() +type - one of the available widget types (see below for a list) +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 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 +field - used to feed graphs or progressbars, by their name +padding - minimum amount of numbers the widget will output, if + available for that widget type +argument - some widgets require an argument to be passed, like 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() + +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, "padding" or +"argument" the 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.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 usage statistics for requested mount points + +vicious.widgets.dio + - provides I/O statistics for requested storage devices + - takes the disk as an argument, i.e. "/dev/hda" + +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.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.entropy + - provides available system entropy + +vicious.widgets.org + - provides agenda statistics for Emacs org-mode + - takes a table with full paths to agenda files, that will be + included, 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. I +created vicious so we can focus on the number crunching and nothing +else. You write a quick worker function that does the work and plug it +in. How the data will be formatted, will it be red or blue, should be +defined in rc.lua. + + +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 a widget, i.e. on low battery, or hide +widgets when they return a certain value or... + +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 + + +Usage examples +-------------- + +Remember, besides creating and registering widgets you have to add them +to a statusbar in order to display them. + +MPD widget + mpdwidget = widget({type = 'textbox',name = 'mpdwidget') + vicious.register(mpdwidget,vicious.widgets.mpd,'$1',30) + + - executed every 30 seconds, takes no arguments + +Memory widget + memwidget = widget({type = 'textbox',name = 'memwidget'}) + vicious.register(memwidget,vicious.widgets.mem,'$1 ($2MB/$3MB)',1,nil,{2, 4, 4}) + + - executed every second, appends "MB" to 2nd and 3rd argument, uses + padding + +File system widget + fswidget = widget({type = 'progressbar',name = 'fswidget'}) + -- configure the progressbar and bar properties, then register with: + vicious.register(fswidget,vicious.widgets.fs,'${/home usep}',120,fswidget) + + - executed every 120 seconds, requests the value of the ${home usep} + key and feeds the "fswidget" progressbar + +Battery widget + batwidget = widget({type = 'progressbar',name = 'batwidget'}) + -- configure the progressbar and bar properties, then register with: + vicious.register(batwidget,vicious.widgets.bat,'$1',60,fswidget,'BAT0') + + - executed every 60 seconds, feeds the "batwidget" progressbar, + provides "BAT0" battery ID as an argument + +Mbox widget + mboxwidget = widget({type = 'textbox',name = 'mboxwidget'}) + vicious.register(mboxwidget,vicious.widgets.mbox,'$1',240,nil,'/home/user/mail/Inbox') + + - executed every 240 seconds, provides full path to the mbox as an + argument + + +All other widgets are used in the same manner. You can check the +authors rc.lua as a reference: + + http://sysphere.org/~anrxc/local/scr/dotfiles/awesomerc.lua.html + + +Other +----- + +You should read "awesome" manual pages: + + awesome(1) awesomerc(5) + + +Authors +------- + +Vicious, written by: + Adrian C. (anrxc) + +Wicked, authored by: + Lucas de Vries -- cgit v1.2.3