138 lines
4.6 KiB
ReStructuredText
138 lines
4.6 KiB
ReStructuredText
.. _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)))
|