Module i3status_rs::formatting

source ·
Expand description

§Formatting system

Many blocks have a format configuration option, which allows to heavily customize the block’s appearance. In short, each block with format option provides a set of values, which are displayed according to format. format’s value is just a text with embedded variables. Similarly to PHP and shell, variable name must start with a $: this is a variable: -> $var <-.

Also, format strings can embed icons. For example, ^icon_ping in " ^icon_ping $ping " gets substituted with a “ping” icon from your icon set. For a complete list of icons, see this.

§Types

The allowed types of variables are:

TypeDefault formatter
Textstr
Numbereng
Datetimedatetime
Durationduration
FlagN/A

§Formatters

A formatter is something that converts a value into a text. Because there are many ways to do this, a number of formatters is available. Formatter can be specified using the syntax similar to method calls in many programming languages: <variable>.<formatter>(<args>). For example: $title.str(min_w:10, max_w:20).

§str - Format text

ArgumentDescriptionDefault value
min_width or min_wif text is shorter it will be padded using spaces0
max_width or max_wif text is longer it will be truncatedInfinity
width or wText will be exactly this length by padding or truncating as neededN/A
rot_intervalif text is longer than max_width it will be rotated every rot_interval seconds, if setNone
rot_separatorif text is longer than max_width it will be rotated with this seporator"|"

Note: width just changes the values of both min_width and max_width to be the same. Use width if you want the values to be the same, or the other two otherwise. Don’t mix width with min_width or max_width.

§eng - Format numbers using engineering notation

ArgumentDescriptionDefault value
width or wthe resulting text will be at least width characters long2
unit or usome values have a unit, and it is possible to convert them by setting this optionN/A
hide_unithide the unit symbolfalse
unit_spacehave a whitespace before unit symbolfalse
prefix or pspecify this argument if you want to set the minimal SI prefixN/A
hide_prefixhide the prefix symbolfalse
prefix_spacehave a whitespace before prefix symbolfalse
force_prefixforce the prefix value instead of setting a “minimal prefix”false
pad_withthe character that is used to pad the number to be width long (a space)
rangea range of allowed values, in the format <start>..<end>, inclusive. Both start and end are optional. Can be used to, for example, hide the block when the value is not in a given range...

§bar - Display numbers as progress bars

ArgumentDescriptionDefault value
width or wthe width of the bar (in characters)5 (1 for vertical)
max_valuewhich value is treated as “full”. For example, for battery level 100 is full.100
vertical or vwhether to render the bar vertically or notfalse

§tally - Display numbers as tally marks

ArgumentDescriptionDefault value
style or sOne of chinese_counting_rods/ccr, chinese_tally/ct, western_tally/wt, western_tally_ungrouped/wtuwestern_tally

§pango-str - Just display the text without pango markup escaping

No arguments.

§datetime - Display datetime

ArgumentDescriptionDefault value
format or fchrono docs for all options.'%a %d/%m %R'
locale or lLocale to apply when formatting the timeSystem locale

§duration/dur - Format durations

ArgumentDescriptionDefault value
hmsShould the format be hours:minutes:seconds.millisecondsfalse
max_unitThe largest unit to display the duration with (see below for the list of all possible units)hms ? h : y
min_unitThe smallest unit to display the duration with (see below for the list of all possible units)s
unitsThe number of units to displaymin(# of units between max_unit and `min_unit``, 2)
round_upRound up to the nearest minimum displayed unittrue
unit_spaceShould there be a space between the value and unit symbol (not allowed when hms:true)false
pad_withThe character that is used to pad the numbershms ? 0 : (a space)
leading_zeroesIf fewer than units are non-zero should leading numbers that have a value of zero be showntrue
UnitDescription
yyears
wweeks
ddays
hhours
mminutes
sseconds
msmilliseconds

§Handling missing placeholders and incorrect types

Some blocks allow missing placeholders, for example bluetooth’s “percentage” may be absent if the device is not supported. To handle such cases it is possible to queue multiple formats together by using | symbol: <something that can fail>|<otherwise try this>|<or this>.

In addition, formats can be recursive. To set a format inside of another format, place it inside of {}. For example, in Percentage: {$percentage|N/A} the text “Percentage: “ will be always displayed, followed by the actual percentage or “N/A” in case percentage is not available. This example does exactly the same thing as Percentage: $percentage|Percentage: N/A

§How to use flags

Some blocks provide flags, which can be used to change the format based on some criteria. For example, taskwarrior defines done if the count is zero. In general, flags are used in this way:

$a{a is set}|$b$c{b and c are set}|${b|c}{b or c is set}|neither flag is set

Modules§

Structs§

Enums§

Type Aliases§