[docs] Move basic instructions from README
This commit is contained in:
parent
b7d08fc84b
commit
2a8f987b22
120
README.md
120
README.md
|
|
@ -13,126 +13,6 @@ 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 Lua version 5.1 and above.
|
||||
|
||||
```lua
|
||||
> widgets = require("vicious.widgets.init")
|
||||
> print(widgets.volume(nil, "Master")[1])
|
||||
100
|
||||
```
|
||||
|
||||
|
||||
## 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`):
|
||||
|
||||
```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
|
||||
|
|
|
|||
|
|
@ -16,6 +16,8 @@ library, but may depend on additional system utilities.
|
|||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
usage-lua
|
||||
usage-awesome
|
||||
copying
|
||||
|
||||
Indices and tables
|
||||
|
|
|
|||
|
|
@ -0,0 +1,117 @@
|
|||
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")
|
||||
|
||||
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`` of 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`` of 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``
|
||||
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.
|
||||
|
||||
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`_ 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)
|
||||
|
||||
where ``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)).
|
||||
|
||||
.. _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/
|
||||
Loading…
Reference in New Issue