diff --git a/README.md b/README.md index 133fbe5..e992b3c 100644 --- a/README.md +++ b/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)). - - ## Widget types Widget types consist of worker functions that take two arguments `format` and diff --git a/docs/source/index.rst b/docs/source/index.rst index a0f206f..cfec428 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,6 +16,8 @@ library, but may depend on additional system utilities. :maxdepth: 2 :caption: Contents: + usage-lua + usage-awesome copying Indices and tables diff --git a/docs/source/usage-awesome.rst b/docs/source/usage-awesome.rst new file mode 100644 index 0000000..aa45071 --- /dev/null +++ b/docs/source/usage-awesome.rst @@ -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 diff --git a/docs/source/usage-lua.rst b/docs/source/usage-lua.rst new file mode 100644 index 0000000..116886e --- /dev/null +++ b/docs/source/usage-lua.rst @@ -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/