249 lines
7.7 KiB
ReStructuredText
249 lines
7.7 KiB
ReStructuredText
Contrib Widget Types
|
|
====================
|
|
|
|
Contrib libraries, or widget types, are extra snippets of code you can use.
|
|
Some are for less common hardware, and other were contributed by Vicious users.
|
|
The contrib directory also holds widget types that were obsoleted or rewritten.
|
|
Contrib widgets will not be imported by init unless you explicitly enable it,
|
|
or load them in your ``rc.lua``.
|
|
|
|
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``: Uemperature of requested graphics device
|
|
* ``$6``: Urequency of GPU core
|
|
* ``$7``: Uemory 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" } })
|