Skip to content

Commit 897ebe9

Browse files
McSinyxMcSinyx
committed
[docs] Move format function guide from README
1 parent 5f87644 commit 897ebe9

File tree

4 files changed

+142
-135
lines changed

4 files changed

+142
-135
lines changed

‎README.md‎

Lines changed: 0 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -102,137 +102,6 @@ vicious.register(cpuwidget, vicious.widgets.cpu, "$1", 3)
102102
```
103103

104104

105-
## <a name="format-func"></a>Format functions
106-
107-
You can use a function instead of a string as the format parameter.
108-
Then you are able to check the value returned by the widget type and
109-
change it or perform some action. You can change the color of the
110-
battery widget when it goes below a certain point, hide widgets when
111-
they return a certain value or maybe use `string.format` for padding.
112-
113-
Do not confuse this with just coloring the widget, in those cases standard
114-
Pango markup can be inserted into the format string.
115-
116-
The format function will get the widget as its first argument, table
117-
with the values otherwise inserted into the format string as its
118-
second argument, and will return the text/data to be used for the
119-
widget.
120-
121-
### Examples
122-
123-
#### Hide mpd widget when no song is playing
124-
125-
```lua
126-
mpdwidget = wibox.widget.textbox()
127-
vicious.register(
128-
mpdwidget,
129-
vicious.widgets.mpd,
130-
function (widget, args)
131-
if args["{state}"] == "Stop" then
132-
return ''
133-
else
134-
return ('<span color="white">MPD:</span> %s - %s'):format(
135-
args["{Artist}"], args["{Title}"])
136-
end
137-
end)
138-
```
139-
140-
#### Use string.format for padding
141-
142-
```lua
143-
uptimewidget = wibox.widget.textbox()
144-
vicious.register(uptimewidget, vicious.widgets.uptime,
145-
function (widget, args)
146-
return ("Uptime: %02d %02d:%02d "):format(
147-
args[1], args[2], args[3])
148-
end, 61)
149-
```
150-
151-
When it comes to padding it is also useful to mention how a widget can be
152-
configured to have a fixed width. You can set a fixed width on your textbox
153-
widgets by changing their `width` field (by default width is automatically
154-
adapted to text width). The following code forces a fixed width of 50 px to the
155-
uptime widget, and aligns its text to the right:
156-
157-
```lua
158-
uptimewidget = wibox.widget.textbox()
159-
uptimewidget.width, uptimewidget.align = 50, "right"
160-
vicious.register(uptimewidget, vicious.widgets.uptime, "$1 $2:$3", 61)
161-
```
162-
163-
#### Stacked graph
164-
165-
Stacked graphs are handled specially by Vicious: `format` functions passed to
166-
the corresponding widget types must return an array instead of a string.
167-
168-
```lua
169-
cpugraph = wibox.widget.graph()
170-
cpugraph:set_stack(true)
171-
cpugraph:set_stack_colors({"red", "yellow", "green", "blue"})
172-
vicious.register(cpugraph, vicious.widgets.cpu,
173-
function (widget, args)
174-
return {args[2], args[3], args[4], args[5]}
175-
end, 3)
176-
```
177-
178-
The snipet above enables graph stacking/multigraph and plots usage of all four
179-
CPU cores on a single graph.
180-
181-
#### Substitute widget types' symbols
182-
183-
If you are not happy with default symbols used in volume, battery, cpufreq and
184-
other widget types, use your own symbols without any need to modify modules.
185-
The following example uses a custom table map to modify symbols representing
186-
the mixer state: on or off/mute.
187-
188-
```lua
189-
volumewidget = wibox.widget.textbox()
190-
vicious.register(volumewidget, vicious.widgets.volume,
191-
function (widget, args)
192-
local label = {["♫"] = "O", ["♩"] = "M"}
193-
return ("Volume: %d%% State: %s"):format(
194-
args[1], label[args[2]])
195-
end, 2, "PCM")
196-
```
197-
198-
#### <a name="call-example"></a>Get data from the widget
199-
200-
`vicious.call` could be useful for naughty notification and scripts:
201-
202-
```lua
203-
mybattery = wibox.widget.textbox()
204-
vicious.register(mybattery, vicious.widgets.bat, "$2%", 17, "0")
205-
mybattery:buttons(awful.util.table.join(
206-
awful.button(
207-
{}, 1,
208-
function ()
209-
naughty.notify{title = "Battery indicator",
210-
text = vicious.call(vicious.widgets.bat,
211-
"Remaining time: $3", "0")}
212-
end)))
213-
```
214-
215-
Format functions can be used as well:
216-
217-
```lua
218-
mybattery:buttons(awful.util.table.join(
219-
awful.button(
220-
{}, 1,
221-
function ()
222-
naughty.notify{
223-
title = "Battery indicator",
224-
text = vicious.call(
225-
vicious.widgets.bat,
226-
function (widget, args)
227-
return ("%s: %10sh\n%s: %14d%%\n%s: %12dW"):format(
228-
"Remaining time", args[3],
229-
"Wear level", args[4],
230-
"Present rate", args[5])
231-
end, "0")}
232-
end)))
233-
```
234-
235-
236105
## Contributing
237106

238107
For details, see CONTRIBUTING.md. Vicious is licensed under GNU GPLv2+,

‎docs/source/format.rst‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
.. _format-func:
2+
3+
Format Functions
4+
================
5+
6+
You can use a function instead of a string as the format parameter.
7+
Then you are able to check the value returned by the widget type
8+
and change it or perform some action. You can change the color of
9+
the battery widget when it goes below a certain point, hide widgets
10+
when they return a certain value or maybe use ``string.format`` for padding.
11+
12+
Do not confuse this with just coloring the widget, in those cases
13+
standard Pango markup can be inserted into the format string.
14+
15+
The format function will get the widget as its first argument, table with
16+
the values otherwise inserted into the format string as its second argument,
17+
and will return the text/data to be used for the widget.
18+
19+
Examples
20+
--------
21+
22+
Hide mpd widget when no song is playing
23+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
24+
25+
.. code-block:: lua
26+
27+
mpdwidget = wibox.widget.textbox()
28+
vicious.register(
29+
mpdwidget,
30+
vicious.widgets.mpd,
31+
function (widget, args)
32+
if args["{state}"] == "Stop" then
33+
return ''
34+
else
35+
return ('<span color="white">MPD:</span> %s - %s'):format(
36+
args["{Artist}"], args["{Title}"])
37+
end
38+
end)
39+
40+
Use string.format for padding
41+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42+
43+
.. code-block:: lua
44+
45+
uptimewidget = wibox.widget.textbox()
46+
vicious.register(uptimewidget, vicious.widgets.uptime,
47+
function (widget, args)
48+
return ("Uptime: %02d %02d:%02d "):format(
49+
args[1], args[2], args[3])
50+
end, 61)
51+
52+
When it comes to padding it is also useful to mention how a widget
53+
can be configured to have a fixed width. You can set a fixed width on
54+
your textbox widgets by changing their ``width`` field (by default width
55+
is automatically adapted to text width). The following code forces
56+
a fixed width of 50 px to the uptime widget, and aligns its text to the right:
57+
58+
.. code-block:: lua
59+
60+
uptimewidget = wibox.widget.textbox()
61+
uptimewidget.width, uptimewidget.align = 50, "right"
62+
vicious.register(uptimewidget, vicious.widgets.uptime, "$1 $2:$3", 61)
63+
64+
Stacked graph
65+
^^^^^^^^^^^^^
66+
67+
Stacked graphs are handled specially by Vicious: ``format`` functions passed
68+
to the corresponding widget types must return an array instead of a string.
69+
70+
.. code-block:: lua
71+
72+
cpugraph = wibox.widget.graph()
73+
cpugraph:set_stack(true)
74+
cpugraph:set_stack_colors{ "red", "yellow", "green", "blue" }
75+
vicious.register(cpugraph, vicious.widgets.cpu,
76+
function (widget, args)
77+
return { args[2], args[3], args[4], args[5] }
78+
end, 3)
79+
80+
The snipet above enables graph stacking/multigraph and plots usage of all four
81+
CPU cores on a single graph.
82+
83+
Substitute widget types' symbols
84+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
85+
86+
If you are not happy with default symbols used in volume, battery, cpufreq and
87+
other widget types, use your own symbols without any need to modify modules.
88+
The following example uses a custom table map to modify symbols representing
89+
the mixer state: on or off/mute.
90+
91+
.. code-block:: lua
92+
93+
volumewidget = wibox.widget.textbox()
94+
vicious.register(volumewidget, vicious.widgets.volume,
95+
function (widget, args)
96+
local label = { ["🔉"] = "O", ["🔈"] = "M" }
97+
return ("Volume: %d%% State: %s"):format(
98+
args[1], label[args[2]])
99+
end, 2, "PCM")
100+
101+
.. _call-example:
102+
103+
Get data from the widget
104+
^^^^^^^^^^^^^^^^^^^^^^^^
105+
106+
:lua:func:`vicious.call` could be useful for naughty notification and scripts:
107+
108+
.. code-block:: lua
109+
110+
mybattery = wibox.widget.textbox()
111+
vicious.register(mybattery, vicious.widgets.bat, "$2%", 17, "0")
112+
mybattery:buttons(awful.util.table.join(awful.button(
113+
{}, 1,
114+
function ()
115+
naughty.notify{ title = "Battery indicator",
116+
text = vicious.call(vicious.widgets.bat,
117+
"Remaining time: $3", "0") }
118+
end)))
119+
120+
Format functions can be used as well:
121+
122+
.. code-block:: lua
123+
124+
mybattery:buttons(awful.util.table.join(awful.button(
125+
{}, 1,
126+
function ()
127+
naughty.notify{
128+
title = "Battery indicator",
129+
text = vicious.call(
130+
vicious.widgets.bat,
131+
function (widget, args)
132+
return ("%s: %10sh\n%s: %14d%%\n%s: %12dW"):format(
133+
"Remaining time", args[3],
134+
"Wear level", args[4],
135+
"Present rate", args[5])
136+
end, "0") }
137+
end)))

‎docs/source/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,13 @@ Table of Contents
1616
-----------------
1717

1818
.. toctree::
19-
:maxdepth: 2
19+
:titlesonly:
2020

2121
usage-lua
2222
usage-awesome
2323
widgets
2424
custom
25+
format
2526
caching
2627
security
2728
copying

‎docs/source/usage-awesome.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ call ``vicious.register`` to register it with Vicious:
4848
to retrieve data from an integer-indexed table (a.k.a. array);
4949
``${foo bar}`` will be substituted by ``t["{foo bar}"]``.
5050
* ``function (widget, args)`` can be used to manipulate data returned
51-
by the widget type (see [Format functions](#format-func)).
51+
by the widget type (see :ref:`format-func`).
5252

5353
:param interval: number of seconds between updates of the widget
5454
(default: 2). See :ref:`caching` for more information.
@@ -111,7 +111,7 @@ vicious.call
111111
.. lua:function:: vicious.call(wtype, format, warg)
112112
113113
Fetch data from the widget type to use it outside of the widget
114-
([example](#call-example)).
114+
(:ref:`example <call-example>`).
115115

116116
:param wtype:
117117
either of
@@ -130,7 +130,7 @@ vicious.call
130130
to retrieve data from an integer-indexed table (a.k.a. array);
131131
``${foo bar}`` will be substituted by ``t["{foo bar}"]``.
132132
* ``function (widget, args)`` can be used to manipulate data returned
133-
by the widget type (see [Format functions](#format-func)).
133+
by the widget type (see :ref:`format-func`).
134134

135135
:param warg: arguments to be passed to widget types, e.g. the battery ID.
136136

0 commit comments

Comments
 (0)