Compare commits
35 Commits
Author | SHA1 | Date |
---|---|---|
Nguyễn Gia Phong | 6600353758 | |
Cássio Ávila | 969d94255b | |
Nguyễn Gia Phong | 9435bfdf6d | |
Rémy CLOUARD | 47ae72ee80 | |
feltcat | 6a633cb4bb | |
Nguyễn Gia Phong | afb6fffafc | |
Nguyễn Gia Phong | 4d3025400e | |
Constantin Piber | 09163271d6 | |
Constantin Piber | 830d624f35 | |
Nguyễn Gia Phong | 81f8a80774 | |
Constantin Piber | 51707f3917 | |
Nguyễn Gia Phong | b20f68bdb7 | |
Nguyễn Gia Phong | 150864a76d | |
Arseniy Terekhin | eada06667d | |
MArpogaus | edfd51215e | |
Nguyễn Gia Phong | 4ae9245246 | |
Nguyễn Gia Phong | 9df7237755 | |
Nguyễn Gia Phong | 82cffa8ea9 | |
Nguyễn Gia Phong | 071cc61a58 | |
Nguyễn Gia Phong | 365e754d8d | |
Nguyễn Gia Phong | d35eeb2ed3 | |
Nguyễn Gia Phong | 897ebe97b7 | |
Nguyễn Gia Phong | 5f87644d28 | |
Nguyễn Gia Phong | 7701418b47 | |
Nguyễn Gia Phong | 1840d0b10d | |
Nguyễn Gia Phong | 901e03f39f | |
Nguyễn Gia Phong | be0eb4870d | |
Nguyễn Gia Phong | 2a8f987b22 | |
Nguyễn Gia Phong | b7d08fc84b | |
Nguyễn Gia Phong | f452b5780f | |
Alexander Koch | 5e0cb0c84a | |
Nguyễn Gia Phong | a2f83bf9d6 | |
Elmeri Niemelä | bfc0922f6e | |
Nguyễn Gia Phong | 3bd7b59b2c | |
Nguyễn Gia Phong | fa6b4e68c8 |
|
@ -0,0 +1,9 @@
|
||||||
|
image: alpine/edge
|
||||||
|
packages:
|
||||||
|
- luacheck
|
||||||
|
sources:
|
||||||
|
- https://github.com/vicious-widgets/vicious
|
||||||
|
tasks:
|
||||||
|
- check: |
|
||||||
|
cd vicious
|
||||||
|
luacheck --config=tools/luacheckrc .
|
|
@ -1 +1,2 @@
|
||||||
*~
|
*~
|
||||||
|
build/
|
||||||
|
|
|
@ -0,0 +1,178 @@
|
||||||
|
Changelog
|
||||||
|
=========
|
||||||
|
|
||||||
|
Changes in 2.7.0
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Added fields ``${Artists}`` and ``${Genres}`` for the mpd widget type.
|
||||||
|
|
||||||
|
Changes in 2.6.0
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Added AMD GPU widget type for Linux.
|
||||||
|
|
||||||
|
Fixed typos in contrib widgets documentation.
|
||||||
|
|
||||||
|
Changes in 2.5.1
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Fixed:
|
||||||
|
|
||||||
|
- Escaping of % in ``helpers.format``, which affects mpd widget ``${Progress}``
|
||||||
|
- Possible deadlock of when ``update`` widgets
|
||||||
|
- [contrib.openweather] New API compatibility, which requires an API key
|
||||||
|
- [gmail] Authentication documentation
|
||||||
|
|
||||||
|
Added:
|
||||||
|
|
||||||
|
- [mpd] Support for sending arbitrary commands
|
||||||
|
- [contrib.openweather] Various new return values
|
||||||
|
|
||||||
|
Changes in 2.5.0
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Fixed:
|
||||||
|
|
||||||
|
- ``vicious.call`` freezing awesome when used with asynchronous widget types
|
||||||
|
|
||||||
|
Added:
|
||||||
|
|
||||||
|
- ``vicious.call_async`` asynchronous analogous to ``vicious.call``
|
||||||
|
|
||||||
|
Moved:
|
||||||
|
|
||||||
|
- Most of the documentation in READMEs to ``docs/``
|
||||||
|
- ``Changes.md`` to ``CHANGELOG.rst``
|
||||||
|
- ``CONTRIBUTING.md`` to ``CONTRIBUTING.rst``
|
||||||
|
- Meta helpers to ``tools/``
|
||||||
|
|
||||||
|
Changes in 2.4.2
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Feature: [hwmontemp] Bring back sysfs path cache
|
||||||
|
|
||||||
|
Changes in 2.4.1
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Fixed:
|
||||||
|
|
||||||
|
- [pkg] Fallback the number of lines before packages listing to 0.
|
||||||
|
This fixes crashes on Arch, FreeBSD and Mandriva.
|
||||||
|
- [mdir] Remove trailing semicolon at the end of command.
|
||||||
|
|
||||||
|
Changes in 2.4.0
|
||||||
|
----------------
|
||||||
|
|
||||||
|
.. important::
|
||||||
|
|
||||||
|
``volume`` now uses 🔉 and 🔈 instead of ♫ and ♩ to show mute state.
|
||||||
|
This BREAKS backward compatibility if users substitute custom symbols
|
||||||
|
from these default.
|
||||||
|
|
||||||
|
Added:
|
||||||
|
|
||||||
|
- notmuch_all, cpu_freebsd widget types.
|
||||||
|
- [cmus_all] Promote to ``widgets/``.
|
||||||
|
- [wifiiw_linux] Expose BSSID.
|
||||||
|
- [wifi_linux] Expose frequency and transmission power.
|
||||||
|
- ``spawn`` as a fallback for ``awful.spawn`` in case Vicious is used as
|
||||||
|
a stand-alone library. This wrapper, however, does NOT provide the facilities
|
||||||
|
to asynchronously spawn new processes. It also lacks a few features such as
|
||||||
|
parsing ``stderr`` and returning PID.
|
||||||
|
- ``helpers.setasyncall`` to avoid writing redundant workers for asynchronous
|
||||||
|
widget types. Note that these workers are only needed in case Vicious is used
|
||||||
|
as a stand-alone library.
|
||||||
|
- ``helpers.setcall`` for registering functions as widget types.
|
||||||
|
- ``headergen`` script for automatic generation of copyright notices.
|
||||||
|
- ``templates`` for the ease of adding new widget types.
|
||||||
|
- ``CONTRIBUTING.md`` which guide contributors through the steps
|
||||||
|
of filing an issue or submitting a patch.
|
||||||
|
|
||||||
|
Fixed:
|
||||||
|
|
||||||
|
- Deprecate the use of ``io.popen`` in following widgets:
|
||||||
|
|
||||||
|
- wifi_linux, wifiiw_linux, hwmontemp_linux, hddtemp_linux
|
||||||
|
- bat_freebsd, mem_freebsd, net_freebsd, thermal_freebsd, uptime_freebsd,
|
||||||
|
- cpu_freebsd, cpufreq_freebsd, fanspeed_freebsd
|
||||||
|
- bat_openbsd
|
||||||
|
- volume, gmail, mdir, mpd, fs
|
||||||
|
|
||||||
|
- [mpd] Lua 5.3 compatibility (for real this time); also correct a typo
|
||||||
|
- [mbox] Update the deprecated ``string.gfind`` to ``string.gmatch``
|
||||||
|
- [pkg,weather,contrib/btc] Allow function call without Awesome
|
||||||
|
- [pkg] Use more updated front-ends for Debian/Ubuntu (apt) and Fedora (dnf)
|
||||||
|
- [os] Splitted os_all into os_linux and os_bsd (and refactored to async)
|
||||||
|
- Tweak ``.luacheckrc`` to suit functional style and soft-limit text width to 80
|
||||||
|
- Update copyright headers for libraries and widget types
|
||||||
|
|
||||||
|
Removed:
|
||||||
|
|
||||||
|
- ``helpers.sysctl`` and ``helpers.sysctl_table`` were removed in favour of
|
||||||
|
``helpers.sysctl_async``.
|
||||||
|
|
||||||
|
Changes in 2.3.3
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Feature: Add battery widget type for OpenBSD
|
||||||
|
|
||||||
|
Fixes:
|
||||||
|
|
||||||
|
- [mpd] Lua 5.3 compatibility
|
||||||
|
- [bat_freebsd] Update battery state symbols
|
||||||
|
|
||||||
|
Changes in 2.3.2
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Features:
|
||||||
|
|
||||||
|
- Support stacked graphs
|
||||||
|
- [hwmontemp_linux] Provide name-based access to hwmon sensors via sysfs
|
||||||
|
- [mpd_all] Expose more informations and format time in [hh:]mm:ss
|
||||||
|
|
||||||
|
Fixes:
|
||||||
|
|
||||||
|
- Improve defaults and mechanism for data caching
|
||||||
|
- Escape XML entities in results by default
|
||||||
|
- [weather_all] Update NOAA link and use Awesome asynchronous API
|
||||||
|
- [mem_linux] Use MemAvailable to calculate free amount
|
||||||
|
- [mem_freebsd] Correct calculation and switch to swapinfo for swap
|
||||||
|
- [bat_freebsd] Add critical charging state
|
||||||
|
- [fs_all] Fix shell quoting of option arguments
|
||||||
|
|
||||||
|
Moreover, ``.luacheckrc`` was added and ``README.md`` was refomatted
|
||||||
|
for the ease of development.
|
||||||
|
|
||||||
|
Changes in 2.3.1
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Fixes:
|
||||||
|
|
||||||
|
- widgets can be a function again (regression introduced in 2.3.0)
|
||||||
|
|
||||||
|
Changes in 2.3.0
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Features:
|
||||||
|
|
||||||
|
- add btc widget
|
||||||
|
- add cmus widget
|
||||||
|
- alsa mixer also accept multiple arguments
|
||||||
|
|
||||||
|
Fixes:
|
||||||
|
|
||||||
|
- pkg now uses non-blocking asynchronous api
|
||||||
|
|
||||||
|
Changes in 2.2.0
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Notable changes:
|
||||||
|
|
||||||
|
- moved development from git.sysphere.org/vicious to github.com/Mic92/vicious
|
||||||
|
- official freebsd support
|
||||||
|
- escape variables before passing to shell
|
||||||
|
- support for gear timers
|
||||||
|
- fix weather widget url
|
||||||
|
- add :lua:func:`vicious.call` method to obtain data outside of widgets
|
||||||
|
|
||||||
|
For older versions please see ``git log``.
|
|
@ -1,6 +1,8 @@
|
||||||
# How to contribute to Vicious
|
Contribution Guidelines
|
||||||
|
=======================
|
||||||
|
|
||||||
## Filing an Issue
|
Filing an Issue
|
||||||
|
---------------
|
||||||
|
|
||||||
* Ensure the bug was not already reported by searching GitHub Issues.
|
* Ensure the bug was not already reported by searching GitHub Issues.
|
||||||
* If you're unable to find an open issue addressing the problem,
|
* If you're unable to find an open issue addressing the problem,
|
||||||
|
@ -15,9 +17,11 @@ Please re-read your issue once again to avoid a couple of common mistakes
|
||||||
|
|
||||||
* Is the description of the issue itself sufficient?
|
* Is the description of the issue itself sufficient?
|
||||||
Make sure that it's obvious
|
Make sure that it's obvious
|
||||||
- What the problem is
|
|
||||||
- How it could be fixed
|
* What the problem is
|
||||||
- How your proposed solution would look like
|
* How it could be fixed
|
||||||
|
* How your proposed solution would look like
|
||||||
|
|
||||||
* Have you provide the versions of Vicious and related software?
|
* Have you provide the versions of Vicious and related software?
|
||||||
We would like to how you installed Vicious, which OS you're using,
|
We would like to how you installed Vicious, which OS you're using,
|
||||||
the version of the software or what kind of hardware you are trying
|
the version of the software or what kind of hardware you are trying
|
||||||
|
@ -34,85 +38,87 @@ Please re-read your issue once again to avoid a couple of common mistakes
|
||||||
Do not post features because they seem like a good idea.
|
Do not post features because they seem like a good idea.
|
||||||
If they're really useful, they'll be requested by someone who requires them.
|
If they're really useful, they'll be requested by someone who requires them.
|
||||||
|
|
||||||
## Requesting for Merging a Patch
|
Requesting for Merging a Patch
|
||||||
|
------------------------------
|
||||||
|
|
||||||
1. [Fork this repository](https://github.com/vicious-widgets/vicious/fork)
|
#. `Fork this repository`_
|
||||||
2. Check out the source code with:
|
#. Check out the source code with::
|
||||||
|
|
||||||
git clone git@github.com:YOUR_GITHUB_USERNAME/vicious.git
|
git clone git@github.com:YOUR_GITHUB_USERNAME/vicious
|
||||||
cd vicious
|
cd vicious
|
||||||
|
|
||||||
3. Start working on your patch. If you want to add a new widget type,
|
#. Start working on your patch. If you want to add a new widget type,
|
||||||
see the `templates` directory for a more detailed guide.
|
see the ``templates`` directory for a more detailed guide.
|
||||||
4. Have a look at `helpers.lua` and `spawn.lua` for possible helper functions.
|
#. Have a look at ``helpers.lua`` and ``spawn.lua``
|
||||||
5. Make sure your code follows the coding conventions below and check the code
|
for possible helper functions.
|
||||||
with `luacheck`. This *should fail* at first, but you can continually
|
#. Make sure your code follows the coding conventions below and check the code
|
||||||
re-run it until you're done.
|
with ``luacheck``. This *should fail* at first, but you can continually
|
||||||
|
re-run it until you're done::
|
||||||
|
|
||||||
luacheck --config .luacheckrc .
|
luacheck --config tools/luacheckrc .
|
||||||
|
|
||||||
6. Make sure your code works under all Lua versions claimed supported
|
#. Make sure your code works under all Lua versions claimed supported
|
||||||
by Vicious, namely 5.1, 5.2 and 5.3.
|
by Vicious, namely 5.1, 5.2 and 5.3.
|
||||||
7. Update the copyright notices of the files you modified. Vicious is
|
#. Update the copyright notices of the files you modified. Vicious is
|
||||||
collectively licensed under GPLv2+, and to protect the freedom of the users,
|
collectively licensed under GPLv2+, and to protect the freedom of the users,
|
||||||
copyright holders need to be properly documented.
|
copyright holders need to be properly documented.
|
||||||
8. Try to note your changes under `Changes.md`. If you find it is
|
#. Try to note your changes under ``CHANGELOG.rst``. If you find it is
|
||||||
difficult to phrase the changes, you can leave it for us.
|
difficult to phrase the changes, you can leave it for us.
|
||||||
9. [Add](https://git-scm.com/docs/git-add) the changes,
|
#. Add_ the changes, commit_ them and push_ the result, like this::
|
||||||
[commit](https://git-scm.com/docs/git-commit) them
|
|
||||||
and [push](https://git-scm.com/docs/git-push) the result, like this:
|
|
||||||
|
|
||||||
git add widgets/bar_baz.lua README.md
|
git add widgets/bar_baz.lua README.md
|
||||||
git commit -m '[bar_baz] Add widget type'
|
git commit -m '[bar_baz] Add widget type'
|
||||||
git add helpers.lua Changes.md
|
git add helpers.lua CHANGELOG.rst
|
||||||
git commit -m '[helpers] Fix foo'
|
git commit -m '[helpers] Fix foo'
|
||||||
git push
|
git push
|
||||||
|
|
||||||
10. Finally, [create a pull request](https://help.github.com/articles/creating-a-pull-request).
|
#. Finally, `create a pull request`_. We'll then review and merge it.
|
||||||
We'll then review and merge it.
|
|
||||||
|
|
||||||
In any case, thank you very much for your contributions!
|
In any case, thank you very much for your contributions!
|
||||||
|
|
||||||
## Coding Conventions
|
Coding Conventions
|
||||||
|
------------------
|
||||||
|
|
||||||
This section introduces a guideline for writing idiomatic, robust
|
This section introduces a guideline for writing idiomatic, robust
|
||||||
and future-proof widget type code.
|
and future-proof widget type code.
|
||||||
|
|
||||||
### Whitespace in Expressions and Statements
|
Whitespace in Expressions and Statements
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Avoid extraneous whitespace in the following situations:
|
Avoid extraneous whitespace in the following situations:
|
||||||
|
|
||||||
* Immediately inside parentheses or brackets. Braces, however, are exceptions
|
* Immediately inside parentheses or brackets. Braces, however, are exceptions
|
||||||
to this rule:
|
to this rule:
|
||||||
|
|
||||||
```lua
|
.. code-block:: lua
|
||||||
foo(bar[1], { baz = 2 }) -- yes
|
|
||||||
foo( bar[ 1 ], {baz = 2} ) -- no
|
foo(bar[1], { baz = 2 }) -- yes
|
||||||
```
|
foo( bar[ 1 ], {baz = 2} ) -- no
|
||||||
|
|
||||||
* Immediately before a comma, semicolon, or colon.
|
* Immediately before a comma, semicolon, or colon.
|
||||||
* Immediately before the open parenthesis, braces, quote, etc.
|
* Immediately before the open parenthesis, braces, quote, etc.
|
||||||
that starts the argument list of a function call; or the open bracket
|
that starts the argument list of a function call; or the open bracket
|
||||||
that starts an indexing. In other words, prefer these:
|
that starts an indexing. In other words, prefer these:
|
||||||
|
|
||||||
```lua
|
.. code-block:: lua
|
||||||
foo(bar, baz)
|
|
||||||
foo{ bar, baz }
|
foo(bar, baz)
|
||||||
foo"bar"
|
foo{ bar, baz }
|
||||||
foo[[bar]]
|
foo"bar"
|
||||||
foo[bar]
|
foo[[bar]]
|
||||||
```
|
foo[bar]
|
||||||
|
|
||||||
* Trailing at the end of line or (newline) at the end of file.
|
* Trailing at the end of line or (newline) at the end of file.
|
||||||
|
|
||||||
Always surround these binary operators with a single space on either side:
|
Always surround these binary operators with a single space on either side:
|
||||||
assignment (`=`), comparisons, Booleans (`and`, `or`, `not`).
|
assignment (``=``), comparisons, Booleans (``and``, ``or``, ``not``).
|
||||||
If operators with different priorities are used, consider adding whitespace
|
If operators with different priorities are used, consider adding whitespace
|
||||||
around the operators with the lowest priorities. Use your own judgment;
|
around the operators with the lowest priorities. Use your own judgment;
|
||||||
however, never use more than one space, and always have
|
however, never use more than one space, and always have
|
||||||
the same amount of whitespace on both sides of a binary operator.
|
the same amount of whitespace on both sides of a binary operator.
|
||||||
|
|
||||||
### Indentation
|
Indentation
|
||||||
|
^^^^^^^^^^^
|
||||||
|
|
||||||
Use 4 *spaces* per indentation level.
|
Use 4 *spaces* per indentation level.
|
||||||
|
|
||||||
|
@ -122,26 +128,26 @@ inside parentheses, brackets and braces, or using a hanging indent
|
||||||
non-whitespace character of the line, with subsequent lines being indented
|
non-whitespace character of the line, with subsequent lines being indented
|
||||||
until the closing parenthesis), e.g.
|
until the closing parenthesis), e.g.
|
||||||
|
|
||||||
```lua
|
.. code-block:: lua
|
||||||
-- Vertically aligned
|
|
||||||
long_function_call{ foo, bar,
|
|
||||||
baz }
|
|
||||||
|
|
||||||
-- Hanging indentation
|
-- Vertically aligned
|
||||||
long_function_call(
|
long_function_call{ foo, bar,
|
||||||
foo, bar
|
baz }
|
||||||
baz)
|
|
||||||
```
|
-- Hanging indentation
|
||||||
|
long_function_call(
|
||||||
|
foo, bar
|
||||||
|
baz)
|
||||||
|
|
||||||
The closing brace or bracket on multi-line constructs may either line up under
|
The closing brace or bracket on multi-line constructs may either line up under
|
||||||
the first character of the line that starts the construct, as in:
|
the first character of the line that starts the construct, as in:
|
||||||
|
|
||||||
```lua
|
.. code-block:: lua
|
||||||
long_function_call{
|
|
||||||
foo = 1, bar = 2,
|
long_function_call{
|
||||||
baz = 3,
|
foo = 1, bar = 2,
|
||||||
}
|
baz = 3,
|
||||||
```
|
}
|
||||||
|
|
||||||
In this case, and this case only, the trailing comma is acceptable
|
In this case, and this case only, the trailing comma is acceptable
|
||||||
to avoid diff noises when more values are added,
|
to avoid diff noises when more values are added,
|
||||||
|
@ -150,19 +156,21 @@ it's occasionally helpful to do so.
|
||||||
|
|
||||||
Trailing right parentheses, however, are not allowed.
|
Trailing right parentheses, however, are not allowed.
|
||||||
|
|
||||||
### Maximum Line Length
|
Maximum Line Length
|
||||||
|
^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
If possible, try to limit all *code* lines to a maximum
|
If possible, try to limit all *code* lines to a maximum
|
||||||
of 80 characters. In case you find some lines in your patch would be
|
of 80 characters. In case you find some lines in your patch would be
|
||||||
more readable exceeding this limit, feel free to discuss with us.
|
more readable exceeding this limit, feel free to discuss with us.
|
||||||
Comments and long strings need not to follow this restriction however.
|
Comments and long strings need not to follow this restriction however.
|
||||||
|
|
||||||
As one might have noticed, the syntactic sugars `f{<fields>}`
|
As one might have noticed, the syntactic sugars ``f{<fields>}``
|
||||||
(for `f({<fields>})`) and `f'<string>'` (or `f"<string>"`/`f[[<string>]]`,
|
(for ``f({<fields>})``) and ``f'<string>'``
|
||||||
for `f('<string>')`) are especially preferred to squeeze
|
(or ``f"<string>"``/``f[[<string>]]``, for ``f('<string>')``)
|
||||||
the line length to this limit.
|
are especially preferred to squeeze the line length to this limit.
|
||||||
|
|
||||||
### Blank Lines
|
Blank Lines
|
||||||
|
^^^^^^^^^^^
|
||||||
|
|
||||||
Surround function definitions with a single blank line. Extra blank lines
|
Surround function definitions with a single blank line. Extra blank lines
|
||||||
may be used (sparingly) to separate groups of related functions.
|
may be used (sparingly) to separate groups of related functions.
|
||||||
|
@ -170,12 +178,13 @@ Blank lines may be omitted between a bunch of related one-liners
|
||||||
(e.g. a set of dummy implementations).
|
(e.g. a set of dummy implementations).
|
||||||
Use blank lines in functions, sparingly, to indicate logical sections.
|
Use blank lines in functions, sparingly, to indicate logical sections.
|
||||||
|
|
||||||
### Requiring Libraries
|
Requiring Libraries
|
||||||
|
^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
All standard libraries should be localized before used
|
All standard libraries should be localized before used
|
||||||
for the matter of performance.
|
for the matter of performance.
|
||||||
|
|
||||||
`require`s should always be put at the top of the source file,
|
``require``'s should always be put at the top of the source file,
|
||||||
just after the copyright header, and before module globals and constants,
|
just after the copyright header, and before module globals and constants,
|
||||||
and grouped in the following order:
|
and grouped in the following order:
|
||||||
|
|
||||||
|
@ -185,50 +194,54 @@ and grouped in the following order:
|
||||||
|
|
||||||
For example,
|
For example,
|
||||||
|
|
||||||
```lua
|
.. code-block:: lua
|
||||||
local type = type
|
|
||||||
local table = { concat = table.concat, insert = table.insert }
|
|
||||||
|
|
||||||
local awful = require("awful")
|
local type = type
|
||||||
|
local table = { concat = table.concat, insert = table.insert }
|
||||||
|
|
||||||
local helpers = require("vicious.helpers")
|
local awful = require("awful")
|
||||||
```
|
|
||||||
|
|
||||||
### String Quotes
|
local helpers = require("vicious.helpers")
|
||||||
|
|
||||||
|
String Quotes
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
In Lua, single-quoted strings and double-quoted strings are the same,
|
In Lua, single-quoted strings and double-quoted strings are the same,
|
||||||
so the choice is totally up to you, but please be consistent within a module.
|
so the choice is totally up to you, but please be consistent within a module.
|
||||||
When a string contains single or double quote characters, however,
|
When a string contains single or double quote characters, however,
|
||||||
use the other one to avoid backslashes in the string. It improves readability:
|
use the other one to avoid backslashes in the string. It improves readability:
|
||||||
|
|
||||||
```lua
|
.. code-block:: lua
|
||||||
'"key": "value"' -- good
|
|
||||||
"\"key\": \"value\"" -- no good
|
'"key": "value"' -- good
|
||||||
```
|
"\"key\": \"value\"" -- no good
|
||||||
|
|
||||||
It is preferable to add a newline immediately after the opening long bracket:
|
It is preferable to add a newline immediately after the opening long bracket:
|
||||||
|
|
||||||
```lua
|
.. code-block:: lua
|
||||||
foo = [[
|
|
||||||
this is a really,
|
|
||||||
really,
|
|
||||||
really long text]]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Naming Conventions
|
foo = [[
|
||||||
|
this is a really,
|
||||||
|
really,
|
||||||
|
really long text]]
|
||||||
|
|
||||||
Avoid using the characters `l` (lowercase letter el), `O` (uppercase letter oh),
|
Naming Conventions
|
||||||
or `I` (uppercase letter eye) as single character variable names.
|
^^^^^^^^^^^^^^^^^^
|
||||||
In some fonts, these characters are indistinguishable from the 1's and 0's.
|
|
||||||
|
|
||||||
#### Constants
|
Avoid using the characters ``l`` (lowercase letter el),
|
||||||
|
``O`` (uppercase letter oh), or ``I`` (uppercase letter eye)
|
||||||
|
as single character variable names. In some fonts, these characters
|
||||||
|
are indistinguishable from the 1's and 0's.
|
||||||
|
|
||||||
|
Constants
|
||||||
|
"""""""""
|
||||||
|
|
||||||
Constants are usually defined on a module level
|
Constants are usually defined on a module level
|
||||||
and written in all capital letters with underscores separating words.
|
and written in all capital letters with underscores separating words.
|
||||||
Examples include `MAX_OVERFLOW` and `TOTAL`.
|
Examples include ``MAX_OVERFLOW`` and ``TOTAL``.
|
||||||
|
|
||||||
|
Function and Variable Names
|
||||||
#### Function and Variable Names
|
"""""""""""""""""""""""""""
|
||||||
|
|
||||||
Function names should be lowercase, with words separated by underscores
|
Function names should be lowercase, with words separated by underscores
|
||||||
as necessary to improve readability.
|
as necessary to improve readability.
|
||||||
|
@ -238,7 +251,8 @@ Variable names follow the same convention as function names.
|
||||||
When you find it difficult to give descriptive names,
|
When you find it difficult to give descriptive names,
|
||||||
use the functions and variable anonymously.
|
use the functions and variable anonymously.
|
||||||
|
|
||||||
### Performance Tips
|
Performance Tips
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Vicious is meant to be run as part of the Awesome window manager,
|
Vicious is meant to be run as part of the Awesome window manager,
|
||||||
thus any little overhead may defect the responsiveness of the UI.
|
thus any little overhead may defect the responsiveness of the UI.
|
||||||
|
@ -258,7 +272,8 @@ However, declare a variable only when you need it, to avoid declaring it
|
||||||
without an initial value (and therefore you seldom forget to initialize it).
|
without an initial value (and therefore you seldom forget to initialize it).
|
||||||
Moreover, you shorten the scope of the variable, which increases readability.
|
Moreover, you shorten the scope of the variable, which increases readability.
|
||||||
|
|
||||||
### Copyright Header
|
Copyright Header
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Vicious is released under the GNU GNU General Public License
|
Vicious is released under the GNU GNU General Public License
|
||||||
version 2 or later and each contributor holds the copyright
|
version 2 or later and each contributor holds the copyright
|
||||||
|
@ -266,27 +281,28 @@ on their contributions. To make this collective control effective,
|
||||||
each source file must include a notice of the following format
|
each source file must include a notice of the following format
|
||||||
denoting the name of all authors
|
denoting the name of all authors
|
||||||
|
|
||||||
```lua
|
.. code-block:: lua
|
||||||
-- <one line to give the program's name and a brief idea of what it does.>
|
|
||||||
-- Copyright (C) <year> <name of author> <<email that can be use for contact>>
|
|
||||||
--
|
|
||||||
-- This file is part of Vicious.
|
|
||||||
--
|
|
||||||
-- Vicious is free software: you can redistribute it and/or modify
|
|
||||||
-- it under the terms of the GNU General Public License as
|
|
||||||
-- published by the Free Software Foundation, either version 2 of the
|
|
||||||
-- License, or (at your option) any later version.
|
|
||||||
--
|
|
||||||
-- Vicious is distributed in the hope that it will be useful,
|
|
||||||
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
||||||
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
||||||
-- GNU General Public License for more details.
|
|
||||||
--
|
|
||||||
-- You should have received a copy of the GNU General Public License
|
|
||||||
-- along with Vicious. If not, see <https://www.gnu.org/licenses/>.
|
|
||||||
```
|
|
||||||
|
|
||||||
### Comments
|
-- <one line to give the program's name and a brief idea of what it does.>
|
||||||
|
-- Copyright (C) <year> <name of author> <<email that can be use for contact>>
|
||||||
|
--
|
||||||
|
-- This file is part of Vicious.
|
||||||
|
--
|
||||||
|
-- Vicious is free software: you can redistribute it and/or modify
|
||||||
|
-- it under the terms of the GNU General Public License as
|
||||||
|
-- published by the Free Software Foundation, either version 2 of the
|
||||||
|
-- License, or (at your option) any later version.
|
||||||
|
--
|
||||||
|
-- Vicious is distributed in the hope that it will be useful,
|
||||||
|
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||||
|
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
|
-- GNU General Public License for more details.
|
||||||
|
--
|
||||||
|
-- You should have received a copy of the GNU General Public License
|
||||||
|
-- along with Vicious. If not, see <https://www.gnu.org/licenses/>.
|
||||||
|
|
||||||
|
Comments
|
||||||
|
^^^^^^^^
|
||||||
|
|
||||||
Comments that contradict the code are worse than no comments.
|
Comments that contradict the code are worse than no comments.
|
||||||
Always make a priority of keeping the comments up-to-date when the code changes!
|
Always make a priority of keeping the comments up-to-date when the code changes!
|
||||||
|
@ -294,25 +310,35 @@ Always make a priority of keeping the comments up-to-date when the code changes!
|
||||||
You should use two spaces after a sentence-ending period
|
You should use two spaces after a sentence-ending period
|
||||||
in multi-sentence comments, except after the final sentence.
|
in multi-sentence comments, except after the final sentence.
|
||||||
|
|
||||||
#### Block Comments
|
Block Comments
|
||||||
|
""""""""""""""
|
||||||
|
|
||||||
Block comments generally apply to some (or all) code that follows them,
|
Block comments generally apply to some (or all) code that follows them,
|
||||||
and are indented to the same level as that code. Each line of a block comment
|
and are indented to the same level as that code. Each line of a block comment
|
||||||
starts with `--` and a single space, unless text inside the comment is indented,
|
starts with ``--`` and a single space, unless text inside the comment
|
||||||
or it is to comment out code.
|
is indented, or it is to comment out code.
|
||||||
|
|
||||||
Paragraphs inside a block comment are separated by a line containing `--` only.
|
Paragraphs inside a block comment are separated by a line containing
|
||||||
The best example is the copyright notice in the section above.
|
``--`` only. The best example is the copyright notice in the section above.
|
||||||
|
|
||||||
The `--[[...]]` style may only be used for commenting out source code.
|
The ``--[[...]]`` style may only be used for commenting out source code.
|
||||||
|
|
||||||
#### Inline Comments
|
Inline Comments
|
||||||
|
"""""""""""""""
|
||||||
|
|
||||||
An inline comment is a comment on the same line as a statement.
|
An inline comment is a comment on the same line as a statement.
|
||||||
Inline comments should be separated by at least two spaces from the statement.
|
Inline comments should be separated by at least two spaces from the statement.
|
||||||
They should start with `-- `.
|
They should start with ``--`` and one single space.
|
||||||
|
|
||||||
## Influences
|
Influences
|
||||||
|
----------
|
||||||
|
|
||||||
These contributing guideline are heavily influenced by that of `youtube-dl`,
|
These contributing guideline are heavily influenced by that of ``youtube-dl``,
|
||||||
PEP 8, Programming in Lua and the performance tips in Lua Programming Gems.
|
PEP 8, Programming in Lua and the performance tips in Lua Programming Gems.
|
||||||
|
|
||||||
|
.. _Fork this repository: https://github.com/vicious-widgets/vicious/fork
|
||||||
|
.. _Add: https://git-scm.com/docs/git-add
|
||||||
|
.. _commit: https://git-scm.com/docs/git-commit
|
||||||
|
.. _push: https://git-scm.com/docs/git-push
|
||||||
|
.. _create a pull request:
|
||||||
|
https://help.github.com/articles/creating-a-pull-request
|
104
Changes.md
104
Changes.md
|
@ -1,104 +0,0 @@
|
||||||
# Changes in 2.4.0
|
|
||||||
|
|
||||||
IMPORTANT:
|
|
||||||
|
|
||||||
- `volume` now uses 🔉 and 🔈 instead of ♫ and ♩ to show mute state.
|
|
||||||
This BREAKS backward compatibility if users substitute custom symbols
|
|
||||||
from these default.
|
|
||||||
|
|
||||||
Added:
|
|
||||||
|
|
||||||
- [wifi_linux] Expose frequency and transmission power
|
|
||||||
- `spawn` as a fallback for `awful.spawn` in case Vicious is used as
|
|
||||||
a stand-alone library. This wrapper, however, does NOT provide the facilities
|
|
||||||
to asynchronously spawn new processes. It also lacks a few features such as
|
|
||||||
parsing `stderr` and returning PID.
|
|
||||||
- `helpers.setasyncall` to avoid writing redundant workers for asynchronous
|
|
||||||
widget types. Note that these workers are only needed in case Vicious is used
|
|
||||||
as a stand-alone library.
|
|
||||||
- `helpers.setcall` for registering functions as widget types.
|
|
||||||
- `headergen` script for automatic generation of copyright notices.
|
|
||||||
- `templates` for the ease of adding new widget types.
|
|
||||||
- `CONTRIBUTING.md` which guide contributors through the steps
|
|
||||||
of filing an issue or submitting a patch.
|
|
||||||
|
|
||||||
Fixed:
|
|
||||||
|
|
||||||
- Deprecate the use of `io.popen` in following widgets:
|
|
||||||
* wifi_linux, wifiiw_linux, hwmontemp_linux, hddtemp_linux
|
|
||||||
* bat_freebsd, mem_freebsd, net_freebsd, thermal_freebsd, uptime_freebsd,
|
|
||||||
cpu_freebsd, cpufreq_freebsd, fanspeed_freebsd
|
|
||||||
* bat_openbsd
|
|
||||||
* volume, gmail, mdir, mpd, fs
|
|
||||||
- [mpd] Lua 5.3 compatibility (for real this time); also correct a typo
|
|
||||||
- [mbox] Update the deprecated `string.gfind` to `string.gmatch`
|
|
||||||
- [pkg,weather,contrib/btc] Allow function call without Awesome
|
|
||||||
- [pkg] Use more updated front-ends for Debian/Ubuntu (apt) and Fedora (dnf)
|
|
||||||
- [os] Splitted os_all into os_linux and os_bsd (and refactored to async)
|
|
||||||
- Tweak `.luacheckrc` to suit functional style and soft-limit text width to 80
|
|
||||||
- Update copyright headers for libraries and widget types
|
|
||||||
|
|
||||||
Removed:
|
|
||||||
|
|
||||||
- `helpers.sysctl` and `helpers.sysctl_table` were removed in favour of
|
|
||||||
`helpers.sysctl_async`.
|
|
||||||
|
|
||||||
# Changes in 2.3.3
|
|
||||||
|
|
||||||
Feature: Add battery widget type for OpenBSD
|
|
||||||
|
|
||||||
Fixes:
|
|
||||||
|
|
||||||
- [mpd] Lua 5.3 compatibility
|
|
||||||
- [bat\_freebsd] Update battery state symbols
|
|
||||||
|
|
||||||
# Changes in 2.3.2
|
|
||||||
|
|
||||||
Features:
|
|
||||||
|
|
||||||
- Support stacked graphs
|
|
||||||
- [hwmontemp\_linux] Provide name-based access to hwmon sensors via sysfs
|
|
||||||
- [mpd\_all] Expose more informations and format time in [hh:]mm:ss
|
|
||||||
|
|
||||||
Fixes:
|
|
||||||
|
|
||||||
- Improve defaults and mechanism for data caching
|
|
||||||
- Escape XML entities in results by default
|
|
||||||
- [weather\_all] Update NOAA link and use Awesome asynchronous API
|
|
||||||
- [mem\_linux] Use MemAvailable to calculate free amount
|
|
||||||
- [mem\_freebsd] Correct calculation and switch to swapinfo for swap
|
|
||||||
- [bat\_freebsd] Add critical charging state
|
|
||||||
- [fs\_all] Fix shell quoting of option arguments
|
|
||||||
|
|
||||||
Moreover, `.luacheckrc` was added and `README.md` was refomatted for the ease
|
|
||||||
of development.
|
|
||||||
|
|
||||||
# Changes in 2.3.1
|
|
||||||
|
|
||||||
Fixes:
|
|
||||||
|
|
||||||
- widgets can be a function again (regression introduced in 2.3.0)
|
|
||||||
|
|
||||||
# Changes in 2.3.0
|
|
||||||
|
|
||||||
Features:
|
|
||||||
- add btc widget
|
|
||||||
- add cmus widget
|
|
||||||
- alsa mixer also accept multiple arguments
|
|
||||||
|
|
||||||
Fixes:
|
|
||||||
|
|
||||||
- pkg now uses non-blocking asynchronous api
|
|
||||||
|
|
||||||
# Changes in 2.2.0
|
|
||||||
|
|
||||||
Notable changes:
|
|
||||||
|
|
||||||
- moved development from git.sysphere.org/vicious to github.com/Mic92/vicious
|
|
||||||
- official freebsd support
|
|
||||||
- escape variables before passing to shell
|
|
||||||
- support for gear timers
|
|
||||||
- fix weather widget url
|
|
||||||
- add vicious.call() method to obtain data outside of widgets
|
|
||||||
|
|
||||||
For older versions see git log
|
|
958
README.md
958
README.md
|
@ -12,957 +12,19 @@ timers, suspend widgets and so on. Vicious doesn't depend on any third party
|
||||||
Lua libraries, but may depend on additional system utilities (see widget
|
Lua libraries, but may depend on additional system utilities (see widget
|
||||||
description).
|
description).
|
||||||
|
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
When provided by an operating system package, or installed from source
|
Please see our [online documentation] for detail instructions.
|
||||||
into the Lua library path Vicious can be used as a regular Lua
|
It is also available under the `docs` directory for offline reference.
|
||||||
library, to be used stand-alone or to feed widgets of any window
|
|
||||||
manager (e.g. Ion, WMII). It is compatible with Lua version 5.1 and above.
|
|
||||||
|
|
||||||
```lua
|
## Copying
|
||||||
> widgets = require("vicious.widgets.init")
|
|
||||||
> print(widgets.volume(nil, "Master")[1])
|
|
||||||
100
|
|
||||||
```
|
|
||||||
|
|
||||||
|
Vicious is free software: you can redistribute it and/or modify
|
||||||
|
it under the terms of the GNU General Public License as
|
||||||
|
published by the Free Software Foundation, either version 2 of the
|
||||||
|
License, or (at your option) any later version.
|
||||||
|
|
||||||
## Usage within Awesome
|
Please refer to our documentation for the full [list of authors].
|
||||||
|
|
||||||
To use Vicious with Awesome, install the package from your operating
|
[online documentation]: https://vicious.rtfd.io
|
||||||
system provider, or download the source code and move it to your
|
[list of authors]: https://vicious.rtfd.io/copying.html
|
||||||
awesome configuration directory in `$XDG_CONFIG_HOME` (usually `~/.config`):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
$ 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`:
|
|
||||||
|
|
||||||
```lua
|
|
||||||
local vicious = require("vicious")
|
|
||||||
```
|
|
||||||
|
|
||||||
### Register a widget
|
|
||||||
|
|
||||||
Once you create a widget (a textbox, graph or a progressbar) call
|
|
||||||
`vicious.register()` to register it with Vicious:
|
|
||||||
|
|
||||||
vicious.register(widget, wtype, format, interval, warg)
|
|
||||||
|
|
||||||
#### widget
|
|
||||||
|
|
||||||
*Awesome* widget created with `widget()` or `awful.widget()` (in case of a
|
|
||||||
graph or a progressbar).
|
|
||||||
|
|
||||||
#### wtype
|
|
||||||
|
|
||||||
Type: Vicious widget or `function`:
|
|
||||||
|
|
||||||
* Vicious widget type: any of the available (default, or custom)
|
|
||||||
[widget type provided by Vicious](#widgets).
|
|
||||||
* function: custom function from your own *Awesome* configuration can be
|
|
||||||
registered as widget types (see [Custom widget types](#custom-widget)).
|
|
||||||
|
|
||||||
#### format
|
|
||||||
|
|
||||||
Type: `string` or `function`:
|
|
||||||
|
|
||||||
* 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 [Format functions](#format-func)).
|
|
||||||
|
|
||||||
#### interval
|
|
||||||
|
|
||||||
Number of seconds between updates of the widget (default: 2). Read section
|
|
||||||
[Power and Caching](#power) for more information.
|
|
||||||
|
|
||||||
#### warg
|
|
||||||
|
|
||||||
Some widget types require an argument to be passed, for example the battery ID.
|
|
||||||
|
|
||||||
`vicious.register` alone is not much different from
|
|
||||||
[awful.widget.watch](https://awesomewm.org/doc/api/classes/awful.widget.watch.html),
|
|
||||||
which has been added to Awesome since version 4.0. However, Vicious offers more
|
|
||||||
advanced control of widgets' behavior by providing the following functions.
|
|
||||||
|
|
||||||
### Unregister a widget
|
|
||||||
|
|
||||||
vicious.unregister(widget, keep)
|
|
||||||
|
|
||||||
If `keep == true`, `widget` will be suspended and wait for activation.
|
|
||||||
|
|
||||||
### Suspend all widgets
|
|
||||||
|
|
||||||
vicious.suspend()
|
|
||||||
|
|
||||||
See [example automation script](http://sysphere.org/~anrxc/local/sources/lmt-vicious.sh)
|
|
||||||
for the "laptop-mode-tools" start-stop module.
|
|
||||||
|
|
||||||
### Restart suspended widgets
|
|
||||||
|
|
||||||
vicious.activate(widget)
|
|
||||||
|
|
||||||
If `widget` is provided only that widget will be activated.
|
|
||||||
|
|
||||||
### Enable caching of a widget type
|
|
||||||
|
|
||||||
vicious.cache(wtype)
|
|
||||||
|
|
||||||
Enable caching of values returned by a widget type.
|
|
||||||
|
|
||||||
### Force update of widgets
|
|
||||||
|
|
||||||
vicious.force(wtable)
|
|
||||||
|
|
||||||
`wtable` is a table of one or more widgets to be updated.
|
|
||||||
|
|
||||||
### Get data from a widget
|
|
||||||
|
|
||||||
vicious.call(wtype, format, warg)
|
|
||||||
|
|
||||||
Fetch data from `wtype` to use it outside from the wibox
|
|
||||||
([example](#call-example)).
|
|
||||||
|
|
||||||
|
|
||||||
## <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
|
|
||||||
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 other 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
|
|
||||||
vicious.register. Your function can accept `format` and `warg`
|
|
||||||
arguments, just like workers.
|
|
||||||
|
|
||||||
|
|
||||||
## <a name="power"></a>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, … 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.
|
|
||||||
|
|
||||||
|
|
||||||
## Security
|
|
||||||
|
|
||||||
At the moment only one widget type (Gmail) requires auth. 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 trough 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. Trough the GPG Passphrase Agent they could
|
|
||||||
then decrypt the file transparently while their session is active.
|
|
||||||
|
|
||||||
|
|
||||||
## 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:
|
|
||||||
|
|
||||||
```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.
|
|
||||||
|
|
||||||
```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 the /dev/sda and
|
|
||||||
append *°C* to the returned value. Since the listening port is not provided,
|
|
||||||
default one is used.
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```lua
|
|
||||||
batwidget = wibox.widget.progressbar()
|
|
||||||
|
|
||||||
-- Create wibox with batwidget
|
|
||||||
batbox = wibox.layout.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:
|
|
||||||
|
|
||||||
```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)
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
## <a name="format-func"></a>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
|
|
||||||
|
|
||||||
```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
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```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.
|
|
||||||
|
|
||||||
```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.
|
|
||||||
|
|
||||||
```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")
|
|
||||||
```
|
|
||||||
|
|
||||||
#### <a name="call-example"></a>Get data from the widget
|
|
||||||
|
|
||||||
`vicious.call` could be useful for naughty notification and scripts:
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```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)))
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
## See also
|
|
||||||
|
|
||||||
* Manual pages: [awesome(1)](https://awesomewm.org/doc/manpages/awesome),
|
|
||||||
[awesomerc(5)](https://awesomewm.org/doc/manpages/awesomerc.5.html)
|
|
||||||
* [Awesome declarative layout system](https://awesomewm.org/apidoc/documentation/03-declarative-layout.md.html)
|
|
||||||
* [Example *awesome* configuration](http://git.sysphere.org/awesome-configs/)
|
|
||||||
(outdated)
|
|
||||||
* [My first awesome](https://awesomewm.org/doc/api/documentation/07-my-first-awesome.md.html)
|
|
||||||
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
For details, see CONTRIBUTING.md. Vicious is licensed under GNU GPLv2+,
|
|
||||||
which require all code within the package to be released under
|
|
||||||
a compatible license. All contributors retain their copyright to their code,
|
|
||||||
so please make sure you add your name to the header of every file you touch.
|
|
||||||
|
|
||||||
|
|
||||||
## Authors
|
|
||||||
|
|
||||||
Wicked was written by:
|
|
||||||
|
|
||||||
* Lucas de Vries \<lucas glacicle.com\>
|
|
||||||
|
|
||||||
Vicious was originally written by:
|
|
||||||
|
|
||||||
* Adrian C. (anrxc) \<anrxc sysphere.org\>
|
|
||||||
|
|
||||||
Current maintainers:
|
|
||||||
|
|
||||||
* Jörg Thalheim (Mic92) \<joerg thalheim.io\>
|
|
||||||
* [mutlusun](https://github.com/mutlusun) (especially the FreeBSD port)
|
|
||||||
* Daniel Hahler (blueyed) \<github thequod.de\>
|
|
||||||
* Nguyễn Gia Phong (McSinyx) \<vn.mcsinyx gmail.com\>
|
|
||||||
|
|
||||||
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\>
|
|
||||||
* 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\>
|
|
||||||
* crondog \<patches crondog.com\>
|
|
||||||
* David Udelson \<dru5 cornell.edu\>
|
|
||||||
* Dodo The Last \<dodo.the.last gmail.com\>
|
|
||||||
* Elric Milon \<whirm gmx.com\>
|
|
||||||
* Enric Morales \<me enric.me\>
|
|
||||||
* getzze \<getzze gmail.com\>
|
|
||||||
* Greg D. \<jabbas jabbas.pl\>
|
|
||||||
* Hagen Schink \<troja84 googlemail.com\>
|
|
||||||
* Henning Glawe \<glaweh debian.org\>
|
|
||||||
* Hiltjo Posthuma \<hiltjo codemadness.org\>
|
|
||||||
* [James Reed](https://github.com/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\>
|
|
||||||
* [Juan Carlos Menonita](https://github.com/JuanKman94)
|
|
||||||
* Juergen Descher \<jhdl gmx.net\>
|
|
||||||
* Julian Volodia \<julianvolodia gmail.com\>
|
|
||||||
* Keith Hughitt \<keith.hughitt gmail.com\>
|
|
||||||
* Lorenzo Gaggini \<lg lgaggini.net\>
|
|
||||||
* 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](https://github.com/empijei)
|
|
||||||
* 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
|
|
||||||
|
|
|
@ -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"}})
|
|
||||||
```
|
|
|
@ -1,6 +1,7 @@
|
||||||
-- contrib/openweather_all.lua
|
-- contrib/openweather_all.lua
|
||||||
-- Copyright (C) 2013 NormalRa <normalrawr gmail com>
|
-- Copyright (C) 2013 NormalRa <normalrawr gmail com>
|
||||||
-- Copyright (C) 2017 Jörg Thalheim <joerg@higgsboson.tk>
|
-- Copyright (C) 2017 Jörg Thalheim <joerg@higgsboson.tk>
|
||||||
|
-- Copyright (C) 2020 Marcel Arpogaus <marcel.arpogaus gmail com>
|
||||||
--
|
--
|
||||||
-- This file is part of Vicious.
|
-- This file is part of Vicious.
|
||||||
--
|
--
|
||||||
|
@ -16,69 +17,66 @@
|
||||||
--
|
--
|
||||||
-- You should have received a copy of the GNU General Public License
|
-- You should have received a copy of the GNU General Public License
|
||||||
-- along with Vicious. If not, see <https://www.gnu.org/licenses/>.
|
-- along with Vicious. If not, see <https://www.gnu.org/licenses/>.
|
||||||
|
|
||||||
-- {{{ Grab environment
|
-- {{{ Grab environment
|
||||||
local tonumber = tonumber
|
local tonumber = tonumber
|
||||||
local io = { popen = io.popen }
|
local string = {match = string.match}
|
||||||
local setmetatable = setmetatable
|
local math = {ceil = math.ceil, floor = math.floor}
|
||||||
local string = { match = string.match }
|
local helpers = require "vicious.helpers"
|
||||||
local math = {
|
local spawn = require "vicious.spawn"
|
||||||
ceil = math.ceil,
|
|
||||||
floor = math.floor
|
|
||||||
}
|
|
||||||
-- }}}
|
-- }}}
|
||||||
|
|
||||||
|
|
||||||
-- Openweather: provides weather information for a requested station
|
-- Openweather: provides weather information for a requested station
|
||||||
-- vicious.widgets.openweather
|
-- vicious.widgets.openweather
|
||||||
local openweather_all = {}
|
local openweather_all = {}
|
||||||
|
|
||||||
|
|
||||||
-- Initialize function tables
|
-- Initialize function tables
|
||||||
local _wdirs = { "N", "NE", "E", "SE", "S", "SW", "W", "NW", "N" }
|
local _wdirs = {"N", "NE", "E", "SE", "S", "SW", "W", "NW", "N"}
|
||||||
local _wdata = {
|
local _wdata = {
|
||||||
["{city}"] = "N/A",
|
["{city}"] = "N/A",
|
||||||
["{wind deg}"] = "N/A",
|
["{wind deg}"] = "N/A",
|
||||||
["{wind aim}"] = "N/A",
|
["{wind aim}"] = "N/A",
|
||||||
["{wind mps}"] = "N/A",
|
["{wind mps}"] = "N/A",
|
||||||
["{wind kmh}"] = "N/A",
|
["{wind kmh}"] = "N/A",
|
||||||
["{sky}"] = "N/A",
|
["{sky}"] = "N/A",
|
||||||
["{weather}"] = "N/A",
|
["{weather}"] = "N/A",
|
||||||
["{temp c}"] = "N/A",
|
["{temp c}"] = "N/A",
|
||||||
["{humid}"] = "N/A",
|
["{temp min c}"] = "N/A",
|
||||||
["{press}"] = "N/A"
|
["{temp max c}"] = "N/A",
|
||||||
|
["{sunrise}"] = -1,
|
||||||
|
["{sunset}"] = -1,
|
||||||
|
["{humid}"] = "N/A",
|
||||||
|
["{press}"] = "N/A"
|
||||||
}
|
}
|
||||||
|
|
||||||
-- {{{ Openweather widget type
|
-- {{{ Openweather widget type
|
||||||
local function worker(format, warg)
|
local function parse(stdout, stderr, exitreason, exitcode)
|
||||||
if not warg then return end
|
|
||||||
|
|
||||||
-- Get weather forceast using the city ID code, from:
|
|
||||||
-- * OpenWeatherMap.org
|
|
||||||
local openweather = "http://api.openweathermap.org/data/2.5/weather?id="..warg.."&mode=json&units=metric"
|
|
||||||
local f = io.popen("curl --connect-timeout 1 -fsm 3 '"..openweather.."'")
|
|
||||||
local ws = f:read("*all")
|
|
||||||
f:close()
|
|
||||||
|
|
||||||
-- Check if there was a timeout or a problem with the station
|
-- Check if there was a timeout or a problem with the station
|
||||||
if ws == nil then return _wdata end
|
if stdout == nil or exitcode ~= 0 then return _wdata end
|
||||||
|
|
||||||
_wdata["{city}"] = -- City name
|
_wdata["{city}"] = -- City name
|
||||||
string.match(ws, '"name":"([%a%s%-]+)"') or _wdata["{city}"]
|
string.match(stdout, '"name":"([%a%s%-]+)"') or _wdata["{city}"]
|
||||||
_wdata["{wind deg}"] = -- Wind degrees
|
_wdata["{wind deg}"] = -- Wind degrees
|
||||||
string.match(ws, '"deg":([%d]+)') or _wdata["{wind deg}"]
|
string.match(stdout, '"deg":([%d]+)') or _wdata["{wind deg}"]
|
||||||
_wdata["{wind mps}"] = -- Wind speed in meters per second
|
_wdata["{wind mps}"] = -- Wind speed in meters per second
|
||||||
string.match(ws, '"speed":([%d%.]+)') or _wdata["{wind mps}"]
|
string.match(stdout, '"speed":([%d%.]+)') or _wdata["{wind mps}"]
|
||||||
_wdata["{sky}"] = -- Sky conditions
|
_wdata["{sky}"] = -- Sky conditions
|
||||||
string.match(ws, '"main":"([%a]+)"') or _wdata["{sky}"]
|
string.match(stdout, '"main":"([%a]+)"') or _wdata["{sky}"]
|
||||||
_wdata["{weather}"] = -- Weather description
|
_wdata["{weather}"] = -- Weather description
|
||||||
string.match(ws, '"description":"([%a%s]+)"') or _wdata["{weather}"]
|
string.match(stdout, '"description":"([%a%s]+)"') or _wdata["{weather}"]
|
||||||
_wdata["{temp c}"] = -- Temperature in celsius
|
_wdata["{temp c}"] = -- Temperature in celsius
|
||||||
string.match(ws, '"temp":([%-]?[%d%.]+)') or _wdata["{temp c}"]
|
string.match(stdout, '"temp":([%-]?[%d%.]+)') or _wdata["{temp c}"]
|
||||||
_wdata["{humid}"] = -- Relative humidity in percent
|
_wdata["{temp min c}"] = -- Minimal Temperature in celsius
|
||||||
string.match(ws, '"humidity":([%d]+)') or _wdata["{humid}"]
|
string.match(stdout, '"temp_min":([%-]?[%d%.]+)') or _wdata["{temp min c}"]
|
||||||
_wdata["{press}"] = -- Pressure in hPa
|
_wdata["{temp max c}"] = -- Maximal Temperature in celsius
|
||||||
string.match(ws, '"pressure":([%d%.]+)') or _wdata["{press}"]
|
string.match(stdout, '"temp_max":([%-]?[%d%.]+)') or _wdata["{temp max c}"]
|
||||||
|
_wdata["{humid}"] = -- Relative humidity in percent
|
||||||
|
string.match(stdout, '"humidity":([%d]+)') or _wdata["{humid}"]
|
||||||
|
_wdata["{sunrise}"] = -- Sunrise
|
||||||
|
tonumber(string.match(stdout, '"sunrise":([%d]+)')) or _wdata["{sunrise}"]
|
||||||
|
_wdata["{sunset}"] = -- Sunset
|
||||||
|
tonumber(string.match(stdout, '"sunset":([%d]+)')) or _wdata["{sunset}"]
|
||||||
|
_wdata["{press}"] = -- Pressure in hPa
|
||||||
|
string.match(stdout, '"pressure":([%d%.]+)') or _wdata["{press}"]
|
||||||
|
|
||||||
-- Wind speed in km/h
|
-- Wind speed in km/h
|
||||||
if _wdata["{wind mps}"] ~= "N/A" then
|
if _wdata["{wind mps}"] ~= "N/A" then
|
||||||
|
@ -92,17 +90,32 @@ local function worker(format, warg)
|
||||||
_wdata["{wind deg}"] = tonumber(_wdata["{wind deg}"])
|
_wdata["{wind deg}"] = tonumber(_wdata["{wind deg}"])
|
||||||
|
|
||||||
-- Lua tables start at [1]
|
-- Lua tables start at [1]
|
||||||
if (_wdata["{wind deg}"] / 45)%1 == 0 then
|
if (_wdata["{wind deg}"] / 45) % 1 == 0 then
|
||||||
_wdata["{wind aim}"] = _wdirs[_wdata["{wind deg}"] / 45 + 1]
|
_wdata["{wind aim}"] = _wdirs[_wdata["{wind deg}"] / 45 + 1]
|
||||||
else
|
else
|
||||||
_wdata["{wind aim}"] =
|
_wdata["{wind aim}"] = _wdirs[math.ceil(_wdata["{wind deg}"] / 45) +
|
||||||
_wdirs[math.ceil(_wdata["{wind deg}"] / 45) + 1]..
|
1] ..
|
||||||
_wdirs[math.floor(_wdata["{wind deg}"] / 45) + 1]
|
_wdirs[math.floor(
|
||||||
|
_wdata["{wind deg}"] / 45) + 1]
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
return _wdata
|
return _wdata
|
||||||
end
|
end
|
||||||
|
|
||||||
|
function openweather_all.async(format, warg, callback)
|
||||||
|
if not warg then return callback {} end
|
||||||
|
if type(warg) ~= "table" then return callback {} end
|
||||||
|
|
||||||
|
-- Get weather forceast using the city ID code, from:
|
||||||
|
-- * OpenWeatherMap.org
|
||||||
|
local openweather = "http://api.openweathermap.org/data/2.5/weather?id=" ..
|
||||||
|
warg.city_id .. "&appid=" .. warg.app_id ..
|
||||||
|
"&mode=json&units=metric"
|
||||||
|
|
||||||
|
spawn.easy_async("curl --connect-timeout 1 -fsm 3 '" .. openweather .. "'",
|
||||||
|
function(...) callback(parse(...)) end)
|
||||||
|
end
|
||||||
-- }}}
|
-- }}}
|
||||||
|
|
||||||
return setmetatable(openweather_all, { __call = function(_, ...) return worker(...) end })
|
return helpers.setasyncall(openweather_all)
|
||||||
|
|
|
@ -0,0 +1,20 @@
|
||||||
|
# Minimal makefile for Sphinx documentation
|
||||||
|
#
|
||||||
|
|
||||||
|
# You can set these variables from the command line, and also
|
||||||
|
# from the environment for the first two.
|
||||||
|
SPHINXOPTS ?=
|
||||||
|
SPHINXBUILD ?= sphinx-build
|
||||||
|
SOURCEDIR = source
|
||||||
|
BUILDDIR = build
|
||||||
|
|
||||||
|
# Put it first so that "make" without argument is like "make help".
|
||||||
|
help:
|
||||||
|
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||||
|
|
||||||
|
.PHONY: help Makefile
|
||||||
|
|
||||||
|
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||||
|
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||||
|
%: Makefile
|
||||||
|
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
@ -0,0 +1,3 @@
|
||||||
|
Sphinx >= 3
|
||||||
|
sphinx_rtd_theme >= 1
|
||||||
|
sphinxcontrib-luadomain
|
|
@ -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.
|
|
@ -0,0 +1 @@
|
||||||
|
../../CHANGELOG.rst
|
|
@ -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-2023, vicious-widgets'
|
||||||
|
author = 'vicious-widgets'
|
||||||
|
|
||||||
|
# The full version, including alpha/beta/rc tags
|
||||||
|
release = '2.7.0'
|
||||||
|
|
||||||
|
# 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', '@')}
|
||||||
|
|
||||||
|
# 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 = []
|
|
@ -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" } })
|
|
@ -0,0 +1 @@
|
||||||
|
../../CONTRIBUTING.rst
|
|
@ -0,0 +1,83 @@
|
||||||
|
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>` <mcsinyx disroot.org>
|
||||||
|
* :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>
|
||||||
|
* 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>
|
||||||
|
* crondog <patches crondog.com>
|
||||||
|
* David Udelson <dru5 cornell.edu>
|
||||||
|
* Dodo The Last <dodo.the.last gmail.com>
|
||||||
|
* Elric Milon <whirm gmx.com>
|
||||||
|
* 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>
|
||||||
|
* 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>
|
||||||
|
* :github:`Roberto <empijei>`
|
||||||
|
* 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
|
|
@ -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.
|
|
@ -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.layout.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)
|
|
@ -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)))
|
|
@ -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/
|
|
@ -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.
|
|
@ -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
|
|
@ -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/
|
|
@ -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
|
17
helpers.lua
17
helpers.lua
|
@ -4,16 +4,13 @@
|
||||||
-- Copyright (C) 2009 Lucas de Vries <lucas@glacicle.com>
|
-- Copyright (C) 2009 Lucas de Vries <lucas@glacicle.com>
|
||||||
-- Copyright (C) 2009 Rémy C. <shikamaru@mandriva.org>
|
-- Copyright (C) 2009 Rémy C. <shikamaru@mandriva.org>
|
||||||
-- Copyright (C) 2009-2012 Adrian C. (anrxc) <anrxc@sysphere.org>
|
-- Copyright (C) 2009-2012 Adrian C. (anrxc) <anrxc@sysphere.org>
|
||||||
-- Copyright (C) 2011 Joerg T. (Mic92) <jthalheim@gmail.com>
|
-- Copyright (C) 2011-2018 Jörg Thalheim <joerg@thalheim.io>
|
||||||
-- Copyright (C) 2012 Arvydas Sidorenko <asido4@gmail.com>
|
-- Copyright (C) 2012 Arvydas Sidorenko <asido4@gmail.com>
|
||||||
-- Copyright (C) 2012 Jörg Thalheim <jthalheim@gmail.com>
|
|
||||||
-- Copyright (C) 2014-2015 Jörg Thalheim <joerg@higgsboson.tk>
|
|
||||||
-- Copyright (C) 2017 Joerg Thalheim <joerg@thalheim.io>
|
|
||||||
-- Copyright (C) 2017,2019 mutlusun <mutlusun@github.com>
|
-- Copyright (C) 2017,2019 mutlusun <mutlusun@github.com>
|
||||||
-- Copyright (C) 2017-2018 Jörg Thalheim <joerg@thalheim.io>
|
|
||||||
-- Copyright (C) 2018-2019 Nguyễn Gia Phong <vn.mcsinyx@gmail.com>
|
-- Copyright (C) 2018-2019 Nguyễn Gia Phong <vn.mcsinyx@gmail.com>
|
||||||
-- Copyright (C) 2019 Alexander Koch <lynix47@gmail.com>
|
-- Copyright (C) 2019 Alexander Koch <lynix47@gmail.com>
|
||||||
-- Copyright (C) 2019 Enric Morales <me@enric.me>
|
-- Copyright (C) 2019 Enric Morales <me@enric.me>
|
||||||
|
-- Copyright (C) 2022 Constantin Piber <cp.piber@gmail.com>
|
||||||
--
|
--
|
||||||
-- This file is part of Vicious.
|
-- This file is part of Vicious.
|
||||||
--
|
--
|
||||||
|
@ -37,6 +34,7 @@ local rawget = rawget
|
||||||
local require = require
|
local require = require
|
||||||
local tonumber = tonumber
|
local tonumber = tonumber
|
||||||
local tostring = tostring
|
local tostring = tostring
|
||||||
|
local type = type
|
||||||
local io = { open = io.open, popen = io.popen }
|
local io = { open = io.open, popen = io.popen }
|
||||||
local setmetatable = setmetatable
|
local setmetatable = setmetatable
|
||||||
local getmetatable = getmetatable
|
local getmetatable = getmetatable
|
||||||
|
@ -168,11 +166,12 @@ end
|
||||||
-- {{{ Format a string with args
|
-- {{{ Format a string with args
|
||||||
function helpers.format(format, args)
|
function helpers.format(format, args)
|
||||||
for var, val in pairs(args) do
|
for var, val in pairs(args) do
|
||||||
format = format:gsub("$" .. (tonumber(var) and var or
|
if tonumber(var) == nil then
|
||||||
var:gsub("[-+?*]", function(i) return "%"..i end)),
|
var = var:gsub("[-+?*]", function(i) return "%"..i end)
|
||||||
val)
|
end
|
||||||
|
if type(val) == "string" then val = val:gsub("%%", "%%%%") end
|
||||||
|
format = format:gsub("$" .. var, val)
|
||||||
end
|
end
|
||||||
|
|
||||||
return format
|
return format
|
||||||
end
|
end
|
||||||
-- }}}
|
-- }}}
|
||||||
|
|
56
init.lua
56
init.lua
|
@ -1,20 +1,17 @@
|
||||||
-- Vicious module initialization
|
-- Vicious module initialization
|
||||||
-- Copyright (C) 2009 Lucas de Vries <lucas@glacicle.com>
|
-- Copyright (C) 2009 Lucas de Vries <lucas@glacicle.com>
|
||||||
-- Copyright (C) 2009-2013 Adrian C. (anrxc) <anrxc@sysphere.org>
|
-- Copyright (C) 2009-2013 Adrian C. (anrxc) <anrxc@sysphere.org>
|
||||||
-- Copyright (C) 2011 Joerg T. (Mic92) <jthalheim@gmail.com>
|
-- Copyright (C) 2011-2017 Joerg Thalheim <joerg@thalheim.io>
|
||||||
-- Copyright (C) 2012 Arvydas Sidorenko <asido4@gmail.com>
|
-- Copyright (C) 2012 Arvydas Sidorenko <asido4@gmail.com>
|
||||||
-- Copyright (C) 2012 Jörg Thalheim <jthalheim@gmail.com>
|
|
||||||
-- Copyright (C) 2013 Dodo <dodo.the.last@gmail.com>
|
-- Copyright (C) 2013 Dodo <dodo.the.last@gmail.com>
|
||||||
-- Copyright (C) 2013-2014,2017 Jörg Thalheim <joerg@higgsboson.tk>
|
|
||||||
-- Copyright (C) 2014 blastmaster <blastmaster@tuxcode.org>
|
-- Copyright (C) 2014 blastmaster <blastmaster@tuxcode.org>
|
||||||
-- Copyright (C) 2015 Daniel Hahler <git@thequod.de>
|
-- Copyright (C) 2015,2019 Daniel Hahler <github@thequod.de>
|
||||||
-- Copyright (C) 2017 James Reed <supplantr@users.noreply.github.com>
|
-- Copyright (C) 2017 James Reed <supplantr@users.noreply.github.com>
|
||||||
-- Copyright (C) 2017 Joerg Thalheim <joerg@thalheim.io>
|
|
||||||
-- Copyright (C) 2017 getzze <getzze@gmail.com>
|
-- Copyright (C) 2017 getzze <getzze@gmail.com>
|
||||||
-- Copyright (C) 2017 mutlusun <mutlusun@github.com>
|
-- Copyright (C) 2017 mutlusun <mutlusun@github.com>
|
||||||
-- Copyright (C) 2018 Beniamin Kalinowski <beniamin.kalinowski@gmail.com>
|
-- Copyright (C) 2018 Beniamin Kalinowski <beniamin.kalinowski@gmail.com>
|
||||||
-- Copyright (C) 2018 Nguyễn Gia Phong <vn.mcsinyx@gmail.com>
|
-- Copyright (C) 2018,2020 Nguyễn Gia Phong <mcsinyx@disroot.org>
|
||||||
-- Copyright (C) 2019 Daniel Hahler <github@thequod.de>
|
-- Copyright (C) 2022 Constantin Piber <cp.piber@gmail.com>
|
||||||
--
|
--
|
||||||
-- This file is part of Vicious.
|
-- This file is part of Vicious.
|
||||||
--
|
--
|
||||||
|
@ -42,6 +39,14 @@ local table = {
|
||||||
remove = table.remove
|
remove = table.remove
|
||||||
}
|
}
|
||||||
local helpers = require("vicious.helpers")
|
local helpers = require("vicious.helpers")
|
||||||
|
local dstatus, debug = pcall(require, "gears.debug")
|
||||||
|
local stderr = io.stderr
|
||||||
|
local warn
|
||||||
|
if dstatus then
|
||||||
|
warn = debug.print_warning
|
||||||
|
else
|
||||||
|
warn = function (msg) stderr:write("Warning (vicious): ", msg, "\n") end
|
||||||
|
end
|
||||||
|
|
||||||
-- Vicious: widgets for the awesome window manager
|
-- Vicious: widgets for the awesome window manager
|
||||||
local vicious = {}
|
local vicious = {}
|
||||||
|
@ -136,7 +141,8 @@ local function update(widget, reg, disablecache)
|
||||||
reg.warg,
|
reg.warg,
|
||||||
function(data)
|
function(data)
|
||||||
update_cache(data, update_time, c)
|
update_cache(data, update_time, c)
|
||||||
update_value(data)
|
local status, res = pcall(update_value, data)
|
||||||
|
if not status then warn(res) end
|
||||||
reg.lock=false
|
reg.lock=false
|
||||||
end)
|
end)
|
||||||
end
|
end
|
||||||
|
@ -322,17 +328,39 @@ function vicious.activate(widget)
|
||||||
end
|
end
|
||||||
-- }}}
|
-- }}}
|
||||||
|
|
||||||
-- {{{ Get custom widget format data
|
-- {{{ Get formatted data from a synchronous widget type
|
||||||
function vicious.call(myw, format, warg)
|
function vicious.call(wtype, format, warg)
|
||||||
local mydata = myw(format, warg)
|
if wtype.async ~= nil then return nil end
|
||||||
|
|
||||||
|
local data = wtype(format, warg)
|
||||||
if type(format) == "string" then
|
if type(format) == "string" then
|
||||||
return helpers.format(format, mydata)
|
return helpers.format(format, data)
|
||||||
elseif type(format) == "function" then
|
elseif type(format) == "function" then
|
||||||
return format(myw, mydata)
|
return format(wtype, data)
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
-- }}}
|
-- }}}
|
||||||
|
|
||||||
return vicious
|
-- {{{ Get formatted data from an asynchronous widget type
|
||||||
|
function vicious.call_async(wtype, format, warg, callback)
|
||||||
|
if wtype.async == nil then
|
||||||
|
callback()
|
||||||
|
return
|
||||||
|
end
|
||||||
|
|
||||||
|
wtype.async(
|
||||||
|
format, warg,
|
||||||
|
function (data)
|
||||||
|
if type(format) == "string" then
|
||||||
|
callback(helpers.format(format, data))
|
||||||
|
elseif type(format) == "function" then
|
||||||
|
callback(format(wtype, data))
|
||||||
|
else
|
||||||
|
callback()
|
||||||
|
end
|
||||||
|
end)
|
||||||
|
end
|
||||||
|
-- }}}
|
||||||
|
|
||||||
|
return vicious
|
||||||
-- }}}
|
-- }}}
|
||||||
|
|
|
@ -0,0 +1,69 @@
|
||||||
|
-- AMD GPU widget type for Linux
|
||||||
|
-- Copyright (C) 2022 Rémy Clouard <shikamaru shikamaru fr>
|
||||||
|
--
|
||||||
|
-- This file is part of Vicious.
|
||||||
|
--
|
||||||
|
-- Vicious is free software: you can redistribute it and/or modify
|
||||||
|
-- it under the terms of the GNU General Public License as
|
||||||
|
-- published by the Free Software Foundation, either version 2 of the
|
||||||
|
-- License, or (at your option) any later version.
|
||||||
|
--
|
||||||
|
-- Vicious is distributed in the hope that it will be useful,
|
||||||
|
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||||
|
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
|
-- GNU General Public License for more details.
|
||||||
|
--
|
||||||
|
-- You should have received a copy of the GNU General Public License
|
||||||
|
-- along with Vicious. If not, see <https://www.gnu.org/licenses/>.
|
||||||
|
|
||||||
|
local io = { open = io.open }
|
||||||
|
local string = { match = string.match }
|
||||||
|
local tonumber = tonumber
|
||||||
|
local type = type
|
||||||
|
|
||||||
|
local helpers = require("vicious.helpers")
|
||||||
|
|
||||||
|
local _mem = nil
|
||||||
|
|
||||||
|
-- {{{ AMDGPU widget type
|
||||||
|
return helpers.setcall(function (format, warg)
|
||||||
|
if not warg then return end
|
||||||
|
|
||||||
|
-- see https://www.kernel.org/doc/html/v5.9/gpu/amdgpu.html#busy-percent
|
||||||
|
local amdgpu = "/sys/class/drm/"..warg.."/device"
|
||||||
|
local _data = {}
|
||||||
|
|
||||||
|
local f = io.open(amdgpu .. "/gpu_busy_percent", "r")
|
||||||
|
if f then
|
||||||
|
_data["{gpu_usage}"] = f:read("*line")
|
||||||
|
f:close()
|
||||||
|
else
|
||||||
|
_data["{gpu_usage}"] = "N/A"
|
||||||
|
end
|
||||||
|
|
||||||
|
if _mem == nil then
|
||||||
|
f = io.open(amdgpu .. "/mem_info_vram_total", "r")
|
||||||
|
if f then
|
||||||
|
_mem = tonumber(string.match(f:read("*line"), "([%d]+)"))
|
||||||
|
f:close()
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
f = io.open(amdgpu .. "/mem_info_vram_used", "r")
|
||||||
|
if f then
|
||||||
|
local _used = tonumber(string.match(f:read("*line"), "([%d]+)"))
|
||||||
|
if type(_used) == 'number' and type(_mem) == 'number'
|
||||||
|
and _mem > 0 then
|
||||||
|
_data["{mem_usage}"] = _used/_mem*100
|
||||||
|
else
|
||||||
|
_data["{mem_usage}"] = "N/A"
|
||||||
|
end
|
||||||
|
f:close()
|
||||||
|
else
|
||||||
|
_data["{mem_usage}"] = "N/A"
|
||||||
|
end
|
||||||
|
|
||||||
|
return _data
|
||||||
|
|
||||||
|
end)
|
||||||
|
--}}}
|
|
@ -1,5 +1,5 @@
|
||||||
-- widget type providing name-indexed temperatures from /sys/class/hwmon
|
-- widget type providing name-indexed temperatures from /sys/class/hwmon
|
||||||
-- Copyright (C) 2019 Alexander Koch <lynix47@gmail.com>
|
-- Copyright (C) 2019, 2020 Alexander Koch <lynix47@gmail.com>
|
||||||
-- Copyright (C) 2019 Nguyễn Gia Phong <vn.mcsinyx@gmail.com>
|
-- Copyright (C) 2019 Nguyễn Gia Phong <vn.mcsinyx@gmail.com>
|
||||||
--
|
--
|
||||||
-- This file is part of Vicious.
|
-- This file is part of Vicious.
|
||||||
|
@ -25,6 +25,14 @@ local io = { open = io.open }
|
||||||
local helpers = require"vicious.helpers"
|
local helpers = require"vicious.helpers"
|
||||||
local spawn = require"vicious.spawn"
|
local spawn = require"vicious.spawn"
|
||||||
|
|
||||||
|
local pathcache = {}
|
||||||
|
|
||||||
|
local function read_sensor(path, callback)
|
||||||
|
local f = io.open(path, "r")
|
||||||
|
callback{ tonumber(f:read"*line") / 1000 }
|
||||||
|
f:close()
|
||||||
|
end
|
||||||
|
|
||||||
-- hwmontemp: provides name-indexed temps from /sys/class/hwmon
|
-- hwmontemp: provides name-indexed temps from /sys/class/hwmon
|
||||||
-- vicious.widgets.hwmontemp
|
-- vicious.widgets.hwmontemp
|
||||||
return helpers.setasyncall{
|
return helpers.setasyncall{
|
||||||
|
@ -32,6 +40,7 @@ return helpers.setasyncall{
|
||||||
if type(warg) ~= "table" or type(warg[1]) ~= "string" then
|
if type(warg) ~= "table" or type(warg[1]) ~= "string" then
|
||||||
return callback{}
|
return callback{}
|
||||||
end
|
end
|
||||||
|
|
||||||
local input = warg[2]
|
local input = warg[2]
|
||||||
if type(input) == "number" then
|
if type(input) == "number" then
|
||||||
input = ("temp%d_input"):format(input)
|
input = ("temp%d_input"):format(input)
|
||||||
|
@ -39,16 +48,20 @@ return helpers.setasyncall{
|
||||||
input = "temp1_input"
|
input = "temp1_input"
|
||||||
end
|
end
|
||||||
|
|
||||||
spawn.easy_async_with_shell(
|
local sensor = warg[1]
|
||||||
"grep " .. warg[1] .. " -wl /sys/class/hwmon/*/name",
|
if pathcache[sensor] then
|
||||||
function (stdout, stderr, exitreason, exitcode)
|
read_sensor(pathcache[sensor] .. input, callback)
|
||||||
if exitreason == "exit" and exitcode == 0 then
|
else
|
||||||
local f = io.open(stdout:gsub("name%s+", input), "r")
|
spawn.easy_async_with_shell(
|
||||||
callback{ tonumber(f:read"*line") / 1000 }
|
"grep " .. sensor .. " -wl /sys/class/hwmon/*/name",
|
||||||
f:close()
|
function (stdout, stderr, exitreason, exitcode)
|
||||||
else
|
if exitreason == "exit" and exitcode == 0 then
|
||||||
callback{}
|
pathcache[sensor] = stdout:gsub("name%s+", "")
|
||||||
end
|
read_sensor(pathcache[sensor] .. input, callback)
|
||||||
end)
|
else
|
||||||
|
callback{}
|
||||||
|
end
|
||||||
|
end)
|
||||||
|
end
|
||||||
end }
|
end }
|
||||||
-- vim: ts=4:sw=4:expandtab
|
-- vim: ts=4:sw=4:expandtab
|
||||||
|
|
|
@ -40,11 +40,11 @@ function mdir_all.async(format, warg, callback)
|
||||||
|
|
||||||
local new, cur = 0, 0
|
local new, cur = 0, 0
|
||||||
spawn.with_line_callback(
|
spawn.with_line_callback(
|
||||||
"find" .. starting_points .. " -type f -regex '.*/cur/.*2,[^S]*$';",
|
"find" .. starting_points .. " -type f -regex '.*/cur/.*2,[^S]*$'",
|
||||||
{ stdout = function (filename) cur = cur + 1 end,
|
{ stdout = function (filename) cur = cur + 1 end,
|
||||||
output_done = function ()
|
output_done = function ()
|
||||||
spawn.with_line_callback(
|
spawn.with_line_callback(
|
||||||
"find" .. starting_points .. " -type f -path '*/new/*';",
|
"find" .. starting_points .. " -type f -path '*/new/*'",
|
||||||
{ stdout = function (filename) new = new + 1 end,
|
{ stdout = function (filename) new = new + 1 end,
|
||||||
output_done = function () callback{ new, cur } end })
|
output_done = function () callback{ new, cur } end })
|
||||||
end })
|
end })
|
||||||
|
|
|
@ -5,6 +5,8 @@
|
||||||
-- Copyright (C) 2018-2019 Nguyễn Gia Phong <vn.mcsinyx@gmail.com>
|
-- Copyright (C) 2018-2019 Nguyễn Gia Phong <vn.mcsinyx@gmail.com>
|
||||||
-- Copyright (C) 2019 Juan Carlos Menonita <JuanKman94@users.noreply.github.com>
|
-- Copyright (C) 2019 Juan Carlos Menonita <JuanKman94@users.noreply.github.com>
|
||||||
-- Copyright (C) 2019 Lorenzo Gaggini <lg@lgaggini.net>
|
-- Copyright (C) 2019 Lorenzo Gaggini <lg@lgaggini.net>
|
||||||
|
-- Copyright (C) 2022 Constantin Piber <cp.piber@gmail.com>
|
||||||
|
-- Copyright (C) 2023 Cássio Ávila <cassioavila@autistici.org>
|
||||||
--
|
--
|
||||||
-- This file is part of Vicious.
|
-- This file is part of Vicious.
|
||||||
--
|
--
|
||||||
|
@ -75,6 +77,40 @@ local function format_progress_percentage(elapsed, duration)
|
||||||
end
|
end
|
||||||
-- }}}
|
-- }}}
|
||||||
|
|
||||||
|
-- {{{ Build shell command from mpd command string
|
||||||
|
local function build_cmd(warg, q)
|
||||||
|
-- Construct MPD client options, fallback to defaults when necessary
|
||||||
|
local query = ("printf 'password %s\n%sclose\n'"):format(
|
||||||
|
warg and (warg.password or warg[1]) or '""',
|
||||||
|
q)
|
||||||
|
local connect = ("curl --connect-timeout 1 -fsm 3 telnet://%s:%s"):format(
|
||||||
|
warg and (warg.host or warg[2]) or "127.0.0.1",
|
||||||
|
warg and (warg.port or warg[3]) or "6600")
|
||||||
|
return query .. "|" .. connect
|
||||||
|
end
|
||||||
|
-- }}}
|
||||||
|
|
||||||
|
-- {{{ Common MPD commands
|
||||||
|
function mpd_all.playpause(warg)
|
||||||
|
spawn.with_shell(build_cmd(warg, "pause\n"))
|
||||||
|
end
|
||||||
|
function mpd_all.play(warg)
|
||||||
|
spawn.with_shell(build_cmd(warg, "pause 0\n"))
|
||||||
|
end
|
||||||
|
function mpd_all.pause(warg)
|
||||||
|
spawn.with_shell(build_cmd(warg, "pause 1\n"))
|
||||||
|
end
|
||||||
|
function mpd_all.stop(warg)
|
||||||
|
spawn.with_shell(build_cmd(warg, "stop\n"))
|
||||||
|
end
|
||||||
|
function mpd_all.next(warg)
|
||||||
|
spawn.with_shell(build_cmd(warg, "next\n"))
|
||||||
|
end
|
||||||
|
function mpd_all.previous(warg)
|
||||||
|
spawn.with_shell(build_cmd(warg, "previous\n"))
|
||||||
|
end
|
||||||
|
-- }}}
|
||||||
|
|
||||||
-- {{{ MPD widget type
|
-- {{{ MPD widget type
|
||||||
function mpd_all.async(format, warg, callback)
|
function mpd_all.async(format, warg, callback)
|
||||||
-- Fallback values
|
-- Fallback values
|
||||||
|
@ -83,26 +119,27 @@ function mpd_all.async(format, warg, callback)
|
||||||
["{bitrate}"] = 0,
|
["{bitrate}"] = 0,
|
||||||
["{elapsed}"] = 0,
|
["{elapsed}"] = 0,
|
||||||
["{duration}"] = 0,
|
["{duration}"] = 0,
|
||||||
["{repeat}"] = false,
|
["{repeat}"] = 0,
|
||||||
["{random}"] = false,
|
["{random}"] = 0,
|
||||||
["{state}"] = "N/A",
|
["{state}"] = "N/A",
|
||||||
["{Artist}"] = "N/A",
|
["{Artist}"] = "N/A",
|
||||||
|
["{Artists}"] = "N/A",
|
||||||
["{Title}"] = "N/A",
|
["{Title}"] = "N/A",
|
||||||
["{Album}"] = "N/A",
|
["{Album}"] = "N/A",
|
||||||
["{Genre}"] = "N/A",
|
["{Genre}"] = "N/A",
|
||||||
--["{Name}"] = "N/A",
|
["{Genres}"] = "N/A",
|
||||||
--["{file}"] = "N/A",
|
|
||||||
}
|
}
|
||||||
|
|
||||||
-- Construct MPD client options, fallback to defaults when necessary
|
local separator = warg and (warg.separator or warg[4]) or ", "
|
||||||
local query = ("printf 'password %s\nstatus\ncurrentsong\nclose\n'"):format(
|
|
||||||
warg and (warg.password or warg[1]) or '""')
|
local cmd = build_cmd(warg, "status\ncurrentsong\n")
|
||||||
local connect = ("curl --connect-timeout 1 -fsm 3 telnet://%s:%s"):format(
|
|
||||||
warg and (warg.host or warg[2]) or "127.0.0.1",
|
local function append_with_separator (current, value)
|
||||||
warg and (warg.port or warg[3]) or "6600")
|
return ("%s%s%s"):format(current, separator, value)
|
||||||
|
end
|
||||||
|
|
||||||
-- Get data from MPD server
|
-- Get data from MPD server
|
||||||
spawn.with_line_callback_with_shell(query .. "|" .. connect, {
|
spawn.with_line_callback_with_shell(cmd, {
|
||||||
stdout = function (line)
|
stdout = function (line)
|
||||||
for k, v in line:gmatch"([%w]+):[%s](.*)$" do
|
for k, v in line:gmatch"([%w]+):[%s](.*)$" do
|
||||||
local key = "{" .. k .. "}"
|
local key = "{" .. k .. "}"
|
||||||
|
@ -114,8 +151,17 @@ function mpd_all.async(format, warg, callback)
|
||||||
elseif k == "state" then
|
elseif k == "state" then
|
||||||
mpd_state[key] = helpers.capitalize(v)
|
mpd_state[key] = helpers.capitalize(v)
|
||||||
elseif k == "Artist" or k == "Title" or
|
elseif k == "Artist" or k == "Title" or
|
||||||
--k == "Name" or k == "file" or
|
|
||||||
k == "Album" or k == "Genre" then
|
k == "Album" or k == "Genre" then
|
||||||
|
if k == "Artist" or k == "Genre" then
|
||||||
|
local current_key = "{" .. k .. "s}"
|
||||||
|
local current_state = mpd_state[current_key]
|
||||||
|
if current_state == "N/A" then
|
||||||
|
mpd_state[current_key] = v
|
||||||
|
else
|
||||||
|
mpd_state[current_key] = append_with_separator(
|
||||||
|
current_state, v)
|
||||||
|
end
|
||||||
|
end
|
||||||
mpd_state[key] = v
|
mpd_state[key] = v
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
|
@ -4,6 +4,7 @@
|
||||||
-- Copyright (C) 2017 getzze <getzze@gmail.com>
|
-- Copyright (C) 2017 getzze <getzze@gmail.com>
|
||||||
-- Copyright (C) 2017 mutlusun <mutlusun@github.com>
|
-- Copyright (C) 2017 mutlusun <mutlusun@github.com>
|
||||||
-- Copyright (C) 2019 Nguyễn Gia Phong <vn.mcsinyx@gmail.com>
|
-- Copyright (C) 2019 Nguyễn Gia Phong <vn.mcsinyx@gmail.com>
|
||||||
|
-- Copyright (C) 2020 Elmeri Niemelä <niemela.elmeri@gmail.com>
|
||||||
--
|
--
|
||||||
-- This file is part of Vicious.
|
-- This file is part of Vicious.
|
||||||
--
|
--
|
||||||
|
@ -30,14 +31,14 @@ local helpers = require("vicious.helpers")
|
||||||
local pkg_all = {}
|
local pkg_all = {}
|
||||||
|
|
||||||
local PKGMGR = {
|
local PKGMGR = {
|
||||||
["Arch"] = { cmd = "pacman -Qu" },
|
["Arch"] = { cmd = "pacman -Qu", sub = 0 },
|
||||||
["Arch C"] = { cmd = "checkupdates" },
|
["Arch C"] = { cmd = "checkupdates", sub = 0 },
|
||||||
["Arch S"] = { cmd = "yes | pacman -Sup", sub = 1 },
|
["Arch S"] = { cmd = "yes | pacman -Sup", sub = 1 },
|
||||||
["Debian"] = { cmd = "apt list --upgradable", sub = 1 },
|
["Debian"] = { cmd = "apt list --upgradable", sub = 1 },
|
||||||
["Ubuntu"] = { cmd = "apt list --upgradable", sub = 1 },
|
["Ubuntu"] = { cmd = "apt list --upgradable", sub = 1 },
|
||||||
["Fedora"] = { cmd = "dnf check-update", sub = 2 },
|
["Fedora"] = { cmd = "dnf check-update", sub = 2 },
|
||||||
["FreeBSD"] = { cmd = "pkg version -I -l '<'" },
|
["FreeBSD"] = { cmd = "pkg version -I -l '<'", sub = 0 },
|
||||||
["Mandriva"] = { cmd = "urpmq --auto-select" }
|
["Mandriva"] = { cmd = "urpmq --auto-select", sub = 0 }
|
||||||
}
|
}
|
||||||
|
|
||||||
-- {{{ Packages widget type
|
-- {{{ Packages widget type
|
||||||
|
|
Loading…
Reference in New Issue