Delete README
This commit is contained in:
Jörg Thalheim
GitHub
parent
cbee482088
commit
4820cb4d39
595
README
595
README
|
|
@ -1,595 +0,0 @@
|
||||||
Vicious
|
|
||||||
-------
|
|
||||||
Vicious is a modular widget library for window managers, but mostly
|
|
||||||
catering to users of the "awesome" window manager. It was derived from
|
|
||||||
the old "Wicked" widget library, and 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
|
|
||||||
widgets. Vicious contains modules that gather data about your system,
|
|
||||||
and a few "awesome" helper functions that make it easier to register
|
|
||||||
timers, suspend widgets and so on.
|
|
||||||
|
|
||||||
For now Vicious doesn't depend on any third party Lua libraries, to
|
|
||||||
make it easier to install and use. That means some system utilities
|
|
||||||
are used instead, where available:
|
|
||||||
|
|
||||||
- hddtemp for the HDD Temperature widget type
|
|
||||||
- alsa-utils for the Volume widget type
|
|
||||||
- wireless_tools for the Wireless widget type
|
|
||||||
- curl for widget types accessing network resources
|
|
||||||
|
|
||||||
|
|
||||||
Usage
|
|
||||||
-----
|
|
||||||
When provided by an operating system package, or installed from source
|
|
||||||
into the Lua library path Vicious can be used as a regular Lua
|
|
||||||
library, to be used stand-alone or to feed widgets of any window
|
|
||||||
manager (ie. Ion, WMII). It is compatible with both Lua v5.1 and v5.2.
|
|
||||||
|
|
||||||
$ lua
|
|
||||||
> widgets = require("vicious.widgets")
|
|
||||||
> print(widgets.volume(nil, "Master")[1])
|
|
||||||
100
|
|
||||||
|
|
||||||
|
|
||||||
Usage within Awesome
|
|
||||||
--------------------
|
|
||||||
To use Vicious with Awesome, install the package from your operating
|
|
||||||
system provider, or download the source code and move it to your
|
|
||||||
awesome configuration directory in $XDG_CONFIG_HOME (usually ~/.config):
|
|
||||||
|
|
||||||
$ mv vicious $XDG_CONFIG_HOME/awesome/
|
|
||||||
|
|
||||||
Vicious will only load modules for widget types you intend to use in
|
|
||||||
your awesome configuration, to avoid having useless modules sitting in
|
|
||||||
your memory.
|
|
||||||
|
|
||||||
Then add the following to the top of your rc.lua:
|
|
||||||
|
|
||||||
vicious = require("vicious")
|
|
||||||
|
|
||||||
Once you create a widget (a textbox, graph or a progressbar) call
|
|
||||||
vicious.register() to register it with Vicious:
|
|
||||||
|
|
||||||
vicious.register(widget, wtype, format, interval, warg)
|
|
||||||
|
|
||||||
widget
|
|
||||||
- widget created with widget() or awful.widget() (in case of a
|
|
||||||
graph or a progressbar)
|
|
||||||
|
|
||||||
wtype
|
|
||||||
- widget type or a function
|
|
||||||
- any of the available (default, or custom) widget types can
|
|
||||||
be used here, see below for a list of those provided by
|
|
||||||
Vicious
|
|
||||||
- function
|
|
||||||
- custom functions from your own "awesome" configuration can
|
|
||||||
be registered as widget types, see the "Custom widget types"
|
|
||||||
section
|
|
||||||
|
|
||||||
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 string 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 of a widget type:
|
|
||||||
vicious.cache(wtype)
|
|
||||||
|
|
||||||
- enable caching of values returned by a widget type
|
|
||||||
|
|
||||||
Force update of widgets:
|
|
||||||
vicious.force({ widget, })
|
|
||||||
|
|
||||||
- widget argument is a table with one or more widgets that will be
|
|
||||||
updated
|
|
||||||
|
|
||||||
|
|
||||||
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 string 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 and coretemp thermal zones
|
|
||||||
- takes the thermal zone as an argument, i.e. "thermal_zone0", or a
|
|
||||||
table with 1st field as thermal zone, 2nd as data source -
|
|
||||||
available data sources are "proc", "core" and "sys" (which is the
|
|
||||||
default when only the zone is provided) and 3rd optional argument
|
|
||||||
as a temperature input file to read
|
|
||||||
- returns 1st value as temperature of requested thermal zone
|
|
||||||
|
|
||||||
vicious.widgets.uptime
|
|
||||||
- provides system uptime and load information
|
|
||||||
- returns 1st value as uptime in days, 2nd as uptime in hours, 3rd
|
|
||||||
as uptime in minutes, 4th as load average for past 1 minute, 5th
|
|
||||||
for 5 minutes and 6th for 15 minutes
|
|
||||||
|
|
||||||
vicious.widgets.bat
|
|
||||||
- provides state, charge, remaining time and wear for a requested
|
|
||||||
battery
|
|
||||||
- takes battery ID as an argument, i.e. "BAT0"
|
|
||||||
- returns 1st value as state of requested battery, 2nd as charge
|
|
||||||
level in percent, 3rd as remaining (charging or discharging)
|
|
||||||
time and 4th as the wear level in percent
|
|
||||||
|
|
||||||
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, 8th as
|
|
||||||
free swap and 9th as memory usage with buffers and cache
|
|
||||||
|
|
||||||
vicious.widgets.os
|
|
||||||
- provides operating system information
|
|
||||||
- returns 1st value as the operating system in use, 2nd as the
|
|
||||||
release version, 3rd as your username, 4th the hostname, 5th as
|
|
||||||
available system entropy and 6th value as available entropy in
|
|
||||||
percent
|
|
||||||
|
|
||||||
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 string keys, using mount points as a base:
|
|
||||||
{/ size_mb}, {/ size_gb}, {/ used_mb}, {/ used_gb}, {/ used_p},
|
|
||||||
{/ avail_mb}, {/ avail_gb}, {/ avail_p}, {/home size_mb} etc.
|
|
||||||
|
|
||||||
vicious.widgets.dio
|
|
||||||
- provides I/O statistics for all available storage devices
|
|
||||||
- returns a table with string keys: {sda total_s}, {sda total_kb},
|
|
||||||
{sda total_mb}, {sda read_s}, {sda read_kb}, {sda read_mb},
|
|
||||||
{sda write_s}, {sda write_kb}, {sda write_mb}, {sdb1 total_s} etc.
|
|
||||||
|
|
||||||
vicious.widgets.raid
|
|
||||||
- provides state information for a requested RAID array
|
|
||||||
- takes the RAID array ID as an argument
|
|
||||||
- returns 1st value as the number of assigned, and 2nd as active,
|
|
||||||
devices in the array
|
|
||||||
|
|
||||||
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 string keys, using hard drives as a base:
|
|
||||||
{/dev/sda} and {/dev/sdc} for example
|
|
||||||
|
|
||||||
vicious.widgets.net
|
|
||||||
- provides state and usage statistics of all network interfaces
|
|
||||||
- returns a table with string keys, using net interfaces as a base:
|
|
||||||
{eth0 carrier}, {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 string keys: {ssid}, {mode}, {chan}, {rate},
|
|
||||||
{link}, {linp} (link quality in percent) and {sign} (signal level)
|
|
||||||
|
|
||||||
vicious.widgets.wifiiw
|
|
||||||
- similar to vicious.widgets.wifi, but uses iw instead of iwconfig
|
|
||||||
- provides wireless information for a requested interface
|
|
||||||
- takes the network interface as an argument, i.e. "wlan0"
|
|
||||||
- returns a table with string keys: {ssid}, {mode}, {chan}, {rate},
|
|
||||||
{freq}, {linp} (link quality in percent), {txpw} (tx power) and {sign} (signal level)
|
|
||||||
|
|
||||||
vicious.widgets.mbox
|
|
||||||
- provides the subject of last e-mail in a mbox file
|
|
||||||
- takes the full path to the mbox as an argument, or a table with
|
|
||||||
1st field as path, 2nd as maximum length and 3rd (optional) as
|
|
||||||
widget name - if 3rd field is present scrolling will be used (note: the
|
|
||||||
path will be escaped so special variables like ~ will not work, use
|
|
||||||
os.getenv("HOME").."mail" instead to access environment variables)
|
|
||||||
- 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 the number of new and unread messages in Maildir
|
|
||||||
structures/directories
|
|
||||||
- takes a table with full paths to Maildir structures 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
|
|
||||||
- takes an (optional) argument, if it's a number subject will be
|
|
||||||
truncated, if a table, with 1st field as maximum length and 2nd
|
|
||||||
the widget name (i.e. "gmailwidget"), scrolling will be used
|
|
||||||
- keeps login information in the ~/.netrc file, example:
|
|
||||||
machine mail.google.com login user password pass
|
|
||||||
- returns a table with string keys: {count} and {subject}
|
|
||||||
- to be able to use this widget, make sure in your Gmail account
|
|
||||||
you disabled "two step verification" (https://support.google.com/accounts/answer/1064203)
|
|
||||||
and then "allowed access to your account for less secure apps" (https://www.google.com/settings/security/lesssecureapps)
|
|
||||||
|
|
||||||
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.pkg
|
|
||||||
- provides number of pending updates on UNIX systems
|
|
||||||
- takes the distribution name as an argument, i.e. "Arch"
|
|
||||||
- returns 1st value as the count of available updates
|
|
||||||
|
|
||||||
vicious.widgets.mpd
|
|
||||||
- provides Music Player Daemon information
|
|
||||||
- takes a table as an argument, 1st field should be the password (or
|
|
||||||
nil), 2nd the hostname (or nil) and 3rd port (or nil) - if no
|
|
||||||
argument is provided connection attempt will be made to localhost
|
|
||||||
port 6600 with no password
|
|
||||||
- returns a table with string keys: {volume}, {state}, {Artist},
|
|
||||||
{Title}, {Album}, {Genre} and optionally {Name} and {file}
|
|
||||||
|
|
||||||
vicious.widgets.volume
|
|
||||||
- provides volume levels and state of requested ALSA mixers
|
|
||||||
- takes the ALSA mixer control as an argument, i.e. "Master",
|
|
||||||
optionally append the card ID or other options, i.e. "PCM -c 0"
|
|
||||||
- returns 1st value as the volume level and 2nd as the mute state 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 string keys: {city}, {wind}, {windmph},
|
|
||||||
{windkmh}, {sky}, {weather}, {tempf}, {tempc}, {humid}, {dewf},
|
|
||||||
{dewc}, {press}
|
|
||||||
|
|
||||||
vicious.widgets.date
|
|
||||||
- provides access to os.date, with optional time formatting provided
|
|
||||||
as the format string - using regular date sequences
|
|
||||||
- takes optional time offset, in seconds, as an argument for example
|
|
||||||
to calculate time zone differences, otherwise current time is
|
|
||||||
formatted
|
|
||||||
- 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).
|
|
||||||
|
|
||||||
Before writing a widget type you should check if there is already one
|
|
||||||
in the contrib directory of Vicious. The contrib directory contains
|
|
||||||
extra widgets you can use. Some are for less common hardware, and
|
|
||||||
other were contributed by Vicious users. The contrib directory also
|
|
||||||
holds widget types that were obsoleted or rewritten. Contrib widgets
|
|
||||||
will not be imported by init unless you explicitly enable it, or load
|
|
||||||
them in your rc.lua.
|
|
||||||
|
|
||||||
Rudi Siegel, a FreeBSD user, published his FreeBSD branch. If you are
|
|
||||||
also a BSD user you can find his work here:
|
|
||||||
|
|
||||||
- https://bitbucket.org/mutluyum/vicious_bsd/
|
|
||||||
|
|
||||||
Some users would like to avoid writing new modules. For them Vicious
|
|
||||||
kept the old Wicked functionality, possibility to register their own
|
|
||||||
functions as widget types. By providing them as the second argument to
|
|
||||||
vicious.register. Your function can accept "format" and "warg"
|
|
||||||
arguments, just like workers.
|
|
||||||
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
Security
|
|
||||||
--------
|
|
||||||
At the moment only one widget type (Gmail) requires auth. information
|
|
||||||
in order to get to the data. In the future there could be more, and
|
|
||||||
you should give some thought to the issue of protecting your data. The
|
|
||||||
Gmail widget type by default stores login information in the ~/.netrc
|
|
||||||
file, and you are advised to make sure that file is only readable by
|
|
||||||
the owner. Other than that we can not force all users to conform to
|
|
||||||
one standard, one way of keeping it secure, like in some keyring.
|
|
||||||
|
|
||||||
First let's clear why we simply don't encrypt the login information
|
|
||||||
and store it in ciphertext. By exposing the algorithm anyone can
|
|
||||||
reverse the encryption steps. Some claim even that's better than
|
|
||||||
plaintext but it's just security trough obscurity.
|
|
||||||
|
|
||||||
Here are some ideas actually worth your time. Users that have KDE (or
|
|
||||||
parts of it) installed could store their login information into the
|
|
||||||
Kwallet service and request it via DBus from the widget type. It can
|
|
||||||
be done with tools like "dbus-send" and "qdbus". The Gnome keyring
|
|
||||||
should support the same, so those with parts of Gnome installed could
|
|
||||||
use that keyring.
|
|
||||||
|
|
||||||
Users of GnuPG (and its agent) could consider encrypting the netrc
|
|
||||||
file with their GPG key. Trough the GPG Passphrase Agent they could
|
|
||||||
then decrypt the file transparently while their session is active.
|
|
||||||
|
|
||||||
|
|
||||||
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 = wibox.widget.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 = wibox.widget.textbox()
|
|
||||||
vicious.cache(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 = wibox.widget.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 = wibox.widget.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({ type = "linear", from = { 0, 0 }, to = { 0, 10 },
|
|
||||||
stops = {{ 0, "#AECF96" }, { 0.5, "#88A175" }, { 1, "#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({ type = "linear", from = { 0, 0 }, to = { 50, 0 },
|
|
||||||
stops = { { 0, "#FF5656" }, { 0.5, "#88A175" }, { 1, "#AECF96" }})
|
|
||||||
vicious.cache(vicious.widgets.cpu)
|
|
||||||
vicious.register(cpuwidget, vicious.widgets.cpu, "$1", 3)
|
|
||||||
|
|
||||||
- updated every 3 seconds, feeds the graph with total usage
|
|
||||||
percentage of all CPUs/cores and enable caching of this widget
|
|
||||||
type
|
|
||||||
|
|
||||||
|
|
||||||
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 pango markup can be inserted into the format string.
|
|
||||||
|
|
||||||
The format function will get the widget as its first argument, table
|
|
||||||
with the values otherwise inserted into the format string as its
|
|
||||||
second argument, and will return the text/data to be used for the
|
|
||||||
widget.
|
|
||||||
|
|
||||||
Example
|
|
||||||
mpdwidget = wibox.widget.textbox()
|
|
||||||
vicious.register(mpdwidget, vicious.widgets.mpd,
|
|
||||||
function (widget, args)
|
|
||||||
if args["{state}"] == "Stop" then return ""
|
|
||||||
else return '<span color="white">MPD:</span> '..
|
|
||||||
args["{Artist}"]..' - '.. args["{Title}"]
|
|
||||||
end
|
|
||||||
end)
|
|
||||||
|
|
||||||
- hides the mpd widget when no song is playing, updated every 2
|
|
||||||
seconds (the default interval)
|
|
||||||
|
|
||||||
Example
|
|
||||||
uptimewidget = wibox.widget.textbox()
|
|
||||||
vicious.register(uptimewidget, vicious.widgets.uptime,
|
|
||||||
function (widget, args)
|
|
||||||
return string.format("Uptime: %2dd %02d:%02d ", args[1], args[2], args[3])
|
|
||||||
end, 61)
|
|
||||||
|
|
||||||
- uses string.format for padding uptime values to a minimum amount
|
|
||||||
of digits, updated every 61 seconds
|
|
||||||
|
|
||||||
When it comes to padding it is also useful to mention how a widget can
|
|
||||||
be configured to have a fixed width. You can set a fixed width on your
|
|
||||||
textbox widgets by changing their .width field (by default width is
|
|
||||||
automatically adapted to text width).
|
|
||||||
|
|
||||||
Example
|
|
||||||
uptimewidget = wibox.widget.textbox()
|
|
||||||
uptimewidget:set_align("right")
|
|
||||||
vicious.register(uptimewidget, vicious.widgets.uptime, "$1 $2:$3", 61)
|
|
||||||
uptimewidget = wibox.layout.constraint(uptimewidget, "exact", 50, nil)
|
|
||||||
|
|
||||||
- forces a fixed width of 50px to the uptime widget, and aligns its
|
|
||||||
text to the right
|
|
||||||
|
|
||||||
Another use case are stacked graphs (aka multigraphs) which Vicious
|
|
||||||
does not handle on its own at the moment, as it's hard to pass on
|
|
||||||
color index arguments elegantly. But they are not unusable, far from
|
|
||||||
it.
|
|
||||||
|
|
||||||
Example
|
|
||||||
ctext = wibox.widget.textbox()
|
|
||||||
cgraph = awful.widget.graph()
|
|
||||||
cgraph:set_width(100):set_height(20)
|
|
||||||
cgraph:set_stack(true):set_max_value(100)
|
|
||||||
cgraph:set_background_color("#494B4F")
|
|
||||||
cgraph:set_stack_colors({ "#FF5656", "#88A175", "#AECF96" })
|
|
||||||
vicious.register(ctext, vicious.widgets.cpu,
|
|
||||||
function (widget, args)
|
|
||||||
cgraph:add_value(args[2], 1) -- Core 1, color 1
|
|
||||||
cgraph:add_value(args[3], 2) -- Core 2, color 2
|
|
||||||
cgraph:add_value(args[4], 3) -- Core 3, color 3
|
|
||||||
end, 3)
|
|
||||||
|
|
||||||
- enables graph stacking/multigraph and plots usage of all three CPU
|
|
||||||
cores on a single graph, the textbox "ctext" is just an empty
|
|
||||||
placeholder, graph is updated every 3 seconds
|
|
||||||
|
|
||||||
A lot of users are not happy with default symbols used in volume,
|
|
||||||
battery, cpufreq and other widget types. You can use your own symbols
|
|
||||||
without any need to modify modules.
|
|
||||||
|
|
||||||
volumewidget = wibox.widget.textbox()
|
|
||||||
vicious.register(volumewidget, vicious.widgets.volume,
|
|
||||||
function(widget, args)
|
|
||||||
local label = { ["♫"] = "O", ["♩"] = "M" }
|
|
||||||
return "Volume: " .. args[1] .. "% State: " .. label[args[2]]
|
|
||||||
end, 2, "PCM")
|
|
||||||
|
|
||||||
- uses a custom table map to modify symbols representing the mixer
|
|
||||||
state; on or off/mute
|
|
||||||
|
|
||||||
|
|
||||||
Other
|
|
||||||
-----
|
|
||||||
Read "awesome" manual pages:
|
|
||||||
|
|
||||||
- awesome(1) awesomerc(5)
|
|
||||||
|
|
||||||
Awesome widgets explained:
|
|
||||||
|
|
||||||
- http://awesome.naquadah.org/wiki/Widgets_in_awesome
|
|
||||||
|
|
||||||
Example "awesome" configuration:
|
|
||||||
|
|
||||||
- http://git.sysphere.org/awesome-configs/
|
|
||||||
|
|
||||||
|
|
||||||
Authors
|
|
||||||
-------
|
|
||||||
Wicked written by:
|
|
||||||
- Lucas de Vries <lucas glacicle.com>
|
|
||||||
|
|
||||||
Vicious written by:
|
|
||||||
- Adrian C. (anrxc) <anrxc sysphere.org>
|
|
||||||
|
|
||||||
Vicious major contributors:
|
|
||||||
- Benedikt Sauer <filmor gmail.com>
|
|
||||||
- Greg D. <jabbas jabbas.pl>
|
|
||||||
- Henning Glawe <glaweh debian.org>
|
|
||||||
- Rémy C. <shikamaru mandriva.org>
|
|
||||||
- Hiltjo Posthuma <hiltjo codemadness.org>
|
|
||||||
- Hagen Schink <troja84 googlemail.com>
|
|
||||||
- Jörg Thalheim <jthalheim gmail.com>
|
|
||||||
- Arvydas Sidorenko <asido4 gmail.com>
|
|
||||||
- Dodo The Last <dodo.the.last gmail.com>
|
|
||||||
- ...
|
|
||||||
- Consult git log for a complete list of contributors
|
|
||||||
Loading…
Reference in New Issue