diff --git a/README.md b/README.md index af094ef..bc43436 100644 --- a/README.md +++ b/README.md @@ -102,137 +102,6 @@ vicious.register(cpuwidget, vicious.widgets.cpu, "$1", 3) ``` -## 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 ('MPD: %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") -``` - -#### 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+, diff --git a/docs/source/format.rst b/docs/source/format.rst new file mode 100644 index 0000000..49b93c4 --- /dev/null +++ b/docs/source/format.rst @@ -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 ('MPD: %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))) diff --git a/docs/source/index.rst b/docs/source/index.rst index 05109a4..7e115e7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,12 +16,13 @@ Table of Contents ----------------- .. toctree:: - :maxdepth: 2 + :titlesonly: usage-lua usage-awesome widgets custom + format caching security copying diff --git a/docs/source/usage-awesome.rst b/docs/source/usage-awesome.rst index 0af59d1..5d97921 100644 --- a/docs/source/usage-awesome.rst +++ b/docs/source/usage-awesome.rst @@ -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 `). :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.