Skip to content

Latest commit

 

History

History
259 lines (181 loc) · 7.21 KB

i3blocks.1.ronn

File metadata and controls

259 lines (181 loc) · 7.21 KB
Raw

i3blocks(1) -- A flexible scheduler for i3bar

SYNOPSIS

i3blocks [-c ] [-v]... [-h] [-V]

DESCRIPTION

i3blocks 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.

OPTIONS

  • -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):

    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

  • -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.

  • -V: Print the version and exit.

  • -h: Print the help message and exit.

CONFIGURATION

The configuration file is an ini file. Each section describes a new block. A line beginning with a # sign is a comment, and empty lines are ignored. A property is a key=value 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.

Here is an example config file:

# This is a comment
interval=5
color=#00FF00

[weather]
command=~/bin/weather.pl
interval=1800

[time]
command=date +%T

To use i3blocks as your status line, define it in a bar block of your ~/i3/config file:

bar {
  status_command i3blocks
}

BLOCK

The properties used to describe a block are the keys specified in the i3bar protocol, plus additional properties used by i3blocks to describe when and how to update a block. All the supported properties are described below.

The following keys are standard, see http://i3wm.org/docs/i3bar-protocol.html for details.

  • full_text
  • short_text
  • color
  • min_width
  • align
  • name
  • instance
  • urgent
  • separator
  • separator_block_width
  • markup

The following keys are specific to i3blocks.

  • command: The command executed by a shell, used to update the block. The expected behavior is described below, in the [COMMAND][] section.

  • interval: 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't be executed on startup (which is useful to simulate buttons). If "once" (or -1), the block will be executed only on startup (note that a click or signal will still trigger an update). If "repeat" (or -2), the block will be spawned on startup, and as soon as it terminates (useful to repeat blocking commands). Use with caution! If "persist" (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.

  • signal: 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, signal=10 means that this block will be updated when i3blocks receives SIGRTMIN+10.

  • label: An optional label to preprend to the full_text after an update.

  • format: This property specifies the format of the output text. The default format is plain text, as described in the [COMMAND][] section. If "json" (or 1) is used, the block output is parsed as JSON.

COMMAND

The value of the command key will be passed and executed as is by a shell.

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:

  1. full_text
  2. short_text
  3. color

For example, this script sets the full_text in blue but no short_text:

echo "Here's my label"
echo
echo \#0000FF

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 urgent flag to true.

For example, this script prints the battery percentage and sets the urgent flag if it is below 10%:

BAT=`acpi -b | grep -E -o '[0-9][0-9]?%'`

echo "BAT: $BAT"
test ${BAT%?} -le 10 && exit 33 || exit 0

When forking a block command, i3blocks will set the environment with some BLOCK_* variables. The following variables are always provided, with eventually an empty string as the value.

  • BLOCK_NAME: The name of the block (usually the section name).

  • BLOCK_INSTANCE: An optional argument to the script.

  • BLOCK_BUTTON: Mouse button (1, 2 or 3) if the block was clicked.

  • BLOCK_X and BLOCK_Y: Coordinates where the click occurred, if the block was clicked.

Here is an example using the environment:

[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

Note that i3blocks provides a set of optional scripts for convenience, such as network status, battery check, cpu load, volume, etc.

EXAMPLES

As an example, here is a close configuration to i3status(1) default settings:

TODO

interval=5
signal=10

[ipv6]

[free]

[dhcp]

[vpn]

[wifi]

[ethernet]
min_width=E: 255.255.255.255 (1000 Mbit/s)

[battery]

[cpu]

[datetime]

The following block shows the usage of signal with some i3(1) bindings which adjust the volume, before issuing a pkill -RTMIN+1 i3blocks:

[volume]
command=echo -n 'Volume: '; amixer get Master | grep -E -o '[0-9][0-9]?%'
interval=once
signal=1
# no interval, only check on SIGRTMIN+1

Here is an example of a very minimalist config, assuming you have a bunch of scripts under ~/bin/blocks/ with the same name as the blocks:

command=~/bin/blocks/$BLOCK_NAME
interval=1

[free]
[wifi]
[ethernet]
[battery]
[cpu]
[datetime]

SEE ALSO

The development of i3blocks takes place on Github. The wiki is a good source of examples for blocks and screenshots.

i3(1), i3bar(1), i3status(1)

BUGS

Reporting Bugs

Please report bugs on the issue tracker.

Known Bugs

None.

AUTHOR

Written by Vivien Didelot vivien.didelot@gmail.com.

COPYRIGHT

Copyright (C) 2014 Vivien Didelot vivien.didelot@gmail.com License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.