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

   1 i3bar input protocol
   2 ====================
   3 Michael Stapelberg <michael@i3wm.org>
   4 February 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 chosing 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 *Example*:
  48 ----------------
  49 { "version": 1 }
  50 ----------------
  51
  52 What follows is an infinite array (so it should be parsed by a streaming JSON
  53 parser, but as described above you can go for a simpler solution), whose
  54 elements are one array per status line. A status line is one unit of
  55 information which should be displayed at a time. i3bar will not display any
  56 input until the status line is complete. In each status line, every block will
  57 be represented by a JSON hash:
  58
  59 *Example*:
  60 ------
  61 [
  62
  63  [
  64   {
  65    "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
  66    "color": "#00ff00"
  67   },
  68   {
  69    "full_text": "2012-01-05 20:00:01"
  70   }
  71  ],
  72
  73  [
  74   {
  75    "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
  76    "color": "#00ff00"
  77   },
  78   {
  79    "full_text": "2012-01-05 20:00:02"
  80   }
  81  ],
  82  …
  83 ------
  84
  85 Please note that this example was pretty printed for human consumption.
  86 i3status and others will output single statuslines in one line, separated by
  87 \n.
  88
  89 === Blocks in detail
  90
  91 full_text::
  92         The most simple block you can think of is one which just includes the
  93         only required key, the +full_text+ key. i3bar will display the string
  94         value and that’s it.
  95 short_text::
  96         Where appropriate, the +short_text+ (string) entry should also be
  97         provided. It will be used in case the status line needs to be shortened
  98         because it uses more space than your screen provides. For example, when
  99         displaying an IPv6 address, the prefix is usually (!) more relevant
 100         than the suffix, because the latter stays constant when using autoconf,
 101         while the prefix changes. When displaying the date, the time is more
 102         important than the date (it is more likely that you know which day it
 103         is than what time it is).
 104 color::
 105         To make the current state of the information easy to spot, colors can
 106         be used. For example, the wireless block could be displayed in red
 107         (using the +color+ (string) entry) if the card is not associated with
 108         any network and in green or yellow (depending on the signal strength)
 109         when it is associated.
 110         Colors are specified in hex (like in HTML), starting with a leading
 111         hash sign. For example, +#ff0000+ means red.
 112 name and instance::
 113         Every block should have a unique +name+ (string) entry so that it can
 114         be easily identified in scripts which process the output. i3bar
 115         completely ignores the name and instance fields. Make sure to also
 116         specify an +instance+ (string) entry where appropriate. For example,
 117         the user can have multiple disk space blocks for multiple mount points.
 118 urgent::
 119         A boolean which specifies whether the current value is urgent. Examples
 120         are battery charge values below 1 percent or no more available disk
 121         space (for non-root users). The presentation of urgency is up to i3bar.
 122
 123 If you want to put in your own entries into a block, prefix the key with an
 124 underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing
 125 them with an underscore makes it clear in every script that they are not part
 126 of the i3bar protocol.
 127
 128 *Example*:
 129 ------------------------------------------
 130 {
 131  "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
 132  "_ethernet_vendor": "Intel"
 133 }
 134 ------------------------------------------
 135
 136 An example of a block which uses all possible entries follows:
 137
 138 *Example*:
 139 ------------------------------------------
 140 {
 141  "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
 142  "short_text": "10.0.0.1",
 143  "color": "#00ff00",
 144  "urgent": false,
 145  "name": "ethernet",
 146  "instance": "eth0"
 147 }
 148 ------------------------------------------