[docs] Move widget type API from README

This commit is contained in:
Nguyễn Gia Phong 2020-09-09 10:34:51 +07:00
parent 901e03f39f
commit 1840d0b10d
3 changed files with 505 additions and 432 deletions

432
README.md
View File

@ -13,438 +13,6 @@ Lua libraries, but may depend on additional system utilities (see widget
description).
## <a name="widgets"></a>Widget types
Widget types consist of worker functions that take two arguments `format` and
`warg` (in that order), which were previously passed to `vicious.register`, and
return a table of values to be formatted by `format`.
### vicious.widgets.bat
Provides state, charge, and remaining time for a requested battery.
Supported platforms: GNU/Linux (require `sysfs`), FreeBSD (require `acpiconf`), OpenBSD (no extra requirements).
* `warg` (from now on will be called *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)](https://linux.die.net/man/3/strftime)
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` and you have to disable
[two step verification](https://support.google.com/accounts/answer/1064203).
[Allow access for less secure apps](https://www.google.com/settings/security/lesssecureapps)
afterwards.
**BE AWARE THAT 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:
```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 and port in that order. `nil`
fields will be fallen back to default (`localhost:6600` without password).
* 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}`, `${Album}`,
`${Genre}` and optionally `${Name}` and `${file}`.
### 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)](https://linux.die.net/man/1/amixer),
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)
## <a name="custom-widget"></a>Custom widget types
Use any of the existing widget types as a starting point for your

View File

@ -20,6 +20,7 @@ Table of Contents
usage-lua
usage-awesome
widgets
caching
security
copying

504
docs/source/widgets.rst Normal file
View File

@ -0,0 +1,504 @@
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 ``vicious.register``,
and return a table of values to be formatted by ``format``.
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).
* ``warg`` (from now on will be called *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`` and you have to disable
`two step verification`_. `Allow access for less secure apps`_ afterwards.
.. 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 and port in that order.
``nil`` fields will be fallen back to default
(``localhost:6600`` without password).
* 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}``,
``${Album}``, ``${Genre}`` and optionally ``${Name}`` and ``${file}``.
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
.. _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