05 Jun 2016

Tags: awesome-widgets,pytextmonitor

Related posts:
FFXIV Astrologian guide
How to upload screenshots to S3 from linux

Awesome Widgets - Introducing custom formatters and macros

This paper describes new major features of Awesome Widgets 3.2.0.


Actually it has own graphical interface for configuration, but let me describe how to configure it by using your editor.

To apply formatters use $HOME/.local/share/awesomewidgets/formatters/formatters.ini file. It has only one section named [Formatters] in which keys are AW keys, values are related formatter names. For example,


means that formatter myformatter will be used for key cpu.

All formatters are stored in the same directory, one formatter per file, files should have .desktop extension. Each formatter has the following configuration fields inside [Desktop Entry] section:

Field Required Value Default
Name yes formatter name none
Comment no comment empty
X-AW-ApiVersion yes API compatibility index. Do not touch it if you don't know what does it mean 0
X-AW-Type no formatter type. The following types are supported: NoFormat, DateTime, Float, Json, List, Script, String NoFormat

Additionaly the following fields will be added by common extesions: X-AW-Active, X-AW-Interval, X-AW-Number, X-AW-Schedule, X-AW-Socket, but they will be ignored.

Each formatter type has own behaviour and own settings and they are described below. Also there are system-wide settings which are stored in /usr/share/awesomewidgets/formatters/, system formatters will be overwritten by user defined ones, but formatter settings (i.e. formatters.ini) will be appended.

NoFormat formatter

Just puts value as string directly. It has no any special settings.

DateTime formatter

Converts QDateTime object to string.

Field Required Value Default
X-AW-Format yes Qt specific format string (empty)

Actually it is the same as $ctime tag and has the same configuration.

Float formatter

Converts any number to string.

Field Required Value Default
X-AW-FillChar no char to fill number to X-AW-Width (space)
X-AW-ForceWidth no strip string after X-AW-Width false
X-AW-Format no Qt specific number format, supported values are e, E, f, g, G f
X-AW-Multiplier no float to which value will be multiplied 1.0
X-AW-Precision no show this count of symbols after dot -1 (as expected)
X-AW-Summand no float to which value will be increased 0.0
X-AW-Width no width of the field, negative means left-alignment 0 (do not limit)

Please note that actual formula is X-AW-Multiplier * value + X-AW-Summand.

Json formatter

Extracts values from json.

Field Required Value Default
X-AW-Path yes path to json value (empty)

Path should be separated only by dots. Numbers in path will be interpret as element index in array.

List formatter

Coverts list of string objects to string.

Field Required Value Default
X-AW-Filter no filter by this regular expression (empty)
X-AW-Separator no use this separator to join strings (empty)
X-AW-Sort no boolean, sort or not list false

String formatter

Improved version of NoFormat.

Field Required Value Default
X-AW-FillChar no char to fill string to X-AW-Width (space)
X-AW-ForceWidth no strip string after X-AW-Width false
X-AW-Width no width of the field, negative means left-alignment 0 (do not limit)

Script formatter

Uses javascript code to convert value to string. Value will be passed as argument to fuction.

Field Required Value Default
X-AW-AppendCode no prepend code by (function(value) { and append }) true
X-AW-Code no code for use
X-AW-HasReturn no if false will append your code by return output;. Only works if X-AW-AppendCode is true false

Actually for example to covert download speed to kibibits on the fly you may use the following:


The code will be expanded to:

(function(value) {
  output = value / 8.0;
  return output;


Another new feature is macros. User may define any own function by using the following construction $aw_macro<my_macro_name,some_arg,another_arg>{{macro body here with $some_arg}}.

The first argument is macros name, which is required. Another ones describe arguments which will be passed to the macro call. Macro body may have any text (including templates, lambdas, etc) and arguments which are defined by using $.

To put defined macro to your code use the following construction: $aw_macro_my_macro_name<$cpu,$cpucl>{{}} (body will be ignored here). In this example macro will be expanded to macro body here with $cpu.