3 Michael Stapelberg <michael@i3wm.org>
6 This document explains the protocol in which i3bar expects its input. It
7 provides support for colors, urgency, shortening and easy manipulation.
9 == Rationale for chosing JSON
11 Before describing the protocol, let’s cover why JSON is a building block of
14 1. Other bar display programs such as dzen2 or xmobar are using in-band
15 signaling: they recognize certain sequences (like ^fg(#330000) in your input
16 text). We would like to avoid that and separate information from
17 meta-information. By information, we mean the actual output, like the IP
18 address of your ethernet adapter and by meta-information, we mean in which
19 color it should be displayed right now.
20 2. It is easy to write a simple script which manipulates part(s) of the input.
21 Each block of information (like a block for the disk space indicator, a block
22 for the current IP address, etc.) can be identified specifically and modified
23 in whichever way you like.
24 3. It remains easy to write a simple script which just suffixes (or prefixes) a
25 status line input, because tools like i3status will output their JSON in
26 such a way that each line array will be terminated by a newline. Therefore,
27 you are not required to use a streaming JSON parser, but you can use any
28 JSON parser and write your script in any programming language. In fact, you
29 can decide to not bother with the JSON parsing at all and just inject your
30 output at a specific position (beginning or end).
31 4. Relying on JSON does not introduce any new dependencies. In fact, the IPC
32 interface of i3 also uses JSON, therefore i3bar already depends on JSON.
34 The only point against using JSON is computational complexity. If that really
35 bothers you, just use the plain text input format (which i3bar will continue to
40 The first message of the protocol is a header block, which contains (at least)
41 the version of the protocol to be used. In case there are significant changes
42 (not only additions), the version will be incremented. i3bar will still
43 understand the old protocol version, but in order to use the new one, you need
44 to provide the correct version. The header block is terminated by a newline and
45 consists of a single JSON hash:
48 ------------------------------
50 ------------------------------
52 *All features example*:
53 ------------------------------
54 { "version": 1, "stop_signal": 10, "cont_signal": 12, "click_events": true }
55 ------------------------------
57 (Note that before i3 v4.3 the precise format had to be +{"version":1}+,
60 What follows is an infinite array (so it should be parsed by a streaming JSON
61 parser, but as described above you can go for a simpler solution), whose
62 elements are one array per status line. A status line is one unit of
63 information which should be displayed at a time. i3bar will not display any
64 input until the status line is complete. In each status line, every block will
65 be represented by a JSON hash:
73 "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
77 "full_text": "2012-01-05 20:00:01"
83 "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
87 "full_text": "2012-01-05 20:00:02"
93 Please note that this example was pretty printed for human consumption.
94 i3status and others will output single statuslines in one line, separated by
97 You can find an example of a shell script which can be used as your
98 +status_command+ in the bar configuration at
99 http://code.stapelberg.de/git/i3/tree/contrib/trivial-bar-script.sh?h=next
104 The version number (as an integer) of the i3bar protocol you will use.
106 Specify to i3bar the signal (as an integer) to send to stop your
108 The default value (if none is specified) is SIGSTOP.
110 Specify to i3bar the signal (as an integer)to send to continue your
112 The default value (if none is specified) is SIGCONT.
114 If specified and true i3bar will write a infinite array (same as above)
120 The most simple block you can think of is one which just includes the
121 only required key, the +full_text+ key. i3bar will display the string
123 https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup].
125 Where appropriate, the +short_text+ (string) entry should also be
126 provided. It will be used in case the status line needs to be shortened
127 because it uses more space than your screen provides. For example, when
128 displaying an IPv6 address, the prefix is usually (!) more relevant
129 than the suffix, because the latter stays constant when using autoconf,
130 while the prefix changes. When displaying the date, the time is more
131 important than the date (it is more likely that you know which day it
132 is than what time it is).
134 To make the current state of the information easy to spot, colors can
135 be used. For example, the wireless block could be displayed in red
136 (using the +color+ (string) entry) if the card is not associated with
137 any network and in green or yellow (depending on the signal strength)
138 when it is associated.
139 Colors are specified in hex (like in HTML), starting with a leading
140 hash sign. For example, +#ff0000+ means red.
142 The minimum width (in pixels) of the block. If the content of the
143 +full_text+ key take less space than the specified min_width, the block
144 will be padded to the left and/or the right side, according to the +align+
145 key. This is useful when you want to prevent the whole status line to shift
146 when value take more or less space between each iteration.
147 The value can also be a string. In this case, the width of the text given
148 by +min_width+ determines the minimum width of the block. This is useful
149 when you want to set a sensible minimum width regardless of which font you
150 are using, and at what particular size.
152 Align text on the +center+, +right+ or +left+ (default) of the block, when
153 the minimum width of the latter, specified by the +min_width+ key, is not
156 Every block should have a unique +name+ (string) entry so that it can
157 be easily identified in scripts which process the output. i3bar
158 completely ignores the name and instance fields. Make sure to also
159 specify an +instance+ (string) entry where appropriate. For example,
160 the user can have multiple disk space blocks for multiple mount points.
162 A boolean which specifies whether the current value is urgent. Examples
163 are battery charge values below 1 percent or no more available disk
164 space (for non-root users). The presentation of urgency is up to i3bar.
166 A boolean which specifies whether a separator line should be drawn
167 after this block. The default is true, meaning the separator line will
168 be drawn. Note that if you disable the separator line, there will still
169 be a gap after the block, unless you also use +separator_block_width+.
170 separator_block_width::
171 The amount of pixels to leave blank after the block. In the middle of
172 this gap, a separator line will be drawn unless +separator+ is
173 disabled. Normally, you want to set this to an odd value (the default
174 is 9 pixels), since the separator line is drawn in the middle.
176 If you want to put in your own entries into a block, prefix the key with an
177 underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing
178 them with an underscore makes it clear in every script that they are not part
179 of the i3bar protocol.
182 ------------------------------------------
184 "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
185 "_ethernet_vendor": "Intel"
187 ------------------------------------------
189 In the following example, the longest (widest) possible value of the block is
190 used to set the minimum width:
192 ------------------------------------------
194 "full_text": "CPU 4%",
195 "min_width": "CPU 100%",
198 ------------------------------------------
200 An example of a block which uses all possible entries follows:
203 ------------------------------------------
205 "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
206 "short_text": "10.0.0.1",
214 "separator_block_width": 9
216 ------------------------------------------
220 If enabled i3bar will send you notifications if the user clicks on a block and
224 Name of the block, if set
226 Instance of the block, if set
228 X11 root window coordinates where the click occured
230 X11 button ID (for example 1 to 3 for left/middle/right mouse button)
233 ------------------------------------------
241 ------------------------------------------