git.sur5r.net Git - i3/i3.github.io/blob - docs/4.13/i3bar-protocol.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
   4 <head>\r
   5 <link rel="icon" type="image/x-icon" href="/favicon.ico">\r
   6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
   7 <meta name="generator" content="AsciiDoc 8.6.9" />\r
   8 <title>i3: i3bar input protocol</title>\r
   9 <link rel="stylesheet" href="/css/style.css" type="text/css" />\r
  10 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
  11 <script type="text/javascript">\r
  12 /*<![CDATA[*/\r
  13 document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes();}, false);\r
  14 /*]]>*/\r
  15 </script>\r
  16 <script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\r
  17 </head>\r
  18 <body class="article">\r
  19 \r
  20         <div id="main">\r
  21             <a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>\r
  22                         <ul id="nav">\r
  23                                 <li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>\r
  24                                 <li><a href="/screenshots">Screens</a></li>\r
  25                                 <li><a href="https://www.reddit.com/r/i3wm/">FAQ</a></li>\r
  26                                 <li><a href="/contact">Contact</a></li>\r
  27                                 <li><a href="https://github.com/i3/i3/issues">Bugs</a></li>\r
  28                         </ul>\r
  29         <br style="clear: both">\r
  30 <div id="content">\r
  31 <div id="header">\r
  32 <h1>i3bar input protocol</h1>\r
  33 <span id="author">Michael Stapelberg</span><br />\r
  34 <span id="email"><tt>&lt;<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>&gt;</tt></span><br />\r
  35 <span id="revdate">August 2012</span>\r
  36 </div>\r
  37 <div id="preamble">\r
  38 <div class="sectionbody">\r
  39 <div class="paragraph"><p>This document explains the protocol in which i3bar expects its input. It\r
  40 provides support for colors, urgency, shortening and easy manipulation.</p></div>\r
  41 </div>\r
  42 </div>\r
  43 <div class="sect1">\r
  44 <h2 id="_rationale_for_choosing_json">1. Rationale for choosing JSON</h2>\r
  45 <div class="sectionbody">\r
  46 <div class="paragraph"><p>Before describing the protocol, let’s cover why JSON is a building block of\r
  47 this protocol.</p></div>\r
  48 <div class="olist arabic"><ol class="arabic">\r
  49 <li>\r
  50 <p>\r
  51 Other bar display programs such as dzen2 or xmobar are using in-band\r
  52    signaling: they recognize certain sequences (like ^fg(#330000) in your input\r
  53    text). We would like to avoid that and separate information from\r
  54    meta-information. By information, we mean the actual output, like the IP\r
  55    address of your ethernet adapter and by meta-information, we mean in which\r
  56    color it should be displayed right now.\r
  57 </p>\r
  58 </li>\r
  59 <li>\r
  60 <p>\r
  61 It is easy to write a simple script which manipulates part(s) of the input.\r
  62    Each block of information (like a block for the disk space indicator, a block\r
  63    for the current IP address, etc.) can be identified specifically and modified\r
  64    in whichever way you like.\r
  65 </p>\r
  66 </li>\r
  67 <li>\r
  68 <p>\r
  69 It remains easy to write a simple script which just suffixes (or prefixes) a\r
  70    status line input, because tools like i3status will output their JSON in\r
  71    such a way that each line array will be terminated by a newline. Therefore,\r
  72    you are not required to use a streaming JSON parser, but you can use any\r
  73    JSON parser and write your script in any programming language. In fact, you\r
  74    can decide to not bother with the JSON parsing at all and just inject your\r
  75    output at a specific position (beginning or end).\r
  76 </p>\r
  77 </li>\r
  78 <li>\r
  79 <p>\r
  80 Relying on JSON does not introduce any new dependencies. In fact, the IPC\r
  81    interface of i3 also uses JSON, therefore i3bar already depends on JSON.\r
  82 </p>\r
  83 </li>\r
  84 </ol></div>\r
  85 <div class="paragraph"><p>The only point against using JSON is computational complexity. If that really\r
  86 bothers you, just use the plain text input format (which i3bar will continue to\r
  87 support).</p></div>\r
  88 </div>\r
  89 </div>\r
  90 <div class="sect1">\r
  91 <h2 id="_the_protocol">2. The protocol</h2>\r
  92 <div class="sectionbody">\r
  93 <div class="paragraph"><p>The first message of the protocol is a header block, which contains (at least)\r
  94 the version of the protocol to be used. In case there are significant changes\r
  95 (not only additions), the version will be incremented. i3bar will still\r
  96 understand the old protocol version, but in order to use the new one, you need\r
  97 to provide the correct version. The header block is terminated by a newline and\r
  98 consists of a single JSON hash:</p></div>\r
  99 <div class="paragraph"><p><strong>Minimal example</strong>:</p></div>\r
 100 <div class="listingblock">\r
 101 <div class="content">\r
 102 <pre><tt>{ "version": 1 }</tt></pre>\r
 103 </div></div>\r
 104 <div class="paragraph"><p><strong>All features example</strong>:</p></div>\r
 105 <div class="listingblock">\r
 106 <div class="content">\r
 107 <pre><tt>{ "version": 1, "stop_signal": 10, "cont_signal": 12, "click_events": true }</tt></pre>\r
 108 </div></div>\r
 109 <div class="paragraph"><p>(Note that before i3 v4.3 the precise format had to be <tt>{"version":1}</tt>,\r
 110 byte-for-byte.)</p></div>\r
 111 <div class="paragraph"><p>What follows is an infinite array (so it should be parsed by a streaming JSON\r
 112 parser, but as described above you can go for a simpler solution), whose\r
 113 elements are one array per status line. A status line is one unit of\r
 114 information which should be displayed at a time. i3bar will not display any\r
 115 input until the status line is complete. In each status line, every block will\r
 116 be represented by a JSON hash:</p></div>\r
 117 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 118 <div class="listingblock">\r
 119 <div class="content">\r
 120 <pre><tt>[\r
 121 \r
 122  [\r
 123   {\r
 124    "full_text": "E: 10.0.0.1 (1000 Mbit/s)",\r
 125    "color": "#00ff00"\r
 126   },\r
 127   {\r
 128    "full_text": "2012-01-05 20:00:01"\r
 129   }\r
 130  ],\r
 131 \r
 132  [\r
 133   {\r
 134    "full_text": "E: 10.0.0.1 (1000 Mbit/s)",\r
 135    "color": "#00ff00"\r
 136   },\r
 137   {\r
 138    "full_text": "2012-01-05 20:00:02"\r
 139   }\r
 140  ],\r
 141  …</tt></pre>\r
 142 </div></div>\r
 143 <div class="paragraph"><p>Please note that this example was pretty printed for human consumption.\r
 144 i3status and others will output single statuslines in one line, separated by\r
 145 \n.</p></div>\r
 146 <div class="paragraph"><p>You can find an example of a shell script which can be used as your\r
 147 <tt>status_command</tt> in the bar configuration at\r
 148 <a href="http://code.stapelberg.de/git/i3/tree/contrib/trivial-bar-script.sh?h=next">http://code.stapelberg.de/git/i3/tree/contrib/trivial-bar-script.sh?h=next</a></p></div>\r
 149 <div class="sect2">\r
 150 <h3 id="_header_in_detail">2.1. Header in detail</h3>\r
 151 <div class="dlist"><dl>\r
 152 <dt class="hdlist1">\r
 153 version\r
 154 </dt>\r
 155 <dd>\r
 156 <p>\r
 157         The version number (as an integer) of the i3bar protocol you will use.\r
 158 </p>\r
 159 </dd>\r
 160 <dt class="hdlist1">\r
 161 stop_signal\r
 162 </dt>\r
 163 <dd>\r
 164 <p>\r
 165         Specify to i3bar the signal (as an integer) to send to stop your\r
 166         processing.\r
 167         The default value (if none is specified) is SIGSTOP.\r
 168 </p>\r
 169 </dd>\r
 170 <dt class="hdlist1">\r
 171 cont_signal\r
 172 </dt>\r
 173 <dd>\r
 174 <p>\r
 175         Specify to i3bar the signal (as an integer)to send to continue your\r
 176         processing.\r
 177         The default value (if none is specified) is SIGCONT.\r
 178 </p>\r
 179 </dd>\r
 180 <dt class="hdlist1">\r
 181 click_events\r
 182 </dt>\r
 183 <dd>\r
 184 <p>\r
 185         If specified and true i3bar will write an infinite array (same as above)\r
 186         to your stdin.\r
 187 </p>\r
 188 </dd>\r
 189 </dl></div>\r
 190 </div>\r
 191 <div class="sect2">\r
 192 <h3 id="_blocks_in_detail">2.2. Blocks in detail</h3>\r
 193 <div class="dlist"><dl>\r
 194 <dt class="hdlist1">\r
 195 full_text\r
 196 </dt>\r
 197 <dd>\r
 198 <p>\r
 199         The <tt>full_text</tt> will be displayed by i3bar on the status line. This is the\r
 200         only required key.\r
 201 </p>\r
 202 </dd>\r
 203 <dt class="hdlist1">\r
 204 short_text\r
 205 </dt>\r
 206 <dd>\r
 207 <p>\r
 208         Where appropriate, the <tt>short_text</tt> (string) entry should also be\r
 209         provided. It will be used in case the status line needs to be shortened\r
 210         because it uses more space than your screen provides. For example, when\r
 211         displaying an IPv6 address, the prefix is usually (!) more relevant\r
 212         than the suffix, because the latter stays constant when using autoconf,\r
 213         while the prefix changes. When displaying the date, the time is more\r
 214         important than the date (it is more likely that you know which day it\r
 215         is than what time it is).\r
 216 </p>\r
 217 </dd>\r
 218 <dt class="hdlist1">\r
 219 color\r
 220 </dt>\r
 221 <dd>\r
 222 <p>\r
 223         To make the current state of the information easy to spot, colors can\r
 224         be used. For example, the wireless block could be displayed in red\r
 225         (using the <tt>color</tt> (string) entry) if the card is not associated with\r
 226         any network and in green or yellow (depending on the signal strength)\r
 227         when it is associated.\r
 228         Colors are specified in hex (like in HTML), starting with a leading\r
 229         hash sign. For example, <tt>#ff0000</tt> means red.\r
 230 </p>\r
 231 </dd>\r
 232 <dt class="hdlist1">\r
 233 background\r
 234 </dt>\r
 235 <dd>\r
 236 <p>\r
 237         Overrides the background color for this particular block.\r
 238 </p>\r
 239 </dd>\r
 240 <dt class="hdlist1">\r
 241 border\r
 242 </dt>\r
 243 <dd>\r
 244 <p>\r
 245         Overrides the border color for this particular block.\r
 246 </p>\r
 247 </dd>\r
 248 <dt class="hdlist1">\r
 249 min_width\r
 250 </dt>\r
 251 <dd>\r
 252 <p>\r
 253         The minimum width (in pixels) of the block. If the content of the\r
 254         <tt>full_text</tt> key take less space than the specified min_width, the block\r
 255         will be padded to the left and/or the right side, according to the <tt>align</tt>\r
 256         key. This is useful when you want to prevent the whole status line to shift\r
 257         when value take more or less space between each iteration.\r
 258         The value can also be a string. In this case, the width of the text given\r
 259         by <tt>min_width</tt> determines the minimum width of the block. This is useful\r
 260         when you want to set a sensible minimum width regardless of which font you\r
 261         are using, and at what particular size.\r
 262 </p>\r
 263 </dd>\r
 264 <dt class="hdlist1">\r
 265 align\r
 266 </dt>\r
 267 <dd>\r
 268 <p>\r
 269         Align text on the <tt>center</tt>, <tt>right</tt> or <tt>left</tt> (default) of the block, when\r
 270         the minimum width of the latter, specified by the <tt>min_width</tt> key, is not\r
 271         reached.\r
 272 </p>\r
 273 </dd>\r
 274 <dt class="hdlist1">\r
 275 name and instance\r
 276 </dt>\r
 277 <dd>\r
 278 <p>\r
 279         Every block should have a unique <tt>name</tt> (string) entry so that it can\r
 280         be easily identified in scripts which process the output. i3bar\r
 281         completely ignores the name and instance fields. Make sure to also\r
 282         specify an <tt>instance</tt> (string) entry where appropriate. For example,\r
 283         the user can have multiple disk space blocks for multiple mount points.\r
 284 </p>\r
 285 </dd>\r
 286 <dt class="hdlist1">\r
 287 urgent\r
 288 </dt>\r
 289 <dd>\r
 290 <p>\r
 291         A boolean which specifies whether the current value is urgent. Examples\r
 292         are battery charge values below 1 percent or no more available disk\r
 293         space (for non-root users). The presentation of urgency is up to i3bar.\r
 294 </p>\r
 295 </dd>\r
 296 <dt class="hdlist1">\r
 297 separator\r
 298 </dt>\r
 299 <dd>\r
 300 <p>\r
 301         A boolean which specifies whether a separator line should be drawn\r
 302         after this block. The default is true, meaning the separator line will\r
 303         be drawn. Note that if you disable the separator line, there will still\r
 304         be a gap after the block, unless you also use <tt>separator_block_width</tt>.\r
 305 </p>\r
 306 </dd>\r
 307 <dt class="hdlist1">\r
 308 separator_block_width\r
 309 </dt>\r
 310 <dd>\r
 311 <p>\r
 312         The amount of pixels to leave blank after the block. In the middle of\r
 313         this gap, a separator line will be drawn unless <tt>separator</tt> is\r
 314         disabled. Normally, you want to set this to an odd value (the default\r
 315         is 9 pixels), since the separator line is drawn in the middle.\r
 316 </p>\r
 317 </dd>\r
 318 <dt class="hdlist1">\r
 319 markup\r
 320 </dt>\r
 321 <dd>\r
 322 <p>\r
 323         A string that indicates how the text of the block should be parsed. Set to\r
 324         <tt>"pango"</tt> to use <a href="https://developer.gnome.org/pango/stable/PangoMarkupFormat.html">Pango markup</a>.\r
 325         Set to <tt>"none"</tt> to not use any markup (default).\r
 326 </p>\r
 327 </dd>\r
 328 </dl></div>\r
 329 <div class="paragraph"><p>If you want to put in your own entries into a block, prefix the key with an\r
 330 underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing\r
 331 them with an underscore makes it clear in every script that they are not part\r
 332 of the i3bar protocol.</p></div>\r
 333 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 334 <div class="listingblock">\r
 335 <div class="content">\r
 336 <pre><tt>{\r
 337  "full_text": "E: 10.0.0.1 (1000 Mbit/s)",\r
 338  "_ethernet_vendor": "Intel"\r
 339 }</tt></pre>\r
 340 </div></div>\r
 341 <div class="paragraph"><p>In the following example, the longest (widest) possible value of the block is\r
 342 used to set the minimum width:</p></div>\r
 343 <div class="listingblock">\r
 344 <div class="content">\r
 345 <pre><tt>{\r
 346  "full_text": "CPU 4%",\r
 347  "min_width": "CPU 100%",\r
 348  "align": "left"\r
 349 }</tt></pre>\r
 350 </div></div>\r
 351 <div class="paragraph"><p>An example of a block which uses all possible entries follows:</p></div>\r
 352 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 353 <div class="listingblock">\r
 354 <div class="content">\r
 355 <pre><tt>{\r
 356  "full_text": "E: 10.0.0.1 (1000 Mbit/s)",\r
 357  "short_text": "10.0.0.1",\r
 358  "color": "#00ff00",\r
 359  "background": "#1c1c1c",\r
 360  "border": "#ee0000",\r
 361  "min_width": 300,\r
 362  "align": "right",\r
 363  "urgent": false,\r
 364  "name": "ethernet",\r
 365  "instance": "eth0",\r
 366  "separator": true,\r
 367  "separator_block_width": 9\r
 368 }</tt></pre>\r
 369 </div></div>\r
 370 </div>\r
 371 <div class="sect2">\r
 372 <h3 id="_click_events">2.3. Click events</h3>\r
 373 <div class="paragraph"><p>If enabled i3bar will send you notifications if the user clicks on a block and\r
 374 looks like this:</p></div>\r
 375 <div class="dlist"><dl>\r
 376 <dt class="hdlist1">\r
 377 name\r
 378 </dt>\r
 379 <dd>\r
 380 <p>\r
 381         Name of the block, if set\r
 382 </p>\r
 383 </dd>\r
 384 <dt class="hdlist1">\r
 385 instance\r
 386 </dt>\r
 387 <dd>\r
 388 <p>\r
 389         Instance of the block, if set\r
 390 </p>\r
 391 </dd>\r
 392 <dt class="hdlist1">\r
 393 x, y\r
 394 </dt>\r
 395 <dd>\r
 396 <p>\r
 397         X11 root window coordinates where the click occurred\r
 398 </p>\r
 399 </dd>\r
 400 <dt class="hdlist1">\r
 401 button\r
 402 </dt>\r
 403 <dd>\r
 404 <p>\r
 405         X11 button ID (for example 1 to 3 for left/middle/right mouse button)\r
 406 </p>\r
 407 </dd>\r
 408 </dl></div>\r
 409 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 410 <div class="listingblock">\r
 411 <div class="content">\r
 412 <pre><tt>{\r
 413  "name": "ethernet",\r
 414  "instance": "eth0",\r
 415  "button": 1,\r
 416  "x": 1320,\r
 417  "y": 1400\r
 418 }</tt></pre>\r
 419 </div></div>\r
 420 </div>\r
 421 </div>\r
 422 </div>\r
 423 </div>\r
 424 <div id="footnotes"><hr /></div>\r
 425 <div id="footer" lang="de">\r
 426 © 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>\r
 427 </div>\r
 428 </body>\r
 429 </html>\r