You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
277 lines
7.1 KiB
277 lines
7.1 KiB
% I3BLOCKS(1)
|
|
|
|
# NAME
|
|
i3blocks - A flexible scheduler for your i3bar blocks
|
|
|
|
# SYNOPSIS
|
|
|
|
i3blocks [*options*]
|
|
|
|
# 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 <configfile>
|
|
: 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 http://i3wm.org/docs/i3bar-protocol.html , 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`
|
|
|
|
- `background`
|
|
|
|
- `border`
|
|
|
|
- `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](https://github.com/vivien/i3blocks).
|
|
|
|
The [wiki](https://github.com/vivien/i3blocks/wiki) is a good
|
|
source of examples for blocks and screenshots.
|
|
|
|
`i3` (1), `i3bar` (1), `i3status` (1)
|
|
|
|
# Reporting Bugs
|
|
|
|
Please report bugs on the [issue tracker](https://github.com/vivien/i3blocks/issues).
|
|
|
|
# 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.
|