git.sur5r.net Git - i3/i3/blob - docs/i3bar-protocol

   1 i3bar input protocol
   2 ====================
   3 Michael Stapelberg <michael@i3wm.org>
   4 August 2012
   5
   6 This document explains the protocol in which i3bar expects its input. It
   7 provides support for colors, urgency, shortening and easy manipulation.
   8
   9 == Rationale for choosing JSON
  10
  11 Before describing the protocol, let’s cover why JSON is a building block of
  12 this protocol.
  13
  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.
  33
  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
  36 support).
  37
  38 == The protocol
  39
  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:
  46
  47 *Minimal example*:
  48 ------------------------------
  49 { "version": 1 }
  50 ------------------------------
  51
  52 *All features example*:
  53 ------------------------------
  54 { "version": 1, "stop_signal": 10, "cont_signal": 12, "click_events": true }
  55 ------------------------------
  56
  57 (Note that before i3 v4.3 the precise format had to be +{"version":1}+,
  58 byte-for-byte.)
  59
  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:
  66
  67 *Example*:
  68 ------
  69 [
  70
  71  [
  72   {
  73    "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
  74    "color": "#00ff00"
  75   },
  76   {
  77    "full_text": "2012-01-05 20:00:01"
  78   }
  79  ],
  80
  81  [
  82   {
  83    "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
  84    "color": "#00ff00"
  85   },
  86   {
  87    "full_text": "2012-01-05 20:00:02"
  88   }
  89  ],
  90  …
  91 ------
  92
  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
  95 \n.
  96
  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 https://github.com/i3/i3/blob/next/contrib/trivial-bar-script.sh
 100
 101 === Header in detail
 102
 103 version::
 104         The version number (as an integer) of the i3bar protocol you will use.
 105 stop_signal::
 106         Specify to i3bar the signal (as an integer) to send to stop your
 107         processing.
 108         The default value (if none is specified) is SIGSTOP.
 109 cont_signal::
 110         Specify to i3bar the signal (as an integer) to send to continue your
 111         processing.
 112         The default value (if none is specified) is SIGCONT.
 113 click_events::
 114         If specified and true i3bar will write an infinite array (same as above)
 115         to your stdin.
 116
 117 === Blocks in detail
 118
 119 full_text::
 120         The +full_text+ will be displayed by i3bar on the status line. This is the
 121         only required key. If +full_text+ is an empty string, the block will be
 122         skipped.
 123 short_text::
 124         Where appropriate, the +short_text+ (string) entry should also be
 125         provided. It will be used in case the status line needs to be shortened
 126         because it uses more space than your screen provides. For example, when
 127         displaying an IPv6 address, the prefix is usually (!) more relevant
 128         than the suffix, because the latter stays constant when using autoconf,
 129         while the prefix changes. When displaying the date, the time is more
 130         important than the date (it is more likely that you know which day it
 131         is than what time it is).
 132 color::
 133         To make the current state of the information easy to spot, colors can
 134         be used. For example, the wireless block could be displayed in red
 135         (using the +color+ (string) entry) if the card is not associated with
 136         any network and in green or yellow (depending on the signal strength)
 137         when it is associated.
 138         Colors are specified in hex (like in HTML), starting with a leading
 139         hash sign. For example, +#ff0000+ means red.
 140 background::
 141         Overrides the background color for this particular block.
 142 border::
 143         Overrides the border color for this particular block.
 144 min_width::
 145         The minimum width (in pixels) of the block. If the content of the
 146         +full_text+ key take less space than the specified min_width, the block
 147         will be padded to the left and/or the right side, according to the +align+
 148         key. This is useful when you want to prevent the whole status line to shift
 149         when value take more or less space between each iteration.
 150         The value can also be a string. In this case, the width of the text given
 151         by +min_width+ determines the minimum width of the block. This is useful
 152         when you want to set a sensible minimum width regardless of which font you
 153         are using, and at what particular size.
 154 align::
 155         Align text on the +center+, +right+ or +left+ (default) of the block, when
 156         the minimum width of the latter, specified by the +min_width+ key, is not
 157         reached.
 158 name and instance::
 159         Every block should have a unique +name+ (string) entry so that it can
 160         be easily identified in scripts which process the output. i3bar
 161         completely ignores the name and instance fields. Make sure to also
 162         specify an +instance+ (string) entry where appropriate. For example,
 163         the user can have multiple disk space blocks for multiple mount points.
 164 urgent::
 165         A boolean which specifies whether the current value is urgent. Examples
 166         are battery charge values below 1 percent or no more available disk
 167         space (for non-root users). The presentation of urgency is up to i3bar.
 168 separator::
 169         A boolean which specifies whether a separator line should be drawn
 170         after this block. The default is true, meaning the separator line will
 171         be drawn. Note that if you disable the separator line, there will still
 172         be a gap after the block, unless you also use +separator_block_width+.
 173 separator_block_width::
 174         The amount of pixels to leave blank after the block. In the middle of
 175         this gap, a separator line will be drawn unless +separator+ is
 176         disabled. Normally, you want to set this to an odd value (the default
 177         is 9 pixels), since the separator line is drawn in the middle.
 178 markup::
 179         A string that indicates how the text of the block should be parsed. Set to
 180         +"pango"+ to use https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup].
 181         Set to +"none"+ to not use any markup (default). Pango markup only works
 182         if you use a pango font.
 183
 184 If you want to put in your own entries into a block, prefix the key with an
 185 underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing
 186 them with an underscore makes it clear in every script that they are not part
 187 of the i3bar protocol.
 188
 189 *Example*:
 190 ------------------------------------------
 191 {
 192  "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
 193  "_ethernet_vendor": "Intel"
 194 }
 195 ------------------------------------------
 196
 197 In the following example, the longest (widest) possible value of the block is
 198 used to set the minimum width:
 199
 200 ------------------------------------------
 201 {
 202  "full_text": "CPU 4%",
 203  "min_width": "CPU 100%",
 204  "align": "left"
 205 }
 206 ------------------------------------------
 207
 208 An example of a block which uses all possible entries follows:
 209
 210 *Example*:
 211 ------------------------------------------
 212 {
 213  "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
 214  "short_text": "10.0.0.1",
 215  "color": "#00ff00",
 216  "background": "#1c1c1c",
 217  "border": "#ee0000",
 218  "min_width": 300,
 219  "align": "right",
 220  "urgent": false,
 221  "name": "ethernet",
 222  "instance": "eth0",
 223  "separator": true,
 224  "separator_block_width": 9
 225 }
 226 ------------------------------------------
 227
 228 === Click events
 229
 230 If enabled i3bar will send you notifications if the user clicks on a block and
 231 looks like this:
 232
 233 name::
 234         Name of the block, if set
 235 instance::
 236         Instance of the block, if set
 237 x, y::
 238         X11 root window coordinates where the click occurred
 239 button::
 240         X11 button ID (for example 1 to 3 for left/middle/right mouse button)
 241 relative_x, relative_y::
 242     Coordinates where the click occurred, with respect to the top left corner
 243     of the block
 244 width, height::
 245     Width and height (in px) of the block
 246
 247 *Example*:
 248 ------------------------------------------
 249 {
 250  "name": "ethernet",
 251  "instance": "eth0",
 252  "button": 1,
 253  "x": 1320,
 254  "y": 1400,
 255  "relative_x": 12,
 256  "relative_y": 8,
 257  "width": 50,
 258  "height": 22
 259 }
 260 ------------------------------------------