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
```
Usage within Awesome
--------------------
To use Vicious with Awesome, install the package from your operating
@ -69,33 +70,31 @@ vicious.register(widget, wtype, format, interval, warg)
**wtype**
- widget type or a function
* any of the available (default, or custom) widget types can
be used here, see below for a list of those provided by
Vicious
* any of the available (default, or custom) widget types can be used here,
see below for a list of those provided by Vicious
- function
* custom functions from your own "awesome" configuration can
be registered as widget types, see the "Custom widget types"
section
* custom functions from your own "awesome" configuration can be registered
as widget types, see the "Custom widget types" section
**format**
- string argument or a function
* $1, $2, $3... will be replaced by their respective value
returned by the widget type, some widget types return tables
with string keys, in that case use: ${key}
* $1, $2, $3... will be replaced by their respective value returned by the
widget type, some widget types return tables with string keys, in that
case use: ${key}
- function
* function(widget, args) can be used to manipulate data
returned by the widget type, more about this below
* function(widget, args) can be used to manipulate data returned by the
widget type, more about this below
**interval**
- number of seconds between updates of the widget, 2s by
default, also read the "Power" section below
- number of seconds between updates of the widget, 2s by default, also read
the "Power" section below
**warg**
- some widget types require an argument to be passed, for example
the battery ID
- some widget types require an argument to be passed, for example the battery
ID
Other functions
@ -152,15 +151,53 @@ Provides state, charge, and remaining time for a requested battery.
Supported platforms: Linux, FreeBSD.
- Arguments (per platform):
- Linux: takes battery ID as an argument, i.e. "BAT0"
- FreeBSD: no arguments needed
* Linux: takes battery ID as an argument, i.e. "BAT0"
* FreeBSD: no arguments needed
- 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
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`
**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**
- 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
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**
- 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},
{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**
- provides weather information for a requested station
@ -351,15 +371,6 @@ Supported platforms: Linux, FreeBSD.
{windkmh}, {sky}, {weather}, {tempf}, {tempc}, {humid}, {dewf},
{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
-------------------
@ -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
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. 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.
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/
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
@ -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
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.
- 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.
- 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
@ -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
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.
- 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