From fcda8a0ce40eabf48236252ecf8fd7adf89e999d Mon Sep 17 00:00:00 2001 From: "Adrian C. (anrxc)" Date: Thu, 24 Sep 2009 16:08:46 +0200 Subject: README rewritten to match HEAD Now also includes the Power section, and has full progressbar/graph settings in examples. --- README | 266 ++++++++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 164 insertions(+), 102 deletions(-) diff --git a/README b/README index f34b847..149a592 100644 --- a/README +++ b/README @@ -1,82 +1,104 @@ -Description ------------ - -Vicious is a modular widget library for "awesome" window manager, +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 -widgets. You can read more about why and how it was written, here: +Wicked widget types, a few of them rewritten, and a good number of +new widgets: - http://sysphere.org/~anrxc/j/archives/2009/07/09/vicious_widgets_for_awesome_wm + http://git.sysphere.org/vicious/ Usage ----- - -To use vicious, copy it to the ~/.config/awesome directory and edit -init.lua to comment out all the widgets you don't need, from the +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: +...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, warg) -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 custom 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 -warg - some widgets require an argument to be passed, like the - battery ID + widget + - widget created with widget() + + 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 + + field + - used to feed graphs and progressbars, by their name + + warg + - some widget types require an argument to be passed, for example + the battery ID Other Functions --------------- +Unregister a widget: -Unregister vicious.unregister(widget, keep) - keep - if true the widget will be suspended, waiting to be activated + keep + - if true widget will be suspended, waiting to be activated -Suspend - suspend all widgets, used when running on battery power - vicious.suspend() +Suspend all widgets: - - if you want it to happen automatically, see the example script for - the laptop-mode-tools start-stop programs module: - - http://sysphere.org/~anrxc/local/scr/sources/lmt-vicious.sh + vicious.suspend() -Activate - restart all suspended, or unregistered but kept, widgets - vicious.activate(widget) + - example automation script for the "laptop-mode-tools" start-stop + module: http://sysphere.org/~anrxc/local/sources/lmt-vicious.sh - widget - if provided, only that widget will be activated +Restart suspended widgets: -Regregister - vicious.regregister(reg) + vicious.activate(widget) - - 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). + widget + - if provided, only that widget will be activated -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 +Power +----- +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. + +Vicious also caches all widget types. Caching enables you to have +multiple widgets using the same widget type and its worker function +will be executed only once. + +Update intervals also play a big role, and you can save a lot of power +with a smart approach to intervals. You should 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 +widgets read files that reside in memory, others call external +utilities and some, like the mbox widget, read very big files. 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 @@ -115,6 +137,8 @@ vicious.widgets.mem 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 @@ -122,8 +146,8 @@ vicious.widgets.dio vicious.widgets.hddtemp - provides hard drive temperatures using the hddtemp daemon - - takes the hddtemp listening port as an argument, or fallbacks to - default port 7634 + - takes the hddtemp listening port as an argument, or defaults to + port 7634 vicious.widgets.net - provides usage statistics for all network interfaces @@ -145,15 +169,19 @@ vicious.widgets.mdir 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 in a Gmail inbox + - takes a table with Gmail login information as an argument + vicious.widgets.entropy - provides available system entropy - - takes the poolsize as an argument, or fallbacks to Linux 2.6 + - takes the poolsize as an argument, or defaults to 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 - included, as an argument + parsed, as an argument vicious.widgets.pacman - provides number of pending updates on Arch Linux @@ -167,7 +195,7 @@ vicious.widgets.volume vicious.widgets.weather - provides weather information for a requested station - - takes the weather station ID as an argument, i.e. "LDRI" + - takes the ICAO station code as an argument, i.e. "LDRI" vicious.widgets.date - provides access to os.date, with optional custom formatting; @@ -176,21 +204,22 @@ vicious.widgets.date 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. +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 a widget, i.e. on low battery, or hide -widgets when they return a certain value or... +it. You can change the color of the battery widget when it goes below +a certain point, or hide widgets when they return a certain value, +or... + + - 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 @@ -200,85 +229,118 @@ 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] + if args[1] == "Stopped" then return '' + else return 'MPD: '..args[1] end - end) + end) - - hides the mpd widget when there is no song playing + - hides the mpd widget when there is no song playing, executed every + 2 seconds (the default interval) Usage examples -------------- - -Remember, besides creating and registering widgets you have to add them -to a statusbar in order to display them. +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', 30) + vicious.register(mpdwidget, vicious.widgets.mpd, '$1', 11) - - executed every 30 seconds, takes no arguments + - executed every 11 seconds, takes no arguments Memory widget memwidget = widget({ type = 'textbox', name = 'memwidget' }) - vicious.register(memwidget, vicious.widgets.mem, '$1 ($2MB/$3MB)', 10) - - - executed every 10 seconds, appends "MB" to 2nd and 3rd argument + vicious.register(memwidget, vicious.widgets.mem, '$1 ($2MB/$3MB)', 13) -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 (/home usage in percent) and feeds the "fswidget" progressbar + - executed every 13 seconds, appends "MB" to 2nd and 3rd returned + values HDD temperature widget hddtempwidget = widget({ type = 'textbox', name = 'hddtempwidget' }) - vicious.register(hddtempwidget, vicious.widgets.hddtemp, '${/dev/sda}°C', 240) + vicious.register(hddtempwidget, vicious.widgets.hddtemp, '${/dev/sda}°C', 19) - - executed every 240 seconds, requests the temperature level of the + - 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 it fallbacks to default + 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, nil, '/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, nil, {'user', 'pass'}) + + - executed every 10 minutes, provides a table with login information + as an argument, prepends "Mail: " to the returned value Battery widget batwidget = widget({ type = 'progressbar', name = 'batwidget' }) - -- configure the progressbar and bar properties, then register with: - vicious.register(batwidget, vicious.widgets.bat, '$2', 60, batwidget, 'BAT0') - - - executed every 60 seconds, feeds the "batwidget" progressbar, + batwidget.width = 10 + batwidget.height = 0.9 + batwidget.gap = 0 + batwidget.border_padding = 1 + batwidget.border_width = 0 + batwidget.ticks_count = 4 + batwidget.ticks_gap = 1 + batwidget.vertical = true + batwidget:bar_properties_set('batbar', { + bg = '#3F3F3F', + fg = '#AECF96', + fg_center = '#88A175', + fg_end = '#FF5656', + fg_off = '#494B4F', + min_value = 0, + max_value = 100 + }) + vicious.register(batwidget, vicious.widgets.bat, '$2', 61, 'batbar', 'BAT0') + + - executed every 61 seconds, requests the current battery charge + level and feeds that data to a progressbar named "batbar", 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') +CPU usage widget + cpuwidget = widget({ type = 'graph', name = 'cpuwidget', align = 'right' }) + cpuwidget.width = 50 + cpuwidget.height = 0.90 + cpuwidget.grow = 'left' + cpuwidget.bg = '#494B4F' + cpuwidget.border_color = '#3F3F3F' + cpuwidget:plot_properties_set('cpuplot', { + fg = '#AECF96', + fg_center = '#88A175', + fg_end = '#FF5656', + vertical_gradient = false + }) + vicious.register(cpuwidget, vicious.widgets.cpu, '$1', 3, 'cpuplot') - - executed every 240 seconds, provides full path to the mbox as an - argument + - executed every 3 seconds, feeds the graph named "cpuplot" with + total usage percentage of all CPUs/cores -All other widgets are used in the same manner. You can use authors -rc.lua as a reference: +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://sysphere.org/~anrxc/local/scr/dotfiles/awesomerc.lua.html + http://git.sysphere.org/awesome-configs/tree/rc.lua?id=9abcf6c Other ----- +Also read "awesome" manual pages: -You should read "awesome" manual pages: - - awesome(1) awesomerc(5) + awesome(1) awesomerc(5) Authors ------- - Vicious, written by: Adrian C. (anrxc) -Wicked, authored by: +Wicked, written by: Lucas de Vries -- cgit v1.2.3