mirror of
https://github.com/vicious-widgets/vicious
synced 2023-12-14 07:13:07 +01:00
[docs] Include contrib widget types
This commit is contained in:
parent
34699a57bb
commit
656235b88b
3 changed files with 246 additions and 212 deletions
|
|
@ -1,212 +0,0 @@
|
|||
# Contrib
|
||||
|
||||
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:
|
||||
|
||||
```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 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 `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
|
||||
|
||||
* Argument: OpenWeatherMap city ID, e.g. `"1275339"`
|
||||
* Returns a table with string keys: `${city}`, `${wind deg}`, `${wind aim}`,
|
||||
`${wind kmh}`, `${wind mps}`, `${sky}`, `${weather}`, `${temp c}`,
|
||||
`${humid}` and `${press}`
|
||||
|
||||
### 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
|
||||
|
||||
### Pulse Audio widget:
|
||||
|
||||
```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
|
||||
|
||||
```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"}})
|
||||
```
|
||||
245
docs/source/contrib.rst
Normal file
245
docs/source/contrib.rst
Normal file
|
|
@ -0,0 +1,245 @@
|
|||
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
|
||||
|
||||
* Argument: OpenWeatherMap city ID, e.g. ``"1275339"``
|
||||
* Returns a table with string keys: ``${city}``, ``${wind deg}``,
|
||||
``${wind aim}``, ``${wind kmh}``, ``${wind mps}``, ``${sky}``,
|
||||
``${weather}``, ``${temp c}``, ``${humid}`` and ``${press}``
|
||||
|
||||
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" } })
|
||||
|
|
@ -22,6 +22,7 @@ Table of Contents
|
|||
usage-awesome
|
||||
examples
|
||||
widgets
|
||||
contrib
|
||||
custom
|
||||
format
|
||||
caching
|
||||
|
|
|
|||
Loading…
Reference in a new issue