diff --git a/Changes.md b/Changes.md index 249ce37..de920ba 100644 --- a/Changes.md +++ b/Changes.md @@ -28,6 +28,7 @@ Fixed: * 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) diff --git a/README.md b/README.md index ad391b3..320d584 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,7 @@ 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: - -* https://github.com/vicious-widgets/vicious +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, @@ -14,12 +12,13 @@ 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 description). + ## Usage 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 both Lua v5.1 and v5.2. +manager (e.g. Ion, WMII). It is compatible with Lua version 5.1 and above. ```lua > widgets = require("vicious.widgets.init") @@ -27,6 +26,7 @@ manager (e.g. Ion, WMII). It is compatible with both Lua v5.1 and v5.2. 100 ``` + ## Usage within Awesome To use Vicious with Awesome, install the package from your operating @@ -34,6 +34,7 @@ system provider, or download the source code and move it to your 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/ ``` @@ -47,17 +48,19 @@ Then add the following to the top of your `rc.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 +#### widget *Awesome* widget created with `widget()` or `awful.widget()` (in case of a graph or a progressbar). -### wtype +#### wtype Type: Vicious widget or `function`: @@ -66,7 +69,7 @@ Type: Vicious widget or `function`: * function: custom function from your own *Awesome* configuration can be registered as widget types (see [Custom widget types](#custom-widget)). -### format +#### format Type: `string` or `function`: @@ -77,17 +80,15 @@ Type: `string` or `function`: * `function (widget, args)` can be used to manipulate data returned by the widget type (see [Format functions](#format-func)). -### interval +#### interval Number of seconds between updates of the widget (default: 2). Read section [Power and Caching](#power) for more information. -### warg +#### warg Some widget types require an argument to be passed, for example the battery ID. -## Other functions - `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 @@ -131,6 +132,7 @@ Enable caching of values returned by a widget type. Fetch data from `wtype` to use it outside from the wibox ([example](#call-example)). + ## Widget types Widget types consist of worker functions that take two arguments `format` and @@ -370,9 +372,11 @@ 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}`, +* 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 @@ -543,6 +547,7 @@ Supported platforms: GNU/Linux. `${rate}` (Mb/s), `${freq}` (MHz), `${linp}` (link quality in percent), `${txpw}` (transmission power, in dBm) and `${sign}` (signal level, in dBm) + ## Custom widget types Use any of the existing widget types as a starting point for your @@ -628,6 +633,7 @@ 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 @@ -716,6 +722,7 @@ cpuwidget:set_color{type = "linear", from = {0, 0}, to = {50, 0}, vicious.register(cpuwidget, vicious.widgets.cpu, "$1", 3) ``` + ## Format functions You can use a function instead of a string as the format parameter. @@ -846,6 +853,7 @@ mybattery:buttons(awful.util.table.join( end))) ``` + ## See also * Manual pages: [awesome(1)](https://awesomewm.org/doc/manpages/awesome), @@ -855,6 +863,7 @@ mybattery:buttons(awful.util.table.join( (outdated) * [My first awesome](https://awesomewm.org/doc/api/documentation/07-my-first-awesome.md.html) + ## Authors Wicked was written by: @@ -872,15 +881,63 @@ Current maintainers: * Daniel Hahler (blueyed) \ * Nguyễn Gia Phong (McSinyx) \ -Vicious major contributors: +Contributors, listed in alphabetic order: -* Benedikt Sauer \ -* Greg D. \ -* Henning Glawe \ -* Rémy C. \ -* Hiltjo Posthuma \ -* Hagen Schink \ +* 0x5b \ +* Adam Lee \ +* Alexander Koch \ +* Amir Mohammad Saied \ +* Andrea Scarpino \ +* Andreas Geisenhainer \ +* Andrew Merenbach \ +* Andrzej Bieniek \ +* Arthur Axel 'fREW' Schmidt \ * Arvydas Sidorenko \ +* Benedikt Sauer \ +* Beniamin Kalinowski \ +* Benoît Zugmeyer \ +* blastmaster \ +* Brandon Hartshorn \ +* crondog \ +* David Udelson \ * Dodo The Last \ -* … -* Consult git log for a complete list of contributors +* Elric Milon \ +* Enric Morales \ +* getzze \ +* Greg D. \ +* Hagen Schink \ +* Henning Glawe \ +* Hiltjo Posthuma \ +* [James Reed](https://github.com/supplantr) +* Jay Kamat \ +* Jeremy \ +* jinleileiking \ +* joe di castro \ +* Joerg Jaspert \ +* Jonathan McCrohan \ +* [Juan Carlos Menonita](https://github.com/JuanKman94) +* Juergen Descher \ +* Julian Volodia \ +* Keith Hughitt \ +* Lorenzo Gaggini \ +* Lyderic Lefever \ +* Martin Striz \ +* Martin Ueding \ +* Mellich \ +* Michael Kressibucher \ +* Michael Unterkalmsteiner \ +* niko \ +* Noah Tilton \ +* Normal Ra \ +* Perry Hargrave \ +* Rémy CLOUARD \ +* [Roberto](https://github.com/empijei) +* Sébastien Luttringer \ +* Shadowmourne G \ +* starenka \ +* Suseika \ +* Uli Schlachter \ +* Wtfcoder \ +* Xaver Hellauer \ +* zhrtz \ +* And many others