'\" t
.\"     Title: wicked
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 06/11/2012
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "WICKED" "7" "06/11/2012" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
wicked \- a lua library for dynamic widgets in awesome
.SH "SYNOPSIS"
.sp
None
.SH "DESCRIPTION"
.sp
wicked is a library, written in lua, for easy creation and management of dynamic awesome statusbar widgets, from the rc\&.lua configuration file\&.
.SH "USAGE"
.sp
To use wicked, put \fBrequire("wicked")\fR at the top of your rc\&.lua, from then on, create your widgets as normal and call \fBwicked\&.register()\fR to register them to wicked\&.
.sp
\fIwicked\&.register(\fR\fI\fBwidget\fR\fR\fI, \fR\fI\fBwidget_type\fR\fR\fI, \fR\fI\fBformat\fR\fR\fI, \fR\fI\fBupdate_interval\fR\fR\fI, \fR\fI\fBdata_field\fR\fR\fI, \fR\fI\fBpadding\fR\fR\fI)\fR
.sp
\fIwidget\fR
.sp
Use the widget created by widget for this argument\&.
.sp
\fIwidget_type\fR
.sp
Enter one of the possible widget type functions or a customised one here, see the \fIWIDGET TYPES\fR section\&.
.sp
\fIformat\fR
.sp
Format can be either a string argument where $1,$2,$3,etc\&. will be replaced by their respective values, or a function called with the arguments \fB(widget, arguments)\fR, arguments being a table of the values otherwise inserted into the string, if it is a function, its return value will be used to populate the widget\&. Note that some widget types might not need or use this parameter\&.
.sp
\fIupdate_interval\fR
.sp
The amount of seconds it waits between updating this widget, defaults to 1\&.
.sp
\fIdata_field\fR
.sp
If you want to feed the data into a graph or progressbar, put the bar or plot name you want to use in here\&.
.sp
\fIpadding\fR
.sp
To prevent widgets jumping about your statusbar all the time, you can specify a padding value here, the number given here represents the minimum amount of digits that the widget\(cqs output has to contain (ie specifying 2 padds values under 10 with one zero, specifying 3 padds values under 100 with one zero and values under 10 with two zeros, etc) If the widget type supports it, you can specify a table with different numbers, the first number being the padding for the first value the type would return, the second number for the second value, etc\&.
.SH "OTHER FUNCTIONS"
.sp
The following functions are also provided by wicked\&.
.sp
\fIwicked\&.unregister(\fR\fI\fBwidget\fR\fR\fI, \fR\fI\fBkeep\fR\fR\fI)\fR
.sp
Unregister all updates associated with a widget\&. Keep is optional (defaults to false), and if true, the widget will only be suspended, ready to be reactivated by the activate function later\&.
.sp
\fIwicked\&.suspend()\fR
.sp
Suspend all widget updates, useful if you are running in low\-power mode and want to save battery for a while\&.
.sp
\fIwicked\&.activate(widget)\fR
.sp
Restarts all widgets that were suspended either from wicked\&.suspend(), or by calling wicked\&.unregister() with keep=true\&. Widget is optional, if given, only that widget will be activated, defaults to all widgets\&.
.sp
\fIwicked\&.regregister(reg)\fR
.sp
wicked\&.register() and wicked\&.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)\&.
.sp
\fIwicked\&.enable_caching(widget_type)\fR
.sp
Enable caching of the values returned by a custom widget_type\&. Note that all widget_type functions included in wicked already have caching enabled by default\&.
.SH "WIDGET TYPES"
.sp
Widget types consist of functions that take the "format" argument given to wicked\&.register as the first argument, the "padding" argument as the second, and return a table of values to insert in the format string, creators of custom widget types should note that the format argument may be a function as well as a string\&.
.sp
For backwards compatibility purposes, if a string X is given as widget_type, it will use \*(Aqwicked\&.widgets\&.X\*(Aq as the widget type\&.
.sp
\fBwicked\&.widgets\&.date\fR
.sp
The date widget type uses the output of the `os\&.date` command to populate the widget, if format is given, it will be passed as the FORMAT argument to `os\&.date`\&.
.sp
\fBwicked\&.widgets\&.cpu\fR
.sp
The cpu widget type outputs the current cpu usage in percentages, calculated over the duration of it\(cqs update_interval\&. Use $1 inside the format string to display the total usage percentage, $2 to show it for your first cpu core only, $3 for the second core, etc\&.
.sp
\fBwicked\&.widgets\&.mem\fR
.sp
The memory widget type outputs four things, $1 will be replaced with the current memory usage in percentages, $2 will be replaced with the total used memory in Mb, $3 with the total amount memory available to the system, and $4 with the amount of free memory\&.
.sp
\fBwicked\&.widgets\&.swap\fR
.sp
The swap widget type outputs the same values as the memory widget type, about the amount of swap in use/available\&.
.sp
\fBwicked\&.widgets\&.mpd\fR
.sp
The mpd widget type outputs the song currently playing on the music player daemon, note that the `mpc` application needs to be installed and configured in order to use this\&.
.sp
\fBwicked\&.widgets\&.mocp\fR
.sp
The mocp widget type outputs the song currently playing on the mocp server\&. Use $1 inside the format string to display the current song\&. A maxlength can be given to the wicked\&.register() function which will cut the songname in two when exeeded and displays the first and last part\&. A typical functioncall looks like this: wicked\&.register(mocpwidget, \*(Aqmocp\*(Aq, \*(AqMOC: $1\*(Aq, 1, nil, 50)\&. Here 50 is the max amount of characters displayed of $1\&.
.sp
\fBwicked\&.widgets\&.fs\fR
.sp
The fs widget type can display size and usage information about currently mounted filesystems, use ${mountpoint datatype} inside the format string to display that data, e\&.g\&. ${/ avail} displays the free space on the partition mounted on /\&. Available datatypes are \*(Aqused\*(Aq, \*(Aqsize\*(Aq, \*(Aqusep\*(Aq (Usage in %) and \*(Aqavail\*(Aq\&.
.sp
\fBwicked\&.widgets\&.net\fR
.sp
The net widget type displays usage information about your networks, in the format string, ${interface type} will be replaced with with that value, possible types are: rx, tx, up, down\&. You can suffix the type with _b, _kb, _mb or _gb, to display the information in those units\&.
.sp
\fBwicked\&.widgets\&.uptime\fR
.sp
The uptime widget type displays information about how long your machine has been on (or "up")\&. Use $1 for the total number of seconds up, $2 for the number of days, $3 for the number of hours, $4 for the number of minutes and $5 for the number of seconds\&.
.SH "CUSTOM TYPES"
.sp
You can create your own custom widgets easily, an example of a widget that returns the output of a specific command is:
.sp
.if n \{\
.RS 4
.\}
.nf
mywidget = widget({
    type = \*(Aqtextbox\*(Aq,
    name = \*(Aqmywidget\*(Aq
})

function run_script()
   local filedescriptor = io\&.popen(\*(Aqmy_nifty_script\&.py\*(Aq)
   local value = filedescriptor:read()
   filedescriptor:close()

   return {value}
end

\-\- Runs \*(Aqmy_nifty_script\&.py\*(Aq every 10 seconds and puts its output into the widget
wicked\&.register(mywidget, run_script, "$1", 10)
.fi
.if n \{\
.RE
.\}
.sp
As you can see, the type function returns a table of values to insert into the format string, the first value in the table will be used in place of $1, the second in place of $2, etc\&.
.sp
If you want to register the same function multiple times, it is a good idea to enable caching so that your function is only called once in each interval\&. To do this call the \fIenable_caching\fR function like so:
.sp
.if n \{\
.RS 4
.\}
.nf
wicked\&.enable_caching(run_script)
.fi
.if n \{\
.RE
.\}
.SH "FORMAT FUNCTIONS"
.sp
You can use a function instead of a string as the format parameter, with this, you are able to check the value returned by wicked and change the output accordingly\&. 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\&.
.sp
An example that uses a format function in order to hide the mpd widget when there is no song playing:
.sp
.if n \{\
.RS 4
.\}
.nf
mpdwidget = widget({
    type = \*(Aqtextbox\*(Aq,
    name = \*(Aqmpdwidget\*(Aq
})

wicked\&.register(mpdwidget, wicked\&.widgets\&.mpd,
    function (widget, args)
        if args[1]:find("volume:") == nil then
            return \*(Aq <span color="white">Now Playing:</span> \*(Aq\&.\&.args[1]
        else
            return \*(Aq\*(Aq
        end
    end)
.fi
.if n \{\
.RE
.\}
.SH "USAGE EXAMPLES"
.sp
Put these snippets into your rc\&.lua (usually located at ~/\&.config/awesome/rc\&.lua) to see what they do, don\(cqt forget to add the widgets to your statusbar\&.
.sp
\fBA simple \*(AqNow Playing\*(Aq widget\fR
.sp
.if n \{\
.RS 4
.\}
.nf
mpdwidget = widget({
    type = \*(Aqtextbox\*(Aq,
    name = \*(Aqmpdwidget\*(Aq
})

wicked\&.register(mpdwidget, wicked\&.widgets\&.mpd,
    \*(Aq <span color="white">Now Playing:</span> $1\*(Aq)
.fi
.if n \{\
.RE
.\}
.sp
\fBA memory usage monitor, with padding\fR
.sp
.if n \{\
.RS 4
.\}
.nf
memwidget = widget({
    type = \*(Aqtextbox\*(Aq,
    name = \*(Aqmemwidget\*(Aq
})

wicked\&.register(memwidget, wicked\&.widgets\&.mem,
    \*(Aq <span color="white">Memory:</span> $1 ($2Mb/$3Mb)\*(Aq,
    {2, 4, 4})
.fi
.if n \{\
.RE
.\}
.sp
\fBA filesystem usage indicator\fR
.sp
.if n \{\
.RS 4
.\}
.nf
fswidget = widget({
    type = \*(Aqtextbox\*(Aq,
    name = \*(Aqfswidget\*(Aq
})

wicked\&.register(fswidget, wicked\&.widgets\&.fs,
    \*(Aq <span color="white">FS:</span> ${/ used}/${/ size} (${/ usep} used)\*(Aq, 120)
.fi
.if n \{\
.RE
.\}
.sp
\fBA network interface monitor (for eth0)\fR
.sp
.if n \{\
.RS 4
.\}
.nf
netwidget = widget({
    type = \*(Aqtextbox\*(Aq,
    name = \*(Aqnetwidget\*(Aq
})

wicked\&.register(netwidget, wicked\&.widgets\&.net,
    \*(Aq <span color="white">NET</span>: ${eth0 down} / ${eth0 up} [ ${eth0 rx} // ${eth0 tx} ]\*(Aq)
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
awesome(1) awesomerc(5)
.SH "AUTHORS"
.sp
Lucas de Vries <\m[blue]\fBlucas@glacicle\&.com\fR\m[]\&\s-2\u[1]\d\s+2>
.SH "NOTES"
.IP " 1." 4
lucas@glacicle.com
.RS 4
\%mailto:lucas@glacicle.com
.RE