Removed submodule and added the raw files.

This commit is contained in:
Johannes Findeisen 2026-11-19 19:37:32 +01:00
commit 6397c554c3
96 changed files with 8176 additions and 0 deletions

View file

@ -0,0 +1,37 @@
.. _caching:
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, etc.
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.

View file

@ -0,0 +1 @@
../../CHANGELOG.rst

View file

@ -0,0 +1,37 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options.
# For a full list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# Project information
project = 'Vicious'
copyright = '2020-2024, vicious-widgets'
author = 'vicious-widgets'
# The full version, including alpha/beta/rc tags
release = '2.7.1'
# Add any Sphinx extension module names here, as strings.
# They can be extensions coming with Sphinx (named 'sphinx.ext.*')
# or your custom ones.
extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.luadomain']
extlinks = {'github': ('https://github.com/%s', '@%s')}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# Options for HTML output
html_theme = 'sphinx_rtd_theme'
html_show_copyright = False
# Add any paths that contain custom static files (such as style sheets)
# here, relative to this directory. They are copied after the builtin
# static files, so a file named "default.css" will overwrite the builtin
# "default.css".
html_static_path = []

View file

@ -0,0 +1,248 @@
Contrib Widget Types
====================
Contrib libraries, or widget types, are extra snippets of code you can use.
Some are for less common hardware, and others 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``.
Usage within Awesome
--------------------
To use contrib widgets uncomment the line that loads them in ``init.lua``.
Or you can load them in your rc.lua after you require Vicious:
.. code-block:: lua
local vicious = require"vicious"
vicious.contrib = require"vicious.contrib"
Widget Types
------------
Most widget types consist of worker functions that take the ``format`` argument
given to :lua:func:`vicious.register` as the first argument,
``warg`` as the second, and return a table of values to insert in
the format string. But we have not insisted on this coding style in contrib.
So widgets like PulseAudio have emerged that are different. These widgets
could also depend on Lua libraries that are not distributed with the
core Lua distribution. Ease of installation and use does not necessarily
have to apply to contributed widgets.
vicious.contrib.ac
^^^^^^^^^^^^^^^^^^
Provide status about the power supply (AC).
Supported platforms: GNU/Linux, requiring ``sysfs``.
* Argument: the AC device, i.e ``"AC"`` or ``"ACAD"``. The device is linked
under ``/sys/class/power_supply/`` and should have a file called ``online``.
* Returns ``{"On"}`` if AC is connected, else ``{"Off"}``.
If AC doesn't exist, returns ``{"N/A"}``.
vicious.contrib.ati
^^^^^^^^^^^^^^^^^^^
Provides various info about ATI GPU status.
Supported platforms: GNU/Linux, requiring ``sysfs``.
* Argument: card ID, e.g. ``"card0"`` (and where possible,
uses ``debugfs`` to gather data on radeon power management)
* Returns a table with string keys: ``${method}``, ``${dpm_state}``,
``${dpm_perf_level}``, ``${profile}``, ``${engine_clock mhz}``,
``${engine_clock khz}``, ``${memory_clock mhz}``, ``${memory_clock khz}``,
``${voltage v}``, ``${voltage mv}``
vicious.contrib.batpmu
^^^^^^^^^^^^^^^^^^^^^^
vicious.contrib.batproc
^^^^^^^^^^^^^^^^^^^^^^^
vicious.contrib.btc
^^^^^^^^^^^^^^^^^^^
Provides current Bitcoin price in any currency by
[code](https://en.wikipedia.org/wiki/ISO_4217).
Platform independent, although requiring ``curl`` and either
[lua-cjson](https://github.com/mpx/lua-cjson/) or
[luajson](https://github.com/harningt/luajson/).
* Argument: currency code, e.g. ``"usd"``, ``"rub"`` and other.
Default to ``"usd"``.
* Returns a table with string key ``${price}``.
vicious.contrib.buildbot
^^^^^^^^^^^^^^^^^^^^^^^^
Provides last build status for configured buildbot builders
(http://trac.buildbot.net/).
Supported platforms: platform independent, though requiring Lua JSON parser
[luajson](https://github.com/harningt/luajson/).
Returns build status in the format:
``[<builderName>.<currentBuildNumber>.<lastSuccessfulBuildNumber>]``.
If ``<currentBuildNumber>`` is the same as ``<lastSuccessfulBuildNumber>``
only one number is displayed. ``<buildNumber>`` colors:
red---failed, green---successful, yellow---in progress.
vicious.contrib.countfiles
^^^^^^^^^^^^^^^^^^^^^^^^^^
vicious.contrib.cmus
^^^^^^^^^^^^^^^^^^^^
.. note::
This widget type has been promoted to :ref:`widgets`.
Provides cmus player information using ``cmus-remote``.
Supported platforms: platform independent.
* Argument: a table whose first field is the socket including host (or nil).
* Returns a table with string keys: ``${status}``, ``${artist}``, ``${title}``,
``${duration}``, ``${file}``, ``${continue}``, ``${shuffle}``, ``${repeat}``.
vicious.contrib.dio
^^^^^^^^^^^^^^^^^^^
Provides I/O statistics for requested storage devices.
* Argument: the disk as an argument, i.e. ``"sda"``, or a specific
partition, i.e. ``"sda/sda2"``
* Returns a table with string keys: ``${total_s}``, ``${total_kb}``,
``${total_mb}``, ``${read_s}``, ``${read_kb}``, ``${read_mb}``,
``${write_s}``, ``${write_kb}``, ``${write_mb}`` and ``${sched}``
vicious.contrib.mpc
^^^^^^^^^^^^^^^^^^^
vicious.contrib.netcfg
^^^^^^^^^^^^^^^^^^^^^^
vicious.contrib.net
^^^^^^^^^^^^^^^^^^^
vicious.contrib.openweather
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Provides weather information for a requested city from OpenWeatherMap (OWM)
* Argument: a table containing the fields ``city_id`` with the OWM city ID, e.g.
``"2643743"`` and ``app_id`` with the the OWM app ID, e.g
``"4c57f0c88d9844630327623633ce269cf826ab99"``
* Returns a table with string keys: ``${city}``, ``${humid}``, ``${press}``,
``${sky}``, ``${sunrise}``, ``${sunset}``, ``${temp c}``, ``${temp max c}``,
``${temp min c}``, ``${weather}``, ``${wind aim}``, ``${wind deg}``,
``${wind kmh}`` and ``${wind mps}``,
vicious.contrib.nvinf
^^^^^^^^^^^^^^^^^^^^^
Provides GPU utilization, core temperature, clock frequency information about
Nvidia GPU from nvidia-settings
Supported Platforms: platform independent
* Argument (optional): card ID as an argument, e.g. ``"1"``, default to ID 0
* Returns an array containing:
* ``$1``: Usage of GPU core
* ``$2``: Usage of GPU memory
* ``$3``: Usage of video engine
* ``$4``: Usage of PCIe bandwidth
* ``$5``: Temperature of requested graphics device
* ``$6``: Frequency of GPU core
* ``$7``: Memory transfer rate
vicious.contrib.nvsmi
^^^^^^^^^^^^^^^^^^^^^
Provides (very basic) information about Nvidia GPU status from SMI
Supported platforms: platform independent
* Argument (optional): card ID as an argument, e.g. ``"1"``, default to ID 0
* Returns an array containing temperature of requested graphics device
vicious.contrib.ossvol
^^^^^^^^^^^^^^^^^^^^^^
vicious.contrib.pop
^^^^^^^^^^^^^^^^^^^
vicious.contrib.pulse
^^^^^^^^^^^^^^^^^^^^^
Provides volume levels of requested pulseaudio sinks and functions to
manipulate them
* Argument (optional): name of a sink as an optional argument. A number will
be interpret as an index, if no argument is given, it will take the
first-best. To get a list of available sinks run
``pacmd list-sinks | grep 'name:'``.
* Returns an array whose only element is the volume level
vicious.contrib.pulse.add(percent[, sink])
""""""""""""""""""""""""""""""""""""""""""
* ``percent`` is the percentage to increment or decrement the volume
from its current value
* Returns the exit status of ``pacmd``
vicious.contrib.pulse.toggle([sink])
""""""""""""""""""""""""""""""""""""
* Toggles mute state
* Returns the exit status of ``pacmd``
vicious.contrib.rss
^^^^^^^^^^^^^^^^^^^
vicious.contrib.sensors
^^^^^^^^^^^^^^^^^^^^^^^
vicious.contrib.wpa
^^^^^^^^^^^^^^^^^^^
Provides information about the wifi status.
Supported Platforms: platform independent, requiring ``wpa_cli``.
* Argument: the interface, e.g. ``"wlan0"`` or ``"wlan1"``
* Returns a table with string keys:
``${ssid}``, ``${qual}``, ``${ip}``, ``${bssid}``
Usage Examples
--------------
PulseAudio Widget
^^^^^^^^^^^^^^^^^
.. code-block:: lua
vol = wibox.widget.textbox()
local sink = "alsa_output.pci-0000_00_1b.0.analog-stereo"
vicious.register(vol, vicious.contrib.pulse, " $1%", 2, sink)
vol:buttons(awful.util.table.join(
awful.button({}, 1, function () awful.util.spawn("pavucontrol") end),
awful.button({}, 4, function () vicious.contrib.pulse.add(5, sink) end),
awful.button({}, 5, function () vicious.contrib.pulse.add(-5, sink) end)))
Buildbot Widget
^^^^^^^^^^^^^^^
.. code-block:: lua
buildbotwidget = wibox.widget.textbox()
vicious.register(
buildbotwidget, vicious.contrib.buildbot, "$1,", 3600,
{ { builder="coverage", url="http://buildbot.buildbot.net" },
{ builder="tarball-slave", url="http://buildbot.buildbot.net" } })

View file

@ -0,0 +1 @@
../../CONTRIBUTING.rst

View file

@ -0,0 +1,89 @@
License and Credits
===================
Wicked was written by:
* Lucas de Vries <lucas glacicle.com>
Vicious was originally written by:
* Adrian C. (anrxc) <anrxc sysphere.org>.
Vicious is released under `GNU GPLv2+`_ and is currently maintained by:
* :github:`Jörg Thalheim <Mic92>` <joerg thalheim.io>
* :github:`mutlusun` (especially the FreeBSD port)
* :github:`Daniel Hahler <blueyed>` <github thequod.de>
* :github:`Nguyễn Gia Phong <McSinyx>` <cnx loang.net>
* :github:`Enric Morales <kiike>` <geekingaround enric.me>
(especially the OpenBSD port)
Over the years, Vicious has also received various patches and improvements
from the following contributors, listed in alphabetic order:
* 0x5b <dragen15051 gmail.com>
* Adam Lee <adam8157 gmail.com>
* Alexander Koch <lynix47 gmail.com>
* Amir Mohammad Saied <amirsaied gmail.com>
* Andrea Scarpino <me andreascarpino.it>
* Andreas Geisenhainer <psycorama datenhalde.de>
* Andrew Merenbach <andrew merenbach.com>
* Andrzej Bieniek <andyhelp gmail.com>
* Arseniy Terekhin <senyai gmail.com>
* Arthur Axel 'fREW' Schmidt <git frew.co>
* Arvydas Sidorenko <asido4 gmail.com>
* Benedikt Sauer <filmor gmail.com>
* Beniamin Kalinowski <beniamin.kalinowski gmail.com>
* Benoît Zugmeyer <bzugmeyer gmail.com>
* blastmaster <blastmaster tuxcode.org>
* Brandon Hartshorn <brandonhartshorn gmail.com>
* Cássio Ávila <cassioavila protonmail.com>
* Constantin Piber <cp.piber gmail.com>
* crondog <patches crondog.com>
* David Udelson <dru5 cornell.edu>
* Dodo The Last <dodo.the.last gmail.com>
* :github:`Elmeri Niemelä <elmeriniemela>`
* Elric Milon <whirm gmx.com>
* :github:`feltcat <feltcat>`
* getzze <getzze gmail.com>
* Greg D. <jabbas jabbas.pl>
* Hagen Schink <troja84 googlemail.com>
* Henning Glawe <glaweh debian.org>
* Hiltjo Posthuma <hiltjo codemadness.org>
* :github:`James Reed <supplantr>`
* Jay Kamat <jaygkamat gmail.com>
* Jeremy <jeremy.sainvil gmaill.com>
* jinleileiking <jinleileiking gmail.com>
* joe di castro <joe joedicastro.com>
* Joerg Jaspert <joerg debian.org>
* Jonathan McCrohan <jmccrohan gmail.com>
* :github:`Juan Carlos Menonita <JuanKman94>`
* Juergen Descher <jhdl gmx.net>
* Julian Volodia <julianvolodia gmail.com>
* Keith Hughitt <keith.hughitt gmail.com>
* Lorenzo Gaggini <lg lgaggini.net>
* :github:`lumpsoid <lumpsoid>`
* Lyderic Lefever <lyderic.lefever gmail.com>
* Martin Striz <striz raynet.cz>
* Martin Ueding <dev martin-ueding.de>
* Mellich <mellich gmx.net>
* Michael Kressibucher <mkressibucher hotmail.com>
* Michael Unterkalmsteiner <miciu gmx.de>
* niko <nikomomo gmail.com>
* Noah Tilton <code tilton.co>
* Normal Ra <normalrawr gmail.com>
* Perry Hargrave <perry.hargrave gmail.com>
* Rémy CLOUARD <shikamaru shikamaru.fr>
* Roberto Clapis <empijei gmail.com>
* Sébastien Luttringer <seblu seblu.net>
* Shadowmourne G <s10e live.com>
* starenka <starenka0 gmail.com>
* Suseika <wlasowegor gmail.com>
* Uli Schlachter <psychon znc.in>
* Wtfcoder <matt mattfreeman.co.uk>
* Xaver Hellauer <xaver hellauer.bayern>
* zhrtz <apaterson scramble.io>
and many others.
.. _GNU GPLv2+: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html

View file

@ -0,0 +1,22 @@
.. _custom-wtype:
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 others
were contributed by Vicious users. Most of the contrib widgets are obsolete.
Contrib widgets will not be imported by init unless you explicitly enable it,
or load them in your ``rc.lua``.
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
:lua:func:`vicious.register`. Your function can accept ``format`` and ``warg``
arguments, just like workers.

View file

@ -0,0 +1,97 @@
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
-----------
Update every 2 seconds (the default interval),
use standard date sequences as the format string:
.. code-block:: lua
datewidget = wibox.widget.textbox()
vicious.register(datewidget, vicious.widgets.date, "%b %d, %R")
Memory Widget
-------------
Update every 13 seconds, append ``MiB`` to 2nd and 3rd returned values
and enables caching.
.. code-block:: lua
memwidget = wibox.widget.textbox()
vicious.cache(vicious.widgets.mem)
vicious.register(memwidget, vicious.widgets.mem, "$1 ($2MiB/$3MiB)", 13)
HDD Temperature Widget
----------------------
Update every 19 seconds, request the temperature level of ``/dev/sda`` and
append *°C* to the returned value. Since the listening port is not provided,
default one is used.
.. code-block:: lua
hddtempwidget = wibox.widget.textbox()
vicious.register(hddtempwidget, vicious.widgets.hddtemp, "${/dev/sda} °C", 19)
Mbox Widget
-----------
Updated every 5 seconds, provide full path to the mbox as argument:
.. code-block:: lua
mboxwidget = wibox.widget.textbox()
vicious.register(mboxwidget, vicious.widgets.mbox, "$1", 5,
"/home/user/mail/Inbox")
Battery Widget
--------------
Update every 61 seconds, request the current battery charge level
and displays a progressbar, provides ``BAT0`` as battery ID:
.. code-block:: lua
batwidget = wibox.widget.progressbar()
-- Create wibox with batwidget
batbox = wibox.container.margin(
wibox.widget{ { max_value = 1, widget = batwidget,
border_width = 0.5, border_color = "#000000",
color = { type = "linear",
from = { 0, 0 },
to = { 0, 30 },
stops = { { 0, "#AECF96" },
{ 1, "#FF5656" } } } },
forced_height = 10, forced_width = 8,
direction = 'east', color = beautiful.fg_widget,
layout = wibox.container.rotate },
1, 1, 3, 3)
-- Register battery widget
vicious.register(batwidget, vicious.widgets.bat, "$2", 61, "BAT0")
CPU Usage Widget
----------------
Update every 3 seconds, feed the graph with total usage percentage
of all CPUs/cores:
.. code-block:: lua
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.register(cpuwidget, vicious.widgets.cpu, "$1", 3)

View file

@ -0,0 +1,137 @@
.. _format-func:
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.
Examples
--------
Hide mpd widget when no song is playing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: lua
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> %s - %s'):format(
args["{Artist}"], args["{Title}"])
end
end)
Use string.format for padding
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: lua
uptimewidget = wibox.widget.textbox()
vicious.register(uptimewidget, vicious.widgets.uptime,
function (widget, args)
return ("Uptime: %02d %02d:%02d "):format(
args[1], args[2], args[3])
end, 61)
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). The following code forces
a fixed width of 50 px to the uptime widget, and aligns its text to the right:
.. code-block:: lua
uptimewidget = wibox.widget.textbox()
uptimewidget.width, uptimewidget.align = 50, "right"
vicious.register(uptimewidget, vicious.widgets.uptime, "$1 $2:$3", 61)
Stacked graph
^^^^^^^^^^^^^
Stacked graphs are handled specially by Vicious: ``format`` functions passed
to the corresponding widget types must return an array instead of a string.
.. code-block:: lua
cpugraph = wibox.widget.graph()
cpugraph:set_stack(true)
cpugraph:set_stack_colors{ "red", "yellow", "green", "blue" }
vicious.register(cpugraph, vicious.widgets.cpu,
function (widget, args)
return { args[2], args[3], args[4], args[5] }
end, 3)
The snipet above enables graph stacking/multigraph and plots usage of all four
CPU cores on a single graph.
Substitute widget types' symbols
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are not happy with default symbols used in volume, battery, cpufreq and
other widget types, use your own symbols without any need to modify modules.
The following example uses a custom table map to modify symbols representing
the mixer state: on or off/mute.
.. code-block:: lua
volumewidget = wibox.widget.textbox()
vicious.register(volumewidget, vicious.widgets.volume,
function (widget, args)
local label = { ["🔉"] = "O", ["🔈"] = "M" }
return ("Volume: %d%% State: %s"):format(
args[1], label[args[2]])
end, 2, "PCM")
.. _call-example:
Get data from the widget
^^^^^^^^^^^^^^^^^^^^^^^^
:lua:func:`vicious.call` could be useful for naughty notification and scripts:
.. code-block:: lua
mybattery = wibox.widget.textbox()
vicious.register(mybattery, vicious.widgets.bat, "$2%", 17, "0")
mybattery:buttons(awful.util.table.join(awful.button(
{}, 1,
function ()
naughty.notify{ title = "Battery indicator",
text = vicious.call(vicious.widgets.bat,
"Remaining time: $3", "0") }
end)))
Format functions can be used as well:
.. code-block:: lua
mybattery:buttons(awful.util.table.join(awful.button(
{}, 1,
function ()
naughty.notify{
title = "Battery indicator",
text = vicious.call(
vicious.widgets.bat,
function (widget, args)
return ("%s: %10sh\n%s: %14d%%\n%s: %12dW"):format(
"Remaining time", args[3],
"Wear level", args[4],
"Present rate", args[5])
end, "0") }
end)))

View file

@ -0,0 +1,50 @@
Welcome to Vicious' documentation!
==================================
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.
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. Vicious doesn't depend on any third party Lua_
library, but may depend on additional system utilities.
Table of Contents
-----------------
.. toctree::
:maxdepth: 2
usage-lua
usage-awesome
examples
widgets
contrib
custom
format
caching
security
contributing
copying
changelog
See Also
--------
* Manual pages: `awesome(1)`_, `awesomerc(5)`_
* `Awesome declarative layout system`_
* `My first awesome`_
* `Example awesome configuration`_ (outdated)
.. _awesome window manager: https://awesomewm.org
.. _Lua: https://www.lua.org
.. _awesome(1): https://awesomewm.org/doc/manpages/awesome.1.html
.. _awesomerc(5): https://awesomewm.org/doc/manpages/awesomerc.5.html
.. _Awesome declarative layout system:
https://awesomewm.org/apidoc/documentation/03-declarative-layout.md.html
.. _My first awesome:
https://awesomewm.org/doc/api/documentation/07-my-first-awesome.md.html
.. _Example awesome configuration: http://git.sysphere.org/awesome-configs/

View file

@ -0,0 +1,27 @@
Security Notes
==============
At the moment only one widget type (Gmail) requires
authentication 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 through 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. Through the GPG Passphrase Agent they could then
decrypt the file transparently while their session is active.

View file

@ -0,0 +1,162 @@
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``)::
git clone https://github.com/vicious-widgets/vicious.git
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``:
.. code-block:: lua
local vicious = require("vicious")
vicious.register
----------------
Once you create a widget (a textbox, graph or a progressbar),
call ``vicious.register`` to register it with Vicious:
.. lua:function:: vicious.register(widget, wtype, format, interval, warg)
Register a widget.
:param widget: awesome widget created from
``awful.widget`` or ``wibox.widget``
:param wtype: either of
* Vicious widget type: any widget type
:ref:`provided by Vicious <widgets>` or customly defined.
* ``function``: custom function from your own
awesome configuration can be registered as widget types
(see :ref:`custom-wtype`).
:param format: either of
* string: ``$key`` will be replaced by respective value in the table
``t`` returned by the widget type, i.e. use ``$1``, ``$2``, etc.
to retrieve data from an integer-indexed table (a.k.a. array);
``${foo bar}`` will be substituted by ``t["{foo bar}"]``.
* ``function (widget, args)`` can be used to manipulate data returned
by the widget type (see :ref:`format-func`).
:param interval: number of seconds between updates of the widget
(default: 2). See :ref:`caching` for more information.
:param warg: arguments to be passed to widget types, e.g. the battery ID.
``vicious.register`` alone is not much different from awful.widget.watch_,
which has been added to Awesome since version 4.0. However, Vicious offers
more advanced control of widgets' behavior by providing the following functions.
vicious.unregister
------------------
.. lua:function:: vicious.unregister(widget, keep)
Unregister a widget.
:param widget: awesome widget created from
``awful.widget`` or ``wibox.widget``
:param keep: if true suspend ``widget`` and wait for activation
:type keep: bool
vicious.suspend
---------------
.. lua:function:: vicious.suspend()
Suspend all widgets.
See `example automation script`_ for the "laptop-mode-tools" start-stop module.
vicious.activate
----------------
.. lua:function:: vicious.activate([widget])
Restart suspended widget(s).
:param widget: if provided only that widget will be activated
vicious.cache
-------------
.. lua:function:: vicious.cache(wtype)
Enable caching of values returned by a widget type.
vicious.force
--------------
.. lua:function:: vicious.force(wtable)
Force update of given widgets.
:param wtable: table of one or more widgets to be updated
vicious.call[_async]
--------------------
.. lua:function:: vicious.call(wtype, format, warg)
Get formatted data from a synchronous widget type
(:ref:`example <call-example>`).
:param wtype: either of
* Vicious widget type: any synchronous widget type
:ref:`provided by Vicious <widgets>` or customly defined.
* ``function``: custom function from your own
awesome configuration can be registered as widget types
(see :ref:`custom-wtype`).
:param format: either of
* string: ``$key`` will be replaced by respective value in the table
``t`` returned by the widget type, i.e. use ``$1``, ``$2``, etc.
to retrieve data from an integer-indexed table (a.k.a. array);
``${foo bar}`` will be substituted by ``t["{foo bar}"]``.
* ``function (widget, args)`` can be used to manipulate data returned
by the widget type (see :ref:`format-func`).
:param warg: arguments to be passed to the widget type, e.g. the battery ID.
:return: ``nil`` if the widget type is asynchronous,
otherwise the formatted data from with widget type.
.. lua:function:: vicious.call_async(wtype, format, warg, callback)
Get formatted data from an asynchronous widget type.
:param wtype: any asynchronous widget type
:ref:`provided by Vicious <widgets>` or customly defined.
:param format: either of
* string: ``$key`` will be replaced by respective value in the table
``t`` returned by the widget type, i.e. use ``$1``, ``$2``, etc.
to retrieve data from an integer-indexed table (a.k.a. array);
``${foo bar}`` will be substituted by ``t["{foo bar}"]``.
* ``function (widget, args)`` can be used to manipulate data returned
by the widget type (see :ref:`format-func`).
:param warg: arguments to be passed to the widget type.
:param callback: function taking the formatted data from with widget type.
If the given widget type happens to be synchronous,
``nil`` will be passed to ``callback``.
.. _awesome: https://awesomewm.org/
.. _awful.widget.watch:
https://awesomewm.org/doc/api/classes/awful.widget.watch.html
.. _example automation script:
http://sysphere.org/~anrxc/local/sources/lmt-vicious.sh

View file

@ -0,0 +1,15 @@
Usage as a Lua Library
======================
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
(e.g. Ion, WMII). It is compatible with Lua 5.1 and above.
.. code-block:: lua
> widgets = require("vicious.widgets.init")
> print(widgets.volume(nil, "Master")[1])
100
.. _Lua: https://www.lua.org/

View file

@ -0,0 +1,528 @@
.. _widgets:
Officially Supported Widget Types
=================================
Widget types consist of worker functions that take two arguments
``format`` and ``warg`` (in that order), which were previously
passed to :lua:func:`vicious.register`, and return a table of values
to be formatted by ``format``.
vicious.widgets.amdgpu
----------------------
Provides GPU and VRAM usage statistics for AMD graphics cards.
Supported platforms: GNU/Linux (require ``sysfs``)
* ``warg`` (from now on will be called *argument*): card ID, e.g. ``"card0"``
* Returns a table with string keys: ``${gpu_usage}``, ``${mem_usage}``
vicious.widgets.bat
-------------------
Provides state, charge, and remaining time for a requested battery.
Supported platforms: GNU/Linux (require ``sysfs``),
FreeBSD (require ``acpiconf``) and OpenBSD (no extra requirements).
* Argument:
* On GNU/Linux: battery ID, e.g. ``"BAT0"``
* On FreeBSD (optional): battery ID, e.g. ``"batt"`` or ``"0"``
* On OpenBSD (optional): ``bat`` followed by battery index,
e.g. ``"bat0"`` or ``"bat1"`` on systems with more than one battery
* Returns an array (integer-indexed table) consisting of:
* ``$1``: State of requested battery
* ``$2``: Charge level in percent
* ``$3``: Remaining (charging or discharging) time
* ``$4``: Wear level in percent
* ``$5``: Current (dis)charge rate in Watt
vicious.contrib.cmus
--------------------
Provides cmus player information using ``cmus-remote``.
Supported platforms: platform independent.
* Argument: a table whose first field is the socket including host (or nil).
* Returns a table with string keys: ``${status}``, ``${artist}``, ``${title}``,
``${duration}``, ``${file}``, ``${continue}``, ``${shuffle}``, ``${repeat}``.
vicious.widgets.cpu
-------------------
Provides CPU usage for all available CPUs/cores. Since this widget type give
CPU utilization between two consecutive calls, it is recommended to enable
caching if it is used to register multiple widgets (#71).
Supported platforms: GNU/Linux, FreeBSD, OpenBSD.
On FreeBSD and Linux returns an array containing:
* ``$1``: usage of all CPUs/cores
* ``$2``, ``$3``, etc. are respectively the usage of 1st, 2nd, etc. CPU/core
On OpenBSD returns an array containing:
* ``$1``: usage of all CPUs/cores
vicious.widgets.cpufreq
-----------------------
Provides freq, voltage and governor info for a requested CPU.
Supported platforms: GNU/Linux, FreeBSD.
* Argument: CPU ID, e.g. ``"cpu0"`` on GNU/Linux, ``"0"`` on FreeBSD
* Returns an array containing:
* ``$1``: Frequency in MHz
* ``$2``: Frequency in GHz
* ``$3``: Voltage in mV
* ``$4``: Voltage in V
* ``$5``: Governor state
* On FreeBSD: only the first two are supported
(other values will always be ``"N/A"``)
vicious.widgets.cpuinf
----------------------
Provides speed and cache information for all available CPUs/cores.
Supported platforms: GNU/Linux.
Returns a table whose keys using CPU ID as a base, e.g. ``${cpu0 mhz}``,
``${cpu0 ghz}``, ``${cpu0 kb}``, ``${cpu0 mb}``, ``${cpu1 mhz}``, etc.
vicious.widgets.date
--------------------
Provides access to Lua's ``os.date``, with optional settings for time format
and time offset.
Supported platforms: platform independent.
* ``format`` (optional): a `strftime(3)`_ format specification string
(format functions are not supported). If not provided, use the prefered
representation for the current locale.
* Argument (optional): time offset in seconds, e.g. for different a time zone.
If not provided, current time is used.
* Returns the output of ``os.date`` formatted by ``format`` *string*.
vicious.widgets.dio
-------------------
Provides I/O statistics for all available storage devices.
Supported platforms: GNU/Linux.
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}``,
``${sda iotime_ms}``, ``${sda iotime_s}``, ``${sdb1 total_s}``, etc.
vicious.widget.fanspeed
-----------------------
Provides fanspeed information for specified fans.
Supported platforms: FreeBSD.
* Argument: full ``sysctl`` string to one or multiple entries,
e.g. ``"dev.acpi_ibm.0.fan_speed"``
* Returns speed of specified fan in RPM, ``"N/A"`` on error
(probably wrong string)
vicious.widgets.fs
------------------
Provides usage of disk space.
Supported platforms: platform independent.
* Argument (optional): if true includes remote filesystems, otherwise fallback
to default, where only local filesystems are included.
* Returns a table with string keys, using mount points as a base,
e.g. ``${/ size_mb}``, ``${/ size_gb}``, ``${/ used_mb}``, ``${/ used_gb}``,
``${/ used_p}``, ``${/ avail_mb}``, ``${/ avail_gb}``, ``${/ avail_p}``,
``${/home size_mb}``, etc.
mb and gb refer to mebibyte and gibibyte respectively.
vicious.widgets.gmail
---------------------
Provides count of new and subject of last e-mail on Gmail.
Supported platform: platform independent, requiring ``curl``.
This widget expects login information in your ``~/.netrc`` file, e.g.
``machine mail.google.com login user password pass``. Use your `app
password`_ if you can, or disable `two step verification`_
and `allow access for less secure apps`_.
.. caution::
Making these settings is a security risk!
* Arguments (optional): either a number or a table
* If it is a number, subject will be truncated.
* If it is a table whose first field is the maximum length and second field
is the widget name (e.g. ``"gmailwidget"``), scrolling will be used.
* Returns a table with string keys: ``${count}`` and ``${subject}``
vicious.widgets.hddtemp
-----------------------
Provides hard drive temperatures using the hddtemp daemon.
Supported platforms: GNU/Linux, requiring ``hddtemp`` and ``curl``.
* Argument (optional): ``hddtemp`` listening port (default: 7634)
* Returns a table with string keys, using hard drives as a base, e.g.
``${/dev/sda}`` and ``${/dev/sdc}``.
vicious.widgets.hwmontemp
-------------------------
Provides name-based access to hwmon devices via sysfs.
Supported platforms: GNU/Linux
* Argument: an array with sensor name and input number
(optional, falling back to ``1``), e.g. ``{"radeon", 2}``
* Returns a table with just the temperature value: ``$1``
* Usage example:
.. code-block:: lua
gputemp = wibox.widget.textbox()
vicious.register(gputemp, vicious.widgets.hwmontemp, " $1°C", 5, {"radeon"})
vicious.widgets.mbox
--------------------
Provides the subject of last e-mail in a mbox file.
Supported platforms: platform independent.
* Argument: either a string or a table:
* A string representing the full path to the mbox, or
* Array of the form ``{path, maximum_length[, widget_name]}``.
If the widget name is provided, scrolling will be used.
* Note: the path will be escaped so special variables like ``~`` will not
work, use ``os.getenv`` instead to access environment variables.
* Returns an array whose first value is the subject of the last e-mail.
vicious.widgets.mboxc
---------------------
Provides the count of total, old and new messages in mbox files.
Supported platforms: platform independent.
* Argument: an array full paths to mbox files.
* Returns an array containing:
* ``$1``: Total number of messages
* ``$2``: Number of old messages
* ``$3``: Number of new messages
vicious.widgets.mdir
--------------------
Provides the number of unread messages in Maildir structures/directories.
Supported platforms: platform independent.
* Argument: an array with full paths to Maildir structures.
* Returns an array containing:
* ``$1``: Number of new messages
* ``$2``: Number of *old* messages lacking the *Seen* flag
vicious.widgets.mem
-------------------
Provides RAM and Swap usage statistics.
Supported platforms: GNU/Linux, FreeBSD.
Returns (per platform):
* GNU/Linux: an array consisting of:
* ``$1``: Memory usage in percent
* ``$2``: Memory usage in MiB
* ``$3``: Total system memory in MiB
* ``$4``: Free memory in MiB
* ``$5``: Swap usage in percent
* ``$6``: Swap usage in MiB
* ``$7``: Total system swap in MiB
* ``$8``: Free swap in MiB
* ``$9``: Memory usage with buffers and cache, in MiB
* FreeBSD: an array including:
* ``$1``: Memory usage in percent
* ``$2``: Memory usage in MiB
* ``$3``: Total system memory in MiB
* ``$4``: Free memory in MiB
* ``$5``: Swap usage in percent
* ``$6``: Swap usage in MiB
* ``$7``: Total system swap in MiB
* ``$8``: Free swap in MiB
* ``$9``: Wired memory in percent
* ``$10``: Wired memory in MiB
* ``$11``: Unfreeable memory (basically active+inactive+wired) in percent
* ``$12``: Unfreeable memory in MiB
vicious.widgets.mpd
-------------------
Provides Music Player Daemon information.
Supported platforms: platform independent (required tools: ``curl``).
* Argument: an array including password, hostname, port and separator in that
order, or a table with the previously mentioned fields.
``nil`` fields will be fallen back to default
(``localhost:6600`` without password and ``", "`` as a separator).
* Returns a table with string keys: ``${volume}``, ``${bitrate}``,
``${elapsed}`` (in seconds), ``${duration}`` (in seconds),
``${Elapsed}`` (formatted as [hh:]mm:ss),
``${Duration}`` (formatted as [hh:]mm:ss), ``${Progress}`` (in percentage),
``${random}``, ``${repeat}``, ``${state}``, ``${Artist}``, ``${Title}``,
``${Artists}`` (all artists concatenated with the configured separator),
``${Genres}`` (all genres concatenated with the configured separator),
``${Album}``, ``${Genre}`` and optionally ``${Name}`` and ``${file}``.
In addition, some common mpd commands are available as functions:
``playpause``, ``play``, ``pause``, ``stop``, ``next``, ``previous``.
Arguments are of the same form as above, and no value is returned,
e.g. ``vicious.widgets.mpd.playpause()``.
vicious.widgets.net
-------------------
Provides state and usage statistics of network interfaces.
Supported platforms: GNU/Linux, FreeBSD.
* Argument (FreeBSD only): desired interface, e.g. ``"wlan0"``
* Returns (per platform):
* GNU/Linux: a table with string keys, using net interfaces as a base,
e.g. ``${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.
* FreeBSD: a table with string keys: ``${carrier}``, ``${rx_b}``, ``${tx_b}``,
``${rx_kb}``, ``${tx_kb}``, ``${rx_mb}``, ``${tx_mb}``, ``${rx_gb}``,
``${tx_gb}``, ``${down_b}``, ``${up_b}``, ``${down_kb}``, ``${up_kb}``,
``${down_mb}``, ``${up_mb}``, ``${down_gb}``, ``${up_gb}``.
vicious.widgets.notmuch
-----------------------
Provides a message count according to an arbitrary Notmuch query.
Supported platforms: platform independent.
Argument: the query that is passed to Notmuch. For instance:
``tag:inbox AND tag:unread`` returns the number of unread messages with
tag "inbox".
Returns a table with string keys containing:
* ``${count}``: the count of messages that match the query
vicious.widgets.org
-------------------
Provides agenda statistics for Emacs org-mode.
Supported platforms: platform independent.
* Argument: an array of full paths to agenda files,
which will be parsed as arguments.
* Returns an array consisting of
* ``$1``: Number of tasks you forgot to do
* ``$2``: Number of tasks for today
* ``$3``: Number of tasks for the next 3 days
* ``$4``: Number of tasks to do in the week
vicious.widgets.os
------------------
Provides operating system information.
Supported platforms: platform independent.
Returns an array containing:
* ``$1``: Operating system in use
* ``$2``: Release version
* ``$3``: Username
* ``$4``: Hostname
* ``$5``: Available system entropy
* ``$6``: Available entropy in percent
vicious.widgets.pkg
-------------------
Provides number of pending updates on UNIX systems. Be aware that some package
managers need to update their local databases (as root) before showing the
correct number of updates.
Supported platforms: platform independent, although it requires Awesome
``awful.spawn`` library for non-blocking spawning.
* Argument: distribution name, e.g. ``"Arch"``, ``"Arch C"``, ``"Arch S"``,
``"Debian"``, ``"Ubuntu"``, ``"Fedora"``, ``"FreeBSD"``, ``"Mandriva"``.
* Returns an array including:
* ``$1``: Number of available updates
* ``$2``: Packages available for update
vicious.widgets.raid
--------------------
Provides state information for a requested RAID array.
Supported platforms: GNU/Linux.
* Argument: the RAID array ID.
* Returns an array containing:
* ``$1``: Number of assigned devices
* ``$2``: Number of active devices
vicious.widgets.thermal
-----------------------
Provides temperature levels of several thermal zones.
Supported platforms: GNU/Linux, FreeBSD.
* Argument (per platform):
* GNU/Linux: either a string - the thermal zone, e.g. ``"thermal_zone0"``,
or a table of the form ``{thermal_zone, data_source[, input_file]}``.
Available ``data_source``'s and corresponding default ``input_file``
are given in the table below. For instance, if ``"thermal_zone0"``
is passed, temperature would be read from
``/sys/class/thermal/thermal_zone0/temp``. This widget type is confusing
and ugly but it is kept for backward compatibility.
* FreeBSD: either a full ``sysctl`` path to a thermal zone, e.g.
``"hw.acpi.thermal.tz0.temperature"``, or a table with multiple paths.
* Returns (per platform):
* GNU/Linux: an array whose first value is the requested temperature.
* FreeBSD: a table whose keys are provided paths thermal zones.
=============== ======================== ======================
``data_source`` Path Default ``input_file``
=============== ======================== ======================
``"sys"`` /sys/class/thermal/ ``"temp"``
``"core"`` /sys/devices/platform/ ``"temp2_input"``
``"hwmon"`` /sys/class/hwmon/ ``"temp1_input"``
``"proc"`` /proc/acpi/thermal_zone/ ``"temperature"``
=============== ======================== ======================
vicious.widgets.uptime
----------------------
Provides system uptime and load information.
Supported platforms: GNU/Linux, FreeBSD.
Returns an array containing:
* ``$1``: Uptime in days
* ``$2``: Uptime in hours
* ``$3``: Uptime in minutes
* ``$4``: Load average in the past minute
* ``$5``: Load average in the past 5 minutes
* ``$6``: Load average in the past 15 minutes
vicious.widgets.volume
----------------------
Provides volume levels and state of requested mixers.
Supported platforms: GNU/Linux (requiring ``amixer``), FreeBSD.
* Argument (per platform):
* GNU/Linux: either a string containing the ALSA mixer control
(e.g. ``"Master"``) or a table including command line arguments
to be passed to `amixer(1)`_, e.g. ``{"PCM", "-c", "0"}``
or ``{"Master", "-D", "pulse"}``
* FreeBSD: the mixer control, e.g. ``"vol"``
* Returns an array consisting of (per platform):
* GNU/Linux: ``$1`` as the volume level and ``$2`` as the mute state of
the requested control
* FreeBSD: ``$1`` as the volume level of the *left* channel, ``$2`` as the
volume level of the *right* channel and ``$3`` as the mute state of the
desired control
vicious.widgets.weather
-----------------------
Provides weather information for a requested station.
Supported platforms: any having Awesome and ``curl`` installed.
* Argument: the ICAO station code, e.g. ``"LDRI"``
* Returns a table with string keys: ``${city}``, ``${wind}``, ``${windmph}``,
``${windkmh}``, ``${sky}``, ``${weather}``, ``${tempf}``, ``${tempc}``,
``${humid}``, ``${dewf}``, ``${dewc}`` and ``${press}``, ``${when}``
vicious.widgets.wifi
--------------------
Provides wireless information for a requested interface.
Supported platforms: GNU/Linux.
* Argument: the network interface, e.g. ``"wlan0"``
* Returns a table with string keys: ``${ssid}``, ``${mode}``,
``${chan}``, ``${rate}`` (Mb/s), ``${freq}`` (MHz),
``${txpw}`` (transmission power, in dBm), ``${sign}`` (signal level),
``${link}`` and ``${linp}`` (link quality per 70 and per cent)
vicious.widgets.wifiiw
----------------------
Provides wireless information for a requested interface (similar to
vicious.widgets.wifi, but uses ``iw`` instead of ``iwconfig``).
Supported platforms: GNU/Linux.
* Argument: the network interface, e.g. ``"wlan0"``
* Returns a table with string keys: ``${bssid}``, ``${ssid}``,
``${mode}``, ``${chan}``, ``${rate}`` (Mb/s), ``${freq}`` (MHz),
``${linp}`` (link quality in percent),
``${txpw}`` (transmission power, in dBm)
and ``${sign}`` (signal level, in dBm)
.. _strftime(3): https://linux.die.net/man/3/strftime
.. _app password: https://support.google.com/accounts/answer/185833?hl=en
.. _two step verification: https://support.google.com/accounts/answer/1064203
.. _allow access for less secure apps:
https://www.google.com/settings/security/lesssecureapps
.. _amixer(1): https://linux.die.net/man/1/amixer