Skip to content

Commit 2a8f987

Browse files
McSinyxMcSinyx
committed
[docs] Move basic instructions from README
1 parent b7d08fc commit 2a8f987

File tree

4 files changed

+134
-120
lines changed

4 files changed

+134
-120
lines changed

‎README.md‎

Lines changed: 0 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -13,126 +13,6 @@ Lua libraries, but may depend on additional system utilities (see widget
1313
description).
1414

1515

16-
## Usage
17-
18-
When provided by an operating system package, or installed from source
19-
into the Lua library path Vicious, can be used as a regular Lua
20-
library, to be used stand-alone or to feed widgets of any window
21-
manager (e.g. Ion, WMII). It is compatible with Lua version 5.1 and above.
22-
23-
```lua
24-
> widgets = require("vicious.widgets.init")
25-
> print(widgets.volume(nil, "Master")[1])
26-
100
27-
```
28-
29-
30-
## Usage within Awesome
31-
32-
To use Vicious with Awesome, install the package from your operating
33-
system provider, or download the source code and move it to your
34-
awesome configuration directory in `$XDG_CONFIG_HOME` (usually `~/.config`):
35-
36-
```bash
37-
$ git clone https://github.com/vicious-widgets/vicious.git
38-
$ mv vicious $XDG_CONFIG_HOME/awesome/
39-
```
40-
41-
Vicious will only load modules for widget types you intend to use in
42-
your awesome configuration, to avoid having useless modules sitting in
43-
your memory.
44-
45-
Then add the following to the top of your `rc.lua`:
46-
47-
```lua
48-
local vicious = require("vicious")
49-
```
50-
51-
### Register a widget
52-
53-
Once you create a widget (a textbox, graph or a progressbar) call
54-
`vicious.register()` to register it with Vicious:
55-
56-
vicious.register(widget, wtype, format, interval, warg)
57-
58-
#### widget
59-
60-
*Awesome* widget created with `widget()` or `awful.widget()` (in case of a
61-
graph or a progressbar).
62-
63-
#### wtype
64-
65-
Type: Vicious widget or `function`:
66-
67-
* Vicious widget type: any of the available (default, or custom)
68-
[widget type provided by Vicious](#widgets).
69-
* function: custom function from your own *Awesome* configuration can be
70-
registered as widget types (see [Custom widget types](#custom-widget)).
71-
72-
#### format
73-
74-
Type: `string` or `function`:
75-
76-
* string: `$key` will be replaced by respective value in the table `t` returned
77-
by the widget type. I.e. use `$1`, `$2`, etc. to retrieve data from an
78-
integer-indexed table (a.k.a. array); `${foo bar}` will be substituted by
79-
`t["{foo bar}"]`.
80-
* `function (widget, args)` can be used to manipulate data returned by the
81-
widget type (see [Format functions](#format-func)).
82-
83-
#### interval
84-
85-
Number of seconds between updates of the widget (default: 2). Read section
86-
[Power and Caching](#power) for more information.
87-
88-
#### warg
89-
90-
Some widget types require an argument to be passed, for example the battery ID.
91-
92-
`vicious.register` alone is not much different from
93-
[awful.widget.watch](https://awesomewm.org/doc/api/classes/awful.widget.watch.html),
94-
which has been added to Awesome since version 4.0. However, Vicious offers more
95-
advanced control of widgets' behavior by providing the following functions.
96-
97-
### Unregister a widget
98-
99-
vicious.unregister(widget, keep)
100-
101-
If `keep == true`, `widget` will be suspended and wait for activation.
102-
103-
### Suspend all widgets
104-
105-
vicious.suspend()
106-
107-
See [example automation script](http://sysphere.org/~anrxc/local/sources/lmt-vicious.sh)
108-
for the "laptop-mode-tools" start-stop module.
109-
110-
### Restart suspended widgets
111-
112-
vicious.activate(widget)
113-
114-
If `widget` is provided only that widget will be activated.
115-
116-
### Enable caching of a widget type
117-
118-
vicious.cache(wtype)
119-
120-
Enable caching of values returned by a widget type.
121-
122-
### Force update of widgets
123-
124-
vicious.force(wtable)
125-
126-
`wtable` is a table of one or more widgets to be updated.
127-
128-
### Get data from a widget
129-
130-
vicious.call(wtype, format, warg)
131-
132-
Fetch data from `wtype` to use it outside from the wibox
133-
([example](#call-example)).
134-
135-
13616
## <a name="widgets"></a>Widget types
13717

13818
Widget types consist of worker functions that take two arguments `format` and

‎docs/source/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ library, but may depend on additional system utilities.
1616
:maxdepth: 2
1717
:caption: Contents:
1818

19+
usage-lua
20+
usage-awesome
1921
copying
2022

2123
Indices and tables

‎docs/source/usage-awesome.rst‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
Usage within Awesome
2+
====================
3+
4+
To use Vicious with Awesome, install the package from your operating system
5+
provider, or download the source code and move it to your awesome
6+
configuration directory in ``$XDG_CONFIG_HOME`` (usually ``~/.config``)::
7+
8+
git clone https://github.com/vicious-widgets/vicious.git
9+
mv vicious $XDG_CONFIG_HOME/awesome/
10+
11+
Vicious will only load modules for widget types you intend to use in
12+
your awesome configuration, to avoid having useless modules sitting in
13+
your memory.
14+
15+
Then add the following to the top of your ``rc.lua``:
16+
17+
.. code-block:: lua
18+
19+
local vicious = require("vicious")
20+
21+
Register a Widget
22+
-----------------
23+
24+
Once you create a widget (a textbox, graph or a progressbar) call
25+
``vicious.register()`` to register it with Vicious::
26+
27+
vicious.register(widget, wtype, format, interval, warg)
28+
29+
``widget``
30+
Awesome_ widget created with ``widget()`` or ``awful.widget()``
31+
(in case of a graph or a progressbar).
32+
33+
``wtype`` of type Vicious widget or ``function``
34+
* Vicious widget type: any of the available (default, or custom)
35+
[widget type provided by Vicious](#widgets).
36+
* function: custom function from your own *Awesome* configuration can be
37+
registered as widget types (see [Custom widget types](#custom-widget)).
38+
39+
``format`` of type ``string`` or ``function``
40+
* string: ``$key`` will be replaced by respective value in the table ``t``
41+
returned by the widget type. I.e. use ``$1``, ``$2``, etc. to retrieve data
42+
from an integer-indexed table (a.k.a. array); ``${foo bar}`` will be
43+
substituted by ``t["{foo bar}"]``.
44+
* ``function (widget, args)`` can be used to manipulate data returned by the
45+
widget type (see [Format functions](#format-func)).
46+
47+
``interval``
48+
Number of seconds between updates of the widget (default: 2).
49+
Read section [Power and Caching](#power) for more information.
50+
51+
``warg``
52+
Arguments to be passed to widget types, e.g. the battery ID.
53+
54+
``vicious.register`` alone is not much different from awful.widget.watch_,
55+
which has been added to Awesome since version 4.0. However, Vicious offers
56+
more advanced control of widgets' behavior by providing the following functions.
57+
58+
Unregister a Widget
59+
-------------------
60+
61+
::
62+
63+
vicious.unregister(widget, keep)
64+
65+
If ``keep == true``, ``widget`` will be suspended and wait for activation.
66+
67+
Suspend All Widgets
68+
-------------------
69+
70+
::
71+
72+
vicious.suspend()
73+
74+
See `example automation script`_ for the "laptop-mode-tools" start-stop module.
75+
76+
Restart Suspended Widgets
77+
-------------------------
78+
79+
::
80+
81+
vicious.activate(widget)
82+
83+
If ``widget`` is provided only that widget will be activated.
84+
85+
Enable Caching of a Widget Type
86+
-------------------------------
87+
88+
::
89+
90+
vicious.cache(wtype)
91+
92+
Enable caching of values returned by a widget type.
93+
94+
Force update of widgets
95+
-----------------------
96+
97+
::
98+
99+
vicious.force(wtable)
100+
101+
where ``wtable`` is a table of one or more widgets to be updated.
102+
103+
Get Data from a Widget
104+
----------------------
105+
106+
::
107+
108+
vicious.call(wtype, format, warg)
109+
110+
Fetch data from ``wtype`` to use it outside from the wibox
111+
([example](#call-example)).
112+
113+
.. _Awesome: https://awesomewm.org/
114+
.. _awful.widget.watch:
115+
https://awesomewm.org/doc/api/classes/awful.widget.watch.html
116+
.. _example automation script:
117+
http://sysphere.org/~anrxc/local/sources/lmt-vicious.sh

‎docs/source/usage-lua.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Usage as a Lua Library
2+
======================
3+
4+
When provided by an operating system package, or installed from source
5+
into the Lua library path, Vicious can be used as a regular Lua_ library,
6+
to be used stand-alone or to feed widgets of any window manager
7+
(e.g. Ion, WMII). It is compatible with Lua 5.1 and above.
8+
9+
.. code-block:: lua
10+
11+
> widgets = require("vicious.widgets.init")
12+
> print(widgets.volume(nil, "Master")[1])
13+
100
14+
15+
.. _Lua: https://www.lua.org/

0 commit comments

Comments
 (0)