Removed submodule and added the raw files.
This commit is contained in:
parent
9da8ea9542
commit
6397c554c3
96 changed files with 8176 additions and 0 deletions
37
.config/awesome/vicious/docs/source/caching.rst
Normal file
37
.config/awesome/vicious/docs/source/caching.rst
Normal 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.
|
||||
1
.config/awesome/vicious/docs/source/changelog.rst
Symbolic link
1
.config/awesome/vicious/docs/source/changelog.rst
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
../../CHANGELOG.rst
|
||||
37
.config/awesome/vicious/docs/source/conf.py
Normal file
37
.config/awesome/vicious/docs/source/conf.py
Normal 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 = []
|
||||
248
.config/awesome/vicious/docs/source/contrib.rst
Normal file
248
.config/awesome/vicious/docs/source/contrib.rst
Normal 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" } })
|
||||
1
.config/awesome/vicious/docs/source/contributing.rst
Symbolic link
1
.config/awesome/vicious/docs/source/contributing.rst
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
../../CONTRIBUTING.rst
|
||||
89
.config/awesome/vicious/docs/source/copying.rst
Normal file
89
.config/awesome/vicious/docs/source/copying.rst
Normal 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
|
||||
22
.config/awesome/vicious/docs/source/custom.rst
Normal file
22
.config/awesome/vicious/docs/source/custom.rst
Normal 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.
|
||||
97
.config/awesome/vicious/docs/source/examples.rst
Normal file
97
.config/awesome/vicious/docs/source/examples.rst
Normal 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)
|
||||
137
.config/awesome/vicious/docs/source/format.rst
Normal file
137
.config/awesome/vicious/docs/source/format.rst
Normal 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)))
|
||||
50
.config/awesome/vicious/docs/source/index.rst
Normal file
50
.config/awesome/vicious/docs/source/index.rst
Normal 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/
|
||||
27
.config/awesome/vicious/docs/source/security.rst
Normal file
27
.config/awesome/vicious/docs/source/security.rst
Normal 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.
|
||||
162
.config/awesome/vicious/docs/source/usage-awesome.rst
Normal file
162
.config/awesome/vicious/docs/source/usage-awesome.rst
Normal 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
|
||||
15
.config/awesome/vicious/docs/source/usage-lua.rst
Normal file
15
.config/awesome/vicious/docs/source/usage-lua.rst
Normal 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/
|
||||
528
.config/awesome/vicious/docs/source/widgets.rst
Normal file
528
.config/awesome/vicious/docs/source/widgets.rst
Normal 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue