File: i3bar-protocol.html

package info (click to toggle)
i3-wm 4.13-1%2Bdeb9u1
links: PTS
area: main
in suites: stretch
size: 5,836 kB
sloc: ansic: 27,729; perl: 12,829; sh: 4,449; makefile: 485
file content (1141 lines) | stat: -rw-r--r-- 29,692 bytes
parent folder | download | duplicates (2)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.9" />
<title>i3bar input protocol</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */

/* Default font. */
body {
  font-family: Georgia,serif;
}

/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
  font-family: Arial,Helvetica,sans-serif;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}
h5 {
  font-size: 1.0em;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

.monospaced, code, pre {
  font-family: "Courier New", Courier, monospace;
  font-size: inherit;
  color: navy;
  padding: 0;
  margin: 0;
}
pre {
  white-space: pre-wrap;
}

#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}

#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #888;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; vertical-align: text-bottom; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}

div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  #footer-badges { display: none; }
}

#toc {
  margin-bottom: 2.5em;
}

#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }

span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }

span.big { font-size: 2em; }
span.small { font-size: 0.6em; }

span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }

div.unbreakable { page-break-inside: avoid; }


/*
 * xhtml11 specific
 *
 * */

div.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


/*
 * html5 specific
 *
 * */

table.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
thead, p.tableblock.header {
  font-weight: bold;
  color: #527bbd;
}
p.tableblock {
  margin-top: 0;
}
table.tableblock {
  border-width: 3px;
  border-spacing: 0px;
  border-style: solid;
  border-color: #527bbd;
  border-collapse: collapse;
}
th.tableblock, td.tableblock {
  border-width: 1px;
  padding: 4px;
  border-style: solid;
  border-color: #527bbd;
}

table.tableblock.frame-topbot {
  border-left-style: hidden;
  border-right-style: hidden;
}
table.tableblock.frame-sides {
  border-top-style: hidden;
  border-bottom-style: hidden;
}
table.tableblock.frame-none {
  border-style: hidden;
}

th.tableblock.halign-left, td.tableblock.halign-left {
  text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
  text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
  text-align: right;
}

th.tableblock.valign-top, td.tableblock.valign-top {
  vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
  vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
  vertical-align: bottom;
}


/*
 * manpage specific
 *
 * */

body.manpage h1 {
  padding-top: 0.5em;
  padding-bottom: 0.5em;
  border-top: 2px solid silver;
  border-bottom: 2px solid silver;
}
body.manpage h2 {
  border-style: none;
}
body.manpage div.sectionbody {
  margin-left: 3em;
}

@media print {
  body.manpage div#toc { display: none; }
}


</style>
<script type="text/javascript">
/*<![CDATA[*/
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  if (!toc) {
    return;
  }

  // Delete existing TOC entries in case we're reloading the TOC.
  var tocEntriesToRemove = [];
  var i;
  for (i = 0; i < toc.childNodes.length; i++) {
    var entry = toc.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div'
     && entry.getAttribute("class")
     && entry.getAttribute("class").match(/^toclevel/))
      tocEntriesToRemove.push(entry);
  }
  for (i = 0; i < tocEntriesToRemove.length; i++) {
    toc.removeChild(tocEntriesToRemove[i]);
  }

  // Rebuild TOC entries.
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  // Delete existing footnote entries in case we're reloading the footnodes.
  var i;
  var noteholder = document.getElementById("footnotes");
  if (!noteholder) {
    return;
  }
  var entriesToRemove = [];
  for (i = 0; i < noteholder.childNodes.length; i++) {
    var entry = noteholder.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
      entriesToRemove.push(entry);
  }
  for (i = 0; i < entriesToRemove.length; i++) {
    noteholder.removeChild(entriesToRemove[i]);
  }

  // Rebuild footnote entries.
  var cont = document.getElementById("content");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      var note = spans[i].getAttribute("data-note");
      if (!note) {
        // Use [\s\S] in place of . so multi-line matches work.
        // Because JavaScript has no s (dotall) regex flag.
        note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
        spans[i].innerHTML =
          "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
        spans[i].setAttribute("data-note", note);
      }
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
},

