--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
+<head>\r
+<link rel="icon" type="image/png" href="/favicon.png">\r
+<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
+<meta name="generator" content="AsciiDoc 8.6.4" />\r
+<title>i3: i3bar input protocol</title>\r
+<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
+<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
+<script type="text/javascript">\r
+/*<![CDATA[*/\r
+window.onload = function(){asciidoc.footnotes();}\r
+/*]]>*/\r
+</script>\r
+<script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\r
+</head>\r
+<body class="article">\r
+\r
+ <div id="main">\r
+ <a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>\r
+ <ul id="nav">\r
+ <li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>\r
+ <li><a href="/screenshots">Screens</a></li>\r
+ <li><a href="/contact">Contact</a></li>\r
+ <li><a href="http://bugs.i3wm.org/">Bugs</a></li>\r
+ </ul>\r
+ <br style="clear: both">\r
+<div id="content">\r
+<div id="header">\r
+<h1>i3bar input protocol</h1>\r
+<span id="author">Michael Stapelberg</span><br />\r
+<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
+<span id="revdate">February 2012</span>\r
+</div>\r
+<div id="preamble">\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>This document explains the protocol in which i3bar expects its input. It\r
+provides support for colors, urgency, shortening and easy manipulation.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_rationale_for_chosing_json">1. Rationale for chosing JSON</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>Before describing the protocol, let’s cover why JSON is a building block of\r
+this protocol.</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+Other bar display programs such as dzen2 or xmobar are using in-band\r
+ signaling: they recognize certain sequences (like ^fg(#330000) in your input\r
+ text). We would like to avoid that and separate information from\r
+ meta-information. By information, we mean the actual output, like the IP\r
+ address of your ethernet adapter and by meta-information, we mean in which\r
+ color it should be displayed right now.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+It is easy to write a simple script which manipulates part(s) of the input.\r
+ Each block of information (like a block for the disk space indicator, a block\r
+ for the current IP address, etc.) can be identified specifically and modified\r
+ in whichever way you like.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+It remains easy to write a simple script which just suffixes (or prefixes) a\r
+ status line input, because tools like i3status will output their JSON in\r
+ such a way that each line array will be terminated by a newline. Therefore,\r
+ you are not required to use a streaming JSON parser, but you can use any\r
+ JSON parser and write your script in any programming language. In fact, you\r
+ can decide to not bother with the JSON parsing at all and just inject your\r
+ output at a specific position (beginning or end).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Relying on JSON does not introduce any new dependencies. In fact, the IPC\r
+ interface of i3 also uses JSON, therefore i3bar already depends on JSON.\r
+</p>\r
+</li>\r
+</ol></div>\r
+<div class="paragraph"><p>The only point against using JSON is computational complexity. If that really\r
+bothers you, just use the plain text input format (which i3bar will continue to\r
+support).</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_the_protocol">2. The protocol</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>The first message of the protocol is a header block, which contains (at least)\r
+the version of the protocol to be used. In case there are significant changes\r
+(not only additions), the version will be incremented. i3bar will still\r
+understand the old protocol version, but in order to use the new one, you need\r
+to provide the correct version. The header block is terminated by a newline and\r
+consists of a single JSON hash:</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{ "version": 1 }</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>What follows is an infinite array (so it should be parsed by a streaming JSON\r
+parser, but as described above you can go for a simpler solution), whose\r
+elements are one array per status line. A status line is one unit of\r
+information which should be displayed at a time. i3bar will not display any\r
+input until the status line is complete. In each status line, every block will\r
+be represented by a JSON hash:</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>[\r
+\r
+ [\r
+ {\r
+ "full_text": "E: 10.0.0.1 (1000 Mbit/s)",\r
+ "color": "#00ff00"\r
+ },\r
+ {\r
+ "full_text": "2012-01-05 20:00:01"\r
+ }\r
+ ],\r
+\r
+ [\r
+ {\r
+ "full_text": "E: 10.0.0.1 (1000 Mbit/s)",\r
+ "color": "#00ff00"\r
+ },\r
+ {\r
+ "full_text": "2012-01-05 20:00:02"\r
+ }\r
+ ],\r
+ …</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Please note that this example was pretty printed for human consumption.\r
+i3status and others will output single statuslines in one line, separated by\r
+\n.</p></div>\r
+<div class="sect2">\r
+<h3 id="_blocks_in_detail">2.1. Blocks in detail</h3>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+full_text\r
+</dt>\r
+<dd>\r
+<p>\r
+ The most simple block you can think of is one which just includes the\r
+ only required key, the <tt>full_text</tt> key. i3bar will display the string\r
+ value and that’s it.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+short_text\r
+</dt>\r
+<dd>\r
+<p>\r
+ Where appropriate, the <tt>short_text</tt> (string) entry should also be\r
+ provided. It will be used in case the status line needs to be shortened\r
+ because it uses more space than your screen provides. For example, when\r
+ displaying an IPv6 address, the prefix is usually (!) more relevant\r
+ than the suffix, because the latter stays constant when using autoconf,\r
+ while the prefix changes. When displaying the date, the time is more\r
+ important than the date (it is more likely that you know which day it\r
+ is than what time it is).\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+color\r
+</dt>\r
+<dd>\r
+<p>\r
+ To make the current state of the information easy to spot, colors can\r
+ be used. For example, the wireless block could be displayed in red\r
+ (using the <tt>color</tt> (string) entry) if the card is not associated with\r
+ any network and in green or yellow (depending on the signal strength)\r
+ when it is associated.\r
+ Colors are specified in hex (like in HTML), starting with a leading\r
+ hash sign. For example, <tt>#ff0000</tt> means red.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+name and instance\r
+</dt>\r
+<dd>\r
+<p>\r
+ Every block should have a unique <tt>name</tt> (string) entry so that it can\r
+ be easily identified in scripts which process the output. i3bar\r
+ completely ignores the name and instance fields. Make sure to also\r
+ specify an <tt>instance</tt> (string) entry where appropriate. For example,\r
+ the user can have multiple disk space blocks for multiple mount points.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+urgent\r
+</dt>\r
+<dd>\r
+<p>\r
+ A boolean which specifies whether the current value is urgent. Examples\r
+ are battery charge values below 1 percent or no more available disk\r
+ space (for non-root users). The presentation of urgency is up to i3bar.\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p>If you want to put in your own entries into a block, prefix the key with an\r
+underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing\r
+them with an underscore makes it clear in every script that they are not part\r
+of the i3bar protocol.</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{\r
+ "full_text": "E: 10.0.0.1 (1000 Mbit/s)",\r
+ "_ethernet_vendor": "Intel"\r
+}</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>An example of a block which uses all possible entries follows:</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{\r
+ "full_text": "E: 10.0.0.1 (1000 Mbit/s)",\r
+ "short_text": "10.0.0.1",\r
+ "color": "#00ff00",\r
+ "urgent": false,\r
+ "name": "ethernet",\r
+ "instance": "eth0"\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
+</div>\r
+</div>\r
+</div>\r
+<div id="footnotes"><hr /></div>\r
+<div id="footer" lang="de">\r
+© 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>\r
+</div>\r
+</body>\r
+</html>\r
projects / i3 / i3.github.io / blobdiff