awesomewm-mirrors
/
vicious
mirror of https://github.com/vicious-widgets/vicious.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

update readme file

This commit is contained in:
mutlusun 2016-12-22 20:56:10 +01:00
parent e28e2760c4
commit 47572e9334
1 changed files with 98 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
README.md
View File

@ -36,6 +36,7 @@ manager (ie. Ion, WMII). It is compatible with both Lua v5.1 and v5.2.
100 100
``` ```
Usage within Awesome Usage within Awesome
-------------------- --------------------
To use Vicious with Awesome, install the package from your operating To use Vicious with Awesome, install the package from your operating
@ -69,33 +70,31 @@ vicious.register(widget, wtype, format, interval, warg)
**wtype** **wtype**
- widget type or a function - widget type or a function
* any of the available (default, or custom) widget types can * any of the available (default, or custom) widget types can be used here,
be used here, see below for a list of those provided by see below for a list of those provided by Vicious
Vicious
- function - function
* custom functions from your own "awesome" configuration can * custom functions from your own "awesome" configuration can be registered
be registered as widget types, see the "Custom widget types" as widget types, see the "Custom widget types" section
section
**format** **format**
- string argument or a function - string argument or a function
* $1, $2, $3... will be replaced by their respective value * $1, $2, $3... will be replaced by their respective value returned by the
returned by the widget type, some widget types return tables widget type, some widget types return tables with string keys, in that
with string keys, in that case use: ${key} case use: ${key}
- function - function
* function(widget, args) can be used to manipulate data * function(widget, args) can be used to manipulate data returned by the
returned by the widget type, more about this below widget type, more about this below
**interval** **interval**
- number of seconds between updates of the widget, 2s by - number of seconds between updates of the widget, 2s by default, also read
default, also read the "Power" section below the "Power" section below
**warg** **warg**
- some widget types require an argument to be passed, for example - some widget types require an argument to be passed, for example the battery
the battery ID ID
Other functions Other functions
@ -152,15 +151,53 @@ Provides state, charge, and remaining time for a requested battery.
Supported platforms: Linux, FreeBSD. Supported platforms: Linux, FreeBSD.
- Arguments (per platform): - Arguments (per platform):
- Linux: takes battery ID as an argument, i.e. "BAT0" * Linux: takes battery ID as an argument, i.e. "BAT0"
- FreeBSD: no arguments needed * FreeBSD: no arguments needed
- Returns (per platform): - Returns (per platform):
- Linux: returns 1st value as state of requested battery, 2nd as charge * Linux: returns 1st value as state of requested battery, 2nd as charge
level in percent, 3rd as remaining (charging or discharging) time and 4th level in percent, 3rd as remaining (charging or discharging) time and 4th
as the wear level in percent as the wear level in percent
- FreeBSD: see Linux, but wear level is not supported right now and always * FreeBSD: see Linux, but wear level is not supported right now and always
set to `0` set to `0`
**vicious.widgets.date**
Provides access to os.date, with optional time formatting provided as the
format string - using regular date sequences.
Supported platforms: platform independent.
- Arguments:
* takes optional time offset, in seconds, as an argument for example to
calculate time zone differences, otherwise current time is formatted
- Returns:
* returns the output of os.date, formatted by provided sequences
**vicious.widgets.fs**
Provides usage of file system disk space.
Supported platforms: platform independent.
- Arguments:
* takes an (optional) argument which, if true, includes remote file systems,
only local file systems are included by default
- Returns:
* returns a table with string keys, using mount points as a base:
`{/ size_mb}`, `{/ size_gb}`, `{/ used_mb}`, ``{/ used_gb}, `{/ used_p}`,
`{/ avail_mb}`, `{/ avail_gb}`, `{/ avail_p}`, `{/home size_mb}` etc.
**vicious.widgets.volume**
Provides volume levels and state of requested mixers.
Supported platforms: Linux, FreeBSD.
- Arguments (per platform):
* Linux: takes the ALSA mixer control as an argument, i.e. `"Master"`,
optionally append the card ID or other options, i.e. `"PCM -c 0"`
* FreeBSD: takes the mixer control as an argument, i.e. `"vol"`
- Returns:
* returns 1st value as the volume level and 2nd as the mute state of the
requested channel
**vicious.widgets.cpu** **vicious.widgets.cpu**
- provides CPU usage for all available CPUs/cores - provides CPU usage for all available CPUs/cores
@ -214,15 +251,6 @@ Supported platforms: Linux, FreeBSD.
available system entropy and 6th value as available entropy in available system entropy and 6th value as available entropy in
percent percent
**vicious.widgets.fs**
- provides file system disk space usage
- takes an (optional) argument which, if true, includes remote file
systems, only local file systems are included by default
- returns a table with string keys, using mount points as a base:
{/ size_mb}, {/ size_gb}, {/ used_mb}, {/ used_gb}, {/ used_p},
{/ avail_mb}, {/ avail_gb}, {/ avail_p}, {/home size_mb} etc.
**vicious.widgets.dio** **vicious.widgets.dio**
- provides I/O statistics for all available storage devices - provides I/O statistics for all available storage devices
@ -335,14 +363,6 @@ Supported platforms: Linux, FreeBSD.
- returns a table with string keys: {volume}, {state}, {Artist}, - returns a table with string keys: {volume}, {state}, {Artist},
{Title}, {Album}, {Genre} and optionally {Name} and {file} {Title}, {Album}, {Genre} and optionally {Name} and {file}
**vicious.widgets.volume**
- provides volume levels and state of requested ALSA mixers
- takes the ALSA mixer control as an argument, i.e. "Master",
optionally append the card ID or other options, i.e. "PCM -c 0"
- returns 1st value as the volume level and 2nd as the mute state of
the requested channel
**vicious.widgets.weather** **vicious.widgets.weather**
- provides weather information for a requested station - provides weather information for a requested station
@ -351,15 +371,6 @@ Supported platforms: Linux, FreeBSD.
{windkmh}, {sky}, {weather}, {tempf}, {tempc}, {humid}, {dewf}, {windkmh}, {sky}, {weather}, {tempf}, {tempc}, {humid}, {dewf},
{dewc}, {press} {dewc}, {press}
**vicious.widgets.date**
- provides access to os.date, with optional time formatting provided
as the format string - using regular date sequences
- takes optional time offset, in seconds, as an argument for example
to calculate time zone differences, otherwise current time is
formatted
- returns the output of os.date, formatted by provided sequences
Custom widget types Custom widget types
------------------- -------------------
@ -368,18 +379,12 @@ 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 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). defined in rc.lua (or somewhere else, outside the actual module).
Before writing a widget type you should check if there is already one Before writing a widget type you should check if there is already one in the
in the contrib directory of Vicious. The contrib directory contains contrib directory of Vicious. The contrib directory contains extra widgets you
extra widgets you can use. Some are for less common hardware, and can use. Some are for less common hardware, and other were contributed by
other were contributed by Vicious users. The contrib directory also Vicious users. Most of the contrib widgets are obsolete. Contrib widgets will
holds widget types that were obsoleted or rewritten. Contrib widgets not be imported by init unless you explicitly enable it, or load them in your
will not be imported by init unless you explicitly enable it, or load rc.lua.
them in your rc.lua.
Rudi Siegel, a FreeBSD user, published his FreeBSD branch. If you are
also a BSD user you can find his work here:
- https://bitbucket.org/mutluyum/vicious_bsd/
Some users would like to avoid writing new modules. For them Vicious Some users would like to avoid writing new modules. For them Vicious
kept the old Wicked functionality, possibility to register their own kept the old Wicked functionality, possibility to register their own
@ -415,17 +420,15 @@ enables you to have multiple widgets using the same widget type. With
caching its worker function gets executed only once - which is also caching its worker function gets executed only once - which is also
great for saving power. great for saving power.
- Some widget types keep internal data and if you call one multiple - Some widget types keep internal data and if you call one multiple times
times without caching, the widget that executes it first would without caching, the widget that executes it first would modify stored
modify stored values. This can lead to problems and give you values. This can lead to problems and give you inconsistent data. Remember
inconsistent data. Remember it for widget types like CPU and it for widget types like CPU and Network usage, which compare the old set of
Network usage, which compare the old set of data with the new one data with the new one to calculate current usage.
to calculate current usage.
- Widget types that require a widget argument to be passed should be - Widget types that require a widget argument to be passed should be handled
handled carefully. If you are requesting information for different carefully. If you are requesting information for different devices then
devices then caching should not be used, because you could get caching should not be used, because you could get inconsistent data.
inconsistent data.
Security Security
@ -543,8 +546,8 @@ 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 battery widget when it goes below a certain point, hide widgets when
they return a certain value or maybe use string.format for padding. they return a certain value or maybe use string.format for padding.
- Do not confuse this with just coloring the widget, in those cases - Do not confuse this with just coloring the widget, in those cases standard
standard pango markup can be inserted into the format string. pango markup can be inserted into the format string.
The format function will get the widget as its first argument, table The format function will get the widget as its first argument, table
with the values otherwise inserted into the format string as its with the values otherwise inserted into the format string as its