.\" Automatically generated by Pandoc 1.19.2.1 .\" .TH "I3BLOCKS" "1" "" "" "" .hy .SH NAME .PP i3blocks \- A flexible scheduler for your i3bar blocks .SH SYNOPSIS .PP i3blocks [\f[I]options\f[]] .SH DESCRIPTION .PP \f[B]i3blocks\f[] allows one to easily describe blocks in a simple format, and generate a status line for i3bar(1). It handles clicks, signals and time interval for user scripts. .SH OPTIONS .TP .B \-c Specifies an alternate configuration file path. By default, i3blocks looks for configuration files in the following order (note that /etc may be prefixed with /usr/local depending on the compilation flags): .RS .IP .nf \f[C] 1.\ ~/.config/i3blocks/config\ (or\ $XDG_CONFIG_HOME/i3blocks/config\ if\ set) 2.\ ~/.i3blocks.conf 3.\ /etc/xdg/i3blocks/config\ (or\ $XDG_CONFIG_DIRS/i3blocks/config\ if\ set) 4.\ /etc/i3blocks.conf \f[] .fi .RE .TP .B \-v Log level. This option is cumulative. By default, error messages are displayed on stderr. Passed once, a failure during an update is shown within the block. Passed twice enables the debug messages on stderr. .RS .RE .TP .B \-V Print the version and exit. .RS .RE .TP .B \-h Print the help message and exit. .RS .RE .SH CONFIGURATION .PP The configuration file is an ini file. Each section describes a new block. A line beginning with a \f[C]#\f[] sign is a comment, and empty lines are ignored. A property is a \f[C]key=value\f[] pair per line, with no space around the equal sign. Properties declared outside a block (i.e. at the beginning of the file) describe global settings. .PP Here is an example config file: .IP .nf \f[C] #\ This\ is\ a\ comment interval=5 color=#00FF00 [weather] command=~/bin/weather.pl interval=1800 [time] command=date\ +%T \f[] .fi .PP To use i3blocks as your status line, define it in a \f[I]bar\f[] block of your \f[C]~/i3/config\f[] file: .IP .nf \f[C] bar\ { \ \ status_command\ i3blocks } \f[] .fi .SH BLOCK .PP The properties used to describe a block are the keys specified in the i3bar protocol http://i3wm.org/docs/i3bar\-protocol.html , plus additional properties used by \f[B]i3blocks\f[] to describe when and how to update a block. All the supported properties are described below. .PP The following keys are standard, see http://i3wm.org/docs/i3bar\-protocol.html for details. .IP \[bu] 2 \f[C]full_text\f[] .IP \[bu] 2 \f[C]short_text\f[] .IP \[bu] 2 \f[C]color\f[] .IP \[bu] 2 \f[C]min_width\f[] .IP \[bu] 2 \f[C]align\f[] .IP \[bu] 2 \f[C]name\f[] .IP \[bu] 2 \f[C]instance\f[] .IP \[bu] 2 \f[C]urgent\f[] .IP \[bu] 2 \f[C]separator\f[] .IP \[bu] 2 \f[C]separator_block_width\f[] .IP \[bu] 2 \f[C]markup\f[] .PP The following keys are specific to \f[B]i3blocks\f[]. .TP .B \f[C]command\f[] The command executed by a shell, used to update the block. The expected behavior is described below, in the \f[B]COMMAND\f[] section. .RS .RE .TP .B \f[C]interval\f[] If it is a positive integer, then the block is spawned on startup and the value is used as a time interval in seconds to schedule future updates. If unspecified or 0, the block won\[aq]t be executed on startup (which is useful to simulate buttons). .RS .PP If "\f[I]once\f[]" (or \-1), the block will be executed only on startup (note that a click or signal will still trigger an update). .PP If "\f[I]repeat\f[]" (or \-2), the block will be spawned on startup, and as soon as it terminates (useful to repeat blocking commands). Use with caution! .PP If "\f[I]persist\f[]" (or \-3), the block will be executed only on startup, and updated as soon as it outputs a line. Thus limited to single line updates. .RE .TP .B \f[C]signal\f[] The signal number used to update the block. All the real\-time (think prioritized and queueable) signals are available to the user. The number is valid between 1 and N, where SIGRTMIN+N = SIGRTMAX. (Note: there are 31 real\-time signals in Linux.) For instance, \f[C]signal=10\f[] means that this block will be updated when \f[B]i3blocks\f[] receives SIGRTMIN+10. .RS .RE .TP .B \f[C]label\f[] An optional label to preprend to the \f[C]full_text\f[] after an update. .RS .RE .TP .B \f[C]format\f[] This property specifies the format of the output text. The default format is plain text, as described in the \f[B]COMMAND\f[] section. If "json" (or 1) is used, the block output is parsed as JSON. .RS .RE .SH COMMAND .PP The value of the \f[C]command\f[] key will be passed and executed as is by a shell. .PP The standard output of the command line is used to update the block content. Each non\-empty line of the output will overwrite the corresponding property: .IP "1." 3 full_text .IP "2." 3 short_text .IP "3." 3 color .PP For example, this script sets the \f[C]full_text\f[] in blue but no \f[C]short_text\f[]: .IP .nf \f[C] echo\ "Here\[aq]s\ my\ label" echo echo\ \\#0000FF \f[] .fi .PP If the command line returns 0 or 33, the block is updated. Otherwise, it is considered a failure and the first line (if any) is still displayed. Note that stderr is ignored. A return code of 33 will set the \f[C]urgent\f[] flag to true. .PP For example, this script prints the battery percentage and sets the urgent flag if it is below 10%: .IP .nf \f[C] BAT=`acpi\ \-b\ |\ grep\ \-E\ \-o\ \[aq][0\-9][0\-9]?%\[aq]` echo\ "BAT:\ $BAT" test\ ${BAT%?}\ \-le\ 10\ &&\ exit\ 33\ ||\ exit\ 0 \f[] .fi .PP When forking a block command, \f[B]i3blocks\f[] will set the environment with some \f[C]BLOCK_*\f[] variables. The following variables are always provided, with eventually an empty string as the value. .TP .B \f[C]BLOCK_NAME\f[] The name of the block (usually the section name). .RS .RE .TP .B \f[C]BLOCK_INSTANCE\f[] An optional argument to the script. .RS .RE .TP .B \f[C]BLOCK_BUTTON\f[] Mouse button (1, 2 or 3) if the block was clicked. .RS .RE .TP .B \f[C]BLOCK_X\f[] and \f[C]BLOCK_Y\f[] Coordinates where the click occurred, if the block was clicked. .RS .RE .PP Here is an example using the environment: .IP .nf \f[C] [block] command=echo\ name=$BLOCK_NAME\ instance=$BLOCK_INSTANCE interval=1 [clickme] full_text=Click\ me! command=echo\ button=$BLOCK_BUTTON\ x=$BLOCK_X\ y=$BLOCK_Y min_width=button=1\ x=1366\ y=768 align=left \f[] .fi .PP Note that \f[B]i3blocks\f[] provides a set of optional scripts for convenience, such as network status, battery check, cpu load, volume, etc. .SH EXAMPLES .PP As an example, here is a close configuration to i3status(1) default settings: .PP \f[B]TODO\f[] .IP .nf \f[C] interval=5 signal=10 [ipv6] [free] [dhcp] [vpn] [wifi] [ethernet] min_width=E:\ 255.255.255.255\ (1000\ Mbit/s) [battery] [cpu] [datetime] \f[] .fi .PP The following block shows the usage of \f[C]signal\f[] with some i3(1) bindings which adjust the volume, before issuing a \f[C]pkill\ \-RTMIN+1\ i3blocks\f[]: .IP .nf \f[C] [volume] command=echo\ \-n\ \[aq]Volume:\ \[aq];\ amixer\ get\ Master\ |\ grep\ \-E\ \-o\ \[aq][0\-9][0\-9]?%\[aq] interval=once signal=1 #\ no\ interval,\ only\ check\ on\ SIGRTMIN+1 \f[] .fi .PP Here is an example of a very minimalist config, assuming you have a bunch of scripts under \f[C]~/bin/blocks/\f[] with the same name as the blocks: .IP .nf \f[C] command=~/bin/blocks/$BLOCK_NAME interval=1 [free] [wifi] [ethernet] [battery] [cpu] [datetime] \f[] .fi .SH SEE ALSO .PP The development of i3blocks takes place on Github (https://github.com/vivien/i3blocks). .PP The wiki (https://github.com/vivien/i3blocks/wiki) is a good source of examples for blocks and screenshots. .PP \f[C]i3\f[] (1), \f[C]i3bar\f[] (1), \f[C]i3status\f[] (1) .SH Reporting Bugs .PP Please report bugs on the issue tracker (https://github.com/vivien/i3blocks/issues). .SH Known Bugs .PP None. .SH AUTHOR .PP Written by Vivien Didelot . .SH COPYRIGHT .PP Copyright (C) 2014 Vivien Didelot .PP License GPLv3+: GNU GPL version 3 or later . .PP This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.