[docs] Move format function guide from README
This commit is contained in:
parent
5f87644d28
commit
897ebe97b7
131
README.md
131
README.md
|
|
@ -102,137 +102,6 @@ vicious.register(cpuwidget, vicious.widgets.cpu, "$1", 3)
|
|||
```
|
||||
|
||||
|
||||
## <a name="format-func"></a>Format functions
|
||||
|
||||
You can use a function instead of a string as the format parameter.
|
||||
Then you are able to check the value returned by the widget type and
|
||||
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.
|
||||
|
||||
The format function will get the widget as its first argument, table
|
||||
with the values otherwise inserted into the format string as its
|
||||
second argument, and will return the text/data to be used for the
|
||||
widget.
|
||||
|
||||
### Examples
|
||||
|
||||
#### Hide mpd widget when no song is playing
|
||||
|
||||
```lua
|
||||
mpdwidget = wibox.widget.textbox()
|
||||
vicious.register(
|
||||
mpdwidget,
|
||||
vicious.widgets.mpd,
|
||||
function (widget, args)
|
||||
if args["{state}"] == "Stop" then
|
||||
return ''
|
||||
else
|
||||
return ('<span color="white">MPD:</span> %s - %s'):format(
|
||||
args["{Artist}"], args["{Title}"])
|
||||
end
|
||||
end)
|
||||
```
|
||||
|
||||
#### Use string.format for padding
|
||||
|
||||
```lua
|
||||
uptimewidget = wibox.widget.textbox()
|
||||
vicious.register(uptimewidget, vicious.widgets.uptime,
|
||||
function (widget, args)
|
||||
return ("Uptime: %02d %02d:%02d "):format(
|
||||
args[1], args[2], args[3])
|
||||
end, 61)
|
||||
```
|
||||
|
||||
When it comes to padding it is also useful to mention how a widget can be
|
||||
configured to have a fixed width. You can set a fixed width on your textbox
|
||||
widgets by changing their `width` field (by default width is automatically
|
||||
adapted to text width). The following code forces a fixed width of 50 px to the
|
||||
uptime widget, and aligns its text to the right:
|
||||
|
||||
```lua
|
||||
uptimewidget = wibox.widget.textbox()
|
||||
uptimewidget.width, uptimewidget.align = 50, "right"
|
||||
vicious.register(uptimewidget, vicious.widgets.uptime, "$1 $2:$3", 61)
|
||||
```
|
||||
|
||||
#### Stacked graph
|
||||
|
||||
Stacked graphs are handled specially by Vicious: `format` functions passed to
|
||||
the corresponding widget types must return an array instead of a string.
|
||||
|
||||
```lua
|
||||
cpugraph = wibox.widget.graph()
|
||||
cpugraph:set_stack(true)
|
||||
cpugraph:set_stack_colors({"red", "yellow", "green", "blue"})
|
||||
vicious.register(cpugraph, vicious.widgets.cpu,
|
||||
function (widget, args)
|
||||
return {args[2], args[3], args[4], args[5]}
|
||||
end, 3)
|
||||
```
|
||||
|
||||
The snipet above enables graph stacking/multigraph and plots usage of all four
|
||||
CPU cores on a single graph.
|
||||
|
||||
#### Substitute widget types' symbols
|
||||
|
||||
If you are not happy with default symbols used in volume, battery, cpufreq and
|
||||
other widget types, use your own symbols without any need to modify modules.
|
||||
The following example uses a custom table map to modify symbols representing
|
||||
the mixer state: on or off/mute.
|
||||
|
||||
```lua
|
||||
volumewidget = wibox.widget.textbox()
|
||||
vicious.register(volumewidget, vicious.widgets.volume,
|
||||
function (widget, args)
|
||||
local label = {["♫"] = "O", ["♩"] = "M"}
|
||||
return ("Volume: %d%% State: %s"):format(
|
||||
args[1], label[args[2]])
|
||||
end, 2, "PCM")
|
||||
```
|
||||
|
||||
#### <a name="call-example"></a>Get data from the widget
|
||||
|
||||
`vicious.call` could be useful for naughty notification and scripts:
|
||||
|
||||
```lua
|
||||
mybattery = wibox.widget.textbox()
|
||||
vicious.register(mybattery, vicious.widgets.bat, "$2%", 17, "0")
|
||||
mybattery:buttons(awful.util.table.join(
|
||||
awful.button(
|
||||
{}, 1,
|
||||
function ()
|
||||
naughty.notify{title = "Battery indicator",
|
||||
text = vicious.call(vicious.widgets.bat,
|
||||
"Remaining time: $3", "0")}
|
||||
end)))
|
||||
```
|
||||
|
||||
Format functions can be used as well:
|
||||
|
||||
```lua
|
||||
mybattery:buttons(awful.util.table.join(
|
||||
awful.button(
|
||||
{}, 1,
|
||||
function ()
|
||||
naughty.notify{
|
||||
title = "Battery indicator",
|
||||
text = vicious.call(
|
||||
vicious.widgets.bat,
|
||||
function (widget, args)
|
||||
return ("%s: %10sh\n%s: %14d%%\n%s: %12dW"):format(
|
||||
"Remaining time", args[3],
|
||||
"Wear level", args[4],
|
||||
"Present rate", args[5])
|
||||
end, "0")}
|
||||
end)))
|
||||
```
|
||||
|
||||
|
||||
## Contributing
|
||||
|
||||
For details, see CONTRIBUTING.md. Vicious is licensed under GNU GPLv2+,
|
||||
|
|
|
|||
|
|
@ -0,0 +1,137 @@
|
|||
.. _format-func:
|
||||
|
||||
Format Functions
|
||||
================
|
||||
|
||||
You can use a function instead of a string as the format parameter.
|
||||
Then you are able to check the value returned by the widget type
|
||||
and 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.
|
||||
|
||||
The format function will get the widget as its first argument, table with
|
||||
the values otherwise inserted into the format string as its second argument,
|
||||
and will return the text/data to be used for the widget.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
Hide mpd widget when no song is playing
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
mpdwidget = wibox.widget.textbox()
|
||||
vicious.register(
|
||||
mpdwidget,
|
||||
vicious.widgets.mpd,
|
||||
function (widget, args)
|
||||
if args["{state}"] == "Stop" then
|
||||
return ''
|
||||
else
|
||||
return ('<span color="white">MPD:</span> %s - %s'):format(
|
||||
args["{Artist}"], args["{Title}"])
|
||||
end
|
||||
end)
|
||||
|
||||
Use string.format for padding
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
uptimewidget = wibox.widget.textbox()
|
||||
vicious.register(uptimewidget, vicious.widgets.uptime,
|
||||
function (widget, args)
|
||||
return ("Uptime: %02d %02d:%02d "):format(
|
||||
args[1], args[2], args[3])
|
||||
end, 61)
|
||||
|
||||
When it comes to padding it is also useful to mention how a widget
|
||||
can be configured to have a fixed width. You can set a fixed width on
|
||||
your textbox widgets by changing their ``width`` field (by default width
|
||||
is automatically adapted to text width). The following code forces
|
||||
a fixed width of 50 px to the uptime widget, and aligns its text to the right:
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
uptimewidget = wibox.widget.textbox()
|
||||
uptimewidget.width, uptimewidget.align = 50, "right"
|
||||
vicious.register(uptimewidget, vicious.widgets.uptime, "$1 $2:$3", 61)
|
||||
|
||||
Stacked graph
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
Stacked graphs are handled specially by Vicious: ``format`` functions passed
|
||||
to the corresponding widget types must return an array instead of a string.
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
cpugraph = wibox.widget.graph()
|
||||
cpugraph:set_stack(true)
|
||||
cpugraph:set_stack_colors{ "red", "yellow", "green", "blue" }
|
||||
vicious.register(cpugraph, vicious.widgets.cpu,
|
||||
function (widget, args)
|
||||
return { args[2], args[3], args[4], args[5] }
|
||||
end, 3)
|
||||
|
||||
The snipet above enables graph stacking/multigraph and plots usage of all four
|
||||
CPU cores on a single graph.
|
||||
|
||||
Substitute widget types' symbols
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you are not happy with default symbols used in volume, battery, cpufreq and
|
||||
other widget types, use your own symbols without any need to modify modules.
|
||||
The following example uses a custom table map to modify symbols representing
|
||||
the mixer state: on or off/mute.
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
volumewidget = wibox.widget.textbox()
|
||||
vicious.register(volumewidget, vicious.widgets.volume,
|
||||
function (widget, args)
|
||||
local label = { ["🔉"] = "O", ["🔈"] = "M" }
|
||||
return ("Volume: %d%% State: %s"):format(
|
||||
args[1], label[args[2]])
|
||||
end, 2, "PCM")
|
||||
|
||||
.. _call-example:
|
||||
|
||||
Get data from the widget
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
:lua:func:`vicious.call` could be useful for naughty notification and scripts:
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
mybattery = wibox.widget.textbox()
|
||||
vicious.register(mybattery, vicious.widgets.bat, "$2%", 17, "0")
|
||||
mybattery:buttons(awful.util.table.join(awful.button(
|
||||
{}, 1,
|
||||
function ()
|
||||
naughty.notify{ title = "Battery indicator",
|
||||
text = vicious.call(vicious.widgets.bat,
|
||||
"Remaining time: $3", "0") }
|
||||
end)))
|
||||
|
||||
Format functions can be used as well:
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
mybattery:buttons(awful.util.table.join(awful.button(
|
||||
{}, 1,
|
||||
function ()
|
||||
naughty.notify{
|
||||
title = "Battery indicator",
|
||||
text = vicious.call(
|
||||
vicious.widgets.bat,
|
||||
function (widget, args)
|
||||
return ("%s: %10sh\n%s: %14d%%\n%s: %12dW"):format(
|
||||
"Remaining time", args[3],
|
||||
"Wear level", args[4],
|
||||
"Present rate", args[5])
|
||||
end, "0") }
|
||||
end)))
|
||||
|
|
@ -16,12 +16,13 @@ Table of Contents
|
|||
-----------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:titlesonly:
|
||||
|
||||
usage-lua
|
||||
usage-awesome
|
||||
widgets
|
||||
custom
|
||||
format
|
||||
caching
|
||||
security
|
||||
copying
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ call ``vicious.register`` to register it with Vicious:
|
|||
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)).
|
||||
by the widget type (see :ref:`format-func`).
|
||||
|
||||
:param interval: number of seconds between updates of the widget
|
||||
(default: 2). See :ref:`caching` for more information.
|
||||
|
|
@ -111,7 +111,7 @@ vicious.call
|
|||
.. lua:function:: vicious.call(wtype, format, warg)
|
||||
|
||||
Fetch data from the widget type to use it outside of the widget
|
||||
([example](#call-example)).
|
||||
(:ref:`example <call-example>`).
|
||||
|
||||
:param wtype:
|
||||
either of
|
||||
|
|
@ -130,7 +130,7 @@ vicious.call
|
|||
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)).
|
||||
by the widget type (see :ref:`format-func`).
|
||||
|
||||
:param warg: arguments to be passed to widget types, e.g. the battery ID.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue