"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
+<link rel="icon" type="image/x-icon" href="/favicon.ico">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.4" />\r
+<meta name="generator" content="AsciiDoc 8.6.9" />\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
+document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes();}, false);\r
/*]]>*/\r
</script>\r
<script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\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="https://www.reddit.com/r/i3wm/">FAQ</a></li>\r
<li><a href="/contact">Contact</a></li>\r
- <li><a href="http://bugs.i3wm.org/">Bugs</a></li>\r
+ <li><a href="https://github.com/i3/i3/issues">Bugs</a></li>\r
</ul>\r
<br style="clear: both">\r
<div id="content">\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
+<span id="revdate">August 2012</span>\r
</div>\r
<div id="preamble">\r
<div class="sectionbody">\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_rationale_for_chosing_json">1. Rationale for chosing JSON</h2>\r
+<h2 id="_rationale_for_choosing_json">1. Rationale for choosing 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
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="paragraph"><p><strong>Minimal 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><strong>All features example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{ "version": 1, "stop_signal": 10, "cont_signal": 12, "click_events": true }</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>(Note that before i3 v4.3 the precise format had to be <tt>{"version":1}</tt>,\r
+byte-for-byte.)</p></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
<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="paragraph"><p>You can find an example of a shell script which can be used as your\r
+<tt>status_command</tt> in the bar configuration at\r
+<a href="https://github.com/i3/i3/blob/next/contrib/trivial-bar-script.sh">https://github.com/i3/i3/blob/next/contrib/trivial-bar-script.sh</a></p></div>\r
+<div class="sect2">\r
+<h3 id="_header_in_detail">2.1. Header in detail</h3>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+version\r
+</dt>\r
+<dd>\r
+<p>\r
+ The version number (as an integer) of the i3bar protocol you will use.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+stop_signal\r
+</dt>\r
+<dd>\r
+<p>\r
+ Specify to i3bar the signal (as an integer) to send to stop your\r
+ processing.\r
+ The default value (if none is specified) is SIGSTOP.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+cont_signal\r
+</dt>\r
+<dd>\r
+<p>\r
+ Specify to i3bar the signal (as an integer)to send to continue your\r
+ processing.\r
+ The default value (if none is specified) is SIGCONT.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+click_events\r
+</dt>\r
+<dd>\r
+<p>\r
+ If specified and true i3bar will write an infinite array (same as above)\r
+ to your stdin.\r
+</p>\r
+</dd>\r
+</dl></div>\r
+</div>\r
<div class="sect2">\r
-<h3 id="_blocks_in_detail">2.1. Blocks in detail</h3>\r
+<h3 id="_blocks_in_detail">2.2. 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
+ The <tt>full_text</tt> will be displayed by i3bar on the status line. This is the\r
+ only required key.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+background\r
+</dt>\r
+<dd>\r
+<p>\r
+ Overrides the background color for this particular block.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+border\r
+</dt>\r
+<dd>\r
+<p>\r
+ Overrides the border color for this particular block.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+min_width\r
+</dt>\r
+<dd>\r
+<p>\r
+ The minimum width (in pixels) of the block. If the content of the\r
+ <tt>full_text</tt> key take less space than the specified min_width, the block\r
+ will be padded to the left and/or the right side, according to the <tt>align</tt>\r
+ key. This is useful when you want to prevent the whole status line to shift\r
+ when value take more or less space between each iteration.\r
+ The value can also be a string. In this case, the width of the text given\r
+ by <tt>min_width</tt> determines the minimum width of the block. This is useful\r
+ when you want to set a sensible minimum width regardless of which font you\r
+ are using, and at what particular size.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+align\r
+</dt>\r
+<dd>\r
+<p>\r
+ Align text on the <tt>center</tt>, <tt>right</tt> or <tt>left</tt> (default) of the block, when\r
+ the minimum width of the latter, specified by the <tt>min_width</tt> key, is not\r
+ reached.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
name and instance\r
</dt>\r
<dd>\r
space (for non-root users). The presentation of urgency is up to i3bar.\r
</p>\r
</dd>\r
+<dt class="hdlist1">\r
+separator\r
+</dt>\r
+<dd>\r
+<p>\r
+ A boolean which specifies whether a separator line should be drawn\r
+ after this block. The default is true, meaning the separator line will\r
+ be drawn. Note that if you disable the separator line, there will still\r
+ be a gap after the block, unless you also use <tt>separator_block_width</tt>.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+separator_block_width\r
+</dt>\r
+<dd>\r
+<p>\r
+ The amount of pixels to leave blank after the block. In the middle of\r
+ this gap, a separator line will be drawn unless <tt>separator</tt> is\r
+ disabled. Normally, you want to set this to an odd value (the default\r
+ is 9 pixels), since the separator line is drawn in the middle.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+markup\r
+</dt>\r
+<dd>\r
+<p>\r
+ A string that indicates how the text of the block should be parsed. Set to\r
+ <tt>"pango"</tt> to use <a href="https://developer.gnome.org/pango/stable/PangoMarkupFormat.html">Pango markup</a>.\r
+ Set to <tt>"none"</tt> to not use any markup (default). Pango markup only works\r
+ if you use a pango font.\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
"_ethernet_vendor": "Intel"\r
}</tt></pre>\r
</div></div>\r
+<div class="paragraph"><p>In the following example, the longest (widest) possible value of the block is\r
+used to set the minimum width:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{\r
+ "full_text": "CPU 4%",\r
+ "min_width": "CPU 100%",\r
+ "align": "left"\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
"full_text": "E: 10.0.0.1 (1000 Mbit/s)",\r
"short_text": "10.0.0.1",\r
"color": "#00ff00",\r
+ "background": "#1c1c1c",\r
+ "border": "#ee0000",\r
+ "min_width": 300,\r
+ "align": "right",\r
"urgent": false,\r
"name": "ethernet",\r
- "instance": "eth0"\r
+ "instance": "eth0",\r
+ "separator": true,\r
+ "separator_block_width": 9\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_click_events">2.3. Click events</h3>\r
+<div class="paragraph"><p>If enabled i3bar will send you notifications if the user clicks on a block and\r
+looks like this:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+name\r
+</dt>\r
+<dd>\r
+<p>\r
+ Name of the block, if set\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+instance\r
+</dt>\r
+<dd>\r
+<p>\r
+ Instance of the block, if set\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+x, y\r
+</dt>\r
+<dd>\r
+<p>\r
+ X11 root window coordinates where the click occurred\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+button\r
+</dt>\r
+<dd>\r
+<p>\r
+ X11 button ID (for example 1 to 3 for left/middle/right mouse button)\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+relative_x, relative_y\r
+</dt>\r
+<dd>\r
+<p>\r
+ Coordinates where the click occurred, with respect to the top left corner\r
+ of the block\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+width, height\r
+</dt>\r
+<dd>\r
+<p>\r
+ Width and height (in px) of the block\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{\r
+ "name": "ethernet",\r
+ "instance": "eth0",\r
+ "button": 1,\r
+ "x": 1320,\r
+ "y": 1400,\r
+ "relative_x": 12,\r
+ "relative_y": 8,\r
+ "width": 50,\r
+ "height": 22\r
}</tt></pre>\r
</div></div>\r
</div>\r
projects / i3 / i3.github.io / blobdiff