install: function(toclevels) {
  var timerId;

  function reinstall() {
    asciidoc.footnotes();
    if (toclevels) {
      asciidoc.toc(toclevels);
    }
  }

  function reinstallAndRemoveTimer() {
    clearInterval(timerId);
    reinstall();
  }

  timerId = setInterval(reinstall, 500);
  if (document.addEventListener)
    document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
  else
    window.onload = reinstallAndRemoveTimer;
}

}
asciidoc.install(2);
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1>i3bar input protocol</h1>
<span id="author">Michael Stapelberg</span><br />
<span id="email"><code>&lt;<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>&gt;</code></span><br />
<span id="revdate">August 2012</span>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>This document explains the protocol in which i3bar expects its input. It
provides support for colors, urgency, shortening and easy manipulation.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_rationale_for_choosing_json">1. Rationale for choosing JSON</h2>
<div class="sectionbody">
<div class="paragraph"><p>Before describing the protocol, let’s cover why JSON is a building block of
this protocol.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Other bar display programs such as dzen2 or xmobar are using in-band
   signaling: they recognize certain sequences (like ^fg(#330000) in your input
   text). We would like to avoid that and separate information from
   meta-information. By information, we mean the actual output, like the IP
   address of your ethernet adapter and by meta-information, we mean in which
   color it should be displayed right now.
</p>
</li>
<li>
<p>
It is easy to write a simple script which manipulates part(s) of the input.
   Each block of information (like a block for the disk space indicator, a block
   for the current IP address, etc.) can be identified specifically and modified
   in whichever way you like.
</p>
</li>
<li>
<p>
It remains easy to write a simple script which just suffixes (or prefixes) a
   status line input, because tools like i3status will output their JSON in
   such a way that each line array will be terminated by a newline. Therefore,
   you are not required to use a streaming JSON parser, but you can use any
   JSON parser and write your script in any programming language. In fact, you
   can decide to not bother with the JSON parsing at all and just inject your
   output at a specific position (beginning or end).
</p>
</li>
<li>
<p>
Relying on JSON does not introduce any new dependencies. In fact, the IPC
   interface of i3 also uses JSON, therefore i3bar already depends on JSON.
</p>
</li>
</ol></div>
<div class="paragraph"><p>The only point against using JSON is computational complexity. If that really
bothers you, just use the plain text input format (which i3bar will continue to
support).</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_the_protocol">2. The protocol</h2>
<div class="sectionbody">
<div class="paragraph"><p>The first message of the protocol is a header block, which contains (at least)
the version of the protocol to be used. In case there are significant changes
(not only additions), the version will be incremented. i3bar will still
understand the old protocol version, but in order to use the new one, you need
to provide the correct version. The header block is terminated by a newline and
consists of a single JSON hash:</p></div>
<div class="paragraph"><p><strong>Minimal example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>{ "version": 1 }</code></pre>
</div></div>
<div class="paragraph"><p><strong>All features example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>{ "version": 1, "stop_signal": 10, "cont_signal": 12, "click_events": true }</code></pre>
</div></div>
<div class="paragraph"><p>(Note that before i3 v4.3 the precise format had to be <code>{"version":1}</code>,
byte-for-byte.)</p></div>
<div class="paragraph"><p>What follows is an infinite array (so it should be parsed by a streaming JSON
parser, but as described above you can go for a simpler solution), whose
elements are one array per status line. A status line is one unit of
information which should be displayed at a time. i3bar will not display any
input until the status line is complete. In each status line, every block will
be represented by a JSON hash:</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>[

 [
  {
   "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
   "color": "#00ff00"
  },
  {
   "full_text": "2012-01-05 20:00:01"
  }
 ],

 [
  {
   "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
   "color": "#00ff00"
  },
  {
   "full_text": "2012-01-05 20:00:02"
  }
 ],
 …</code></pre>
</div></div>
<div class="paragraph"><p>Please note that this example was pretty printed for human consumption.
i3status and others will output single statuslines in one line, separated by
\n.</p></div>
<div class="paragraph"><p>You can find an example of a shell script which can be used as your
<code>status_command</code> in the bar configuration at
<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>
<div class="sect2">
<h3 id="_header_in_detail">2.1. Header in detail</h3>
<div class="dlist"><dl>
<dt class="hdlist1">
version
</dt>
<dd>
<p>
        The version number (as an integer) of the i3bar protocol you will use.
</p>
</dd>
<dt class="hdlist1">
stop_signal
</dt>
<dd>
<p>
        Specify to i3bar the signal (as an integer) to send to stop your
        processing.
        The default value (if none is specified) is SIGSTOP.
</p>
</dd>
<dt class="hdlist1">
cont_signal
</dt>
<dd>
<p>
        Specify to i3bar the signal (as an integer)to send to continue your
        processing.
        The default value (if none is specified) is SIGCONT.
</p>
</dd>
<dt class="hdlist1">
click_events
</dt>
<dd>
<p>
        If specified and true i3bar will write an infinite array (same as above)
        to your stdin.
</p>
</dd>
</dl></div>
</div>
<div class="sect2">
<h3 id="_blocks_in_detail">2.2. Blocks in detail</h3>
<div class="dlist"><dl>
<dt class="hdlist1">
full_text
</dt>
<dd>
<p>
        The <code>full_text</code> will be displayed by i3bar on the status line. This is the
        only required key.
</p>
</dd>
<dt class="hdlist1">
short_text
</dt>
<dd>
<p>
        Where appropriate, the <code>short_text</code> (string) entry should also be
        provided. It will be used in case the status line needs to be shortened
        because it uses more space than your screen provides. For example, when
        displaying an IPv6 address, the prefix is usually (!) more relevant
        than the suffix, because the latter stays constant when using autoconf,
        while the prefix changes. When displaying the date, the time is more
        important than the date (it is more likely that you know which day it
        is than what time it is).
</p>
</dd>
<dt class="hdlist1">
color
</dt>
<dd>
<p>
        To make the current state of the information easy to spot, colors can
        be used. For example, the wireless block could be displayed in red
        (using the <code>color</code> (string) entry) if the card is not associated with
        any network and in green or yellow (depending on the signal strength)
        when it is associated.
        Colors are specified in hex (like in HTML), starting with a leading
        hash sign. For example, <code>#ff0000</code> means red.
</p>
</dd>
<dt class="hdlist1">
background
</dt>
<dd>
<p>
        Overrides the background color for this particular block.
</p>
</dd>
<dt class="hdlist1">
border
</dt>
<dd>
<p>
        Overrides the border color for this particular block.
</p>
</dd>
<dt class="hdlist1">
min_width
</dt>
<dd>
<p>
        The minimum width (in pixels) of the block. If the content of the
        <code>full_text</code> key take less space than the specified min_width, the block
        will be padded to the left and/or the right side, according to the <code>align</code>
        key. This is useful when you want to prevent the whole status line to shift
        when value take more or less space between each iteration.
        The value can also be a string. In this case, the width of the text given
        by <code>min_width</code> determines the minimum width of the block. This is useful
        when you want to set a sensible minimum width regardless of which font you
        are using, and at what particular size.
</p>
</dd>
<dt class="hdlist1">
align
</dt>
<dd>
<p>
        Align text on the <code>center</code>, <code>right</code> or <code>left</code> (default) of the block, when
        the minimum width of the latter, specified by the <code>min_width</code> key, is not
        reached.
</p>
</dd>
<dt class="hdlist1">
name and instance
</dt>
<dd>
<p>
        Every block should have a unique <code>name</code> (string) entry so that it can
        be easily identified in scripts which process the output. i3bar
        completely ignores the name and instance fields. Make sure to also
        specify an <code>instance</code> (string) entry where appropriate. For example,
        the user can have multiple disk space blocks for multiple mount points.
</p>
</dd>
<dt class="hdlist1">
urgent
</dt>
<dd>
<p>
        A boolean which specifies whether the current value is urgent. Examples
        are battery charge values below 1 percent or no more available disk
        space (for non-root users). The presentation of urgency is up to i3bar.
</p>
</dd>
<dt class="hdlist1">
separator
</dt>
<dd>
<p>
        A boolean which specifies whether a separator line should be drawn
        after this block. The default is true, meaning the separator line will
        be drawn. Note that if you disable the separator line, there will still
        be a gap after the block, unless you also use <code>separator_block_width</code>.
</p>
</dd>
<dt class="hdlist1">
separator_block_width
</dt>
<dd>
<p>
        The amount of pixels to leave blank after the block. In the middle of
        this gap, a separator line will be drawn unless <code>separator</code> is
        disabled. Normally, you want to set this to an odd value (the default
        is 9 pixels), since the separator line is drawn in the middle.
</p>
</dd>
<dt class="hdlist1">
markup
</dt>
<dd>
<p>
        A string that indicates how the text of the block should be parsed. Set to
        <code>"pango"</code> to use <a href="https://developer.gnome.org/pango/stable/PangoMarkupFormat.html">Pango markup</a>.
        Set to <code>"none"</code> to not use any markup (default).
</p>
</dd>
</dl></div>
<div class="paragraph"><p>If you want to put in your own entries into a block, prefix the key with an
underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing
them with an underscore makes it clear in every script that they are not part
of the i3bar protocol.</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>{
 "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
 "_ethernet_vendor": "Intel"
}</code></pre>
</div></div>
<div class="paragraph"><p>In the following example, the longest (widest) possible value of the block is
used to set the minimum width:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>{
 "full_text": "CPU 4%",
 "min_width": "CPU 100%",
 "align": "left"
}</code></pre>
</div></div>
<div class="paragraph"><p>An example of a block which uses all possible entries follows:</p></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>{
 "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
 "short_text": "10.0.0.1",
 "color": "#00ff00",
 "background": "#1c1c1c",
 "border": "#ee0000",
 "min_width": 300,
 "align": "right",
 "urgent": false,
 "name": "ethernet",
 "instance": "eth0",
 "separator": true,
 "separator_block_width": 9
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_click_events">2.3. Click events</h3>
<div class="paragraph"><p>If enabled i3bar will send you notifications if the user clicks on a block and
looks like this:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
name
</dt>
<dd>
<p>
        Name of the block, if set
</p>
</dd>
<dt class="hdlist1">
instance
</dt>
<dd>
<p>
        Instance of the block, if set
</p>
</dd>
<dt class="hdlist1">
x, y
</dt>
<dd>
<p>
        X11 root window coordinates where the click occurred
</p>
</dd>
<dt class="hdlist1">
button
</dt>
<dd>
<p>
        X11 button ID (for example 1 to 3 for left/middle/right mouse button)
</p>
</dd>
</dl></div>
<div class="paragraph"><p><strong>Example</strong>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>{
 "name": "ethernet",
 "instance": "eth0",
 "button": 1,
 "x": 1320,
 "y": 1400
}</code></pre>
</div></div>
</div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated
 2016-11-08 19:54:01 CET
</div>
</div>
</body>
</html>