File: hacking-howto.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 (2327 lines) | stat: -rw-r--r-- 79,862 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>Hacking i3: How To</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>Hacking i3: How To</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">February 2013</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 is intended to be the first thing you read before looking and/or
touching i3’s source code. It should contain all important information to help
you understand why things are like they are. If it does not mention something
you find necessary, please do not hesitate to contact me.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_window_managers">1. Window Managers</h2>
<div class="sectionbody">
<div class="paragraph"><p>A window manager is not necessarily needed to run X, but it is usually used in
combination with X to facilitate some things. The window manager&#8217;s job is to
take care of the placement of windows, to provide the user with some mechanisms
to change the position/size of windows and to communicate with clients to a
certain extent (for example handle fullscreen requests of clients such as
MPlayer).</p></div>
<div class="paragraph"><p>There are no different contexts in which X11 clients run, so a window manager
is just another client, like all other X11 applications. However, it handles
some events which normal clients usually don’t handle.</p></div>
<div class="paragraph"><p>In the case of i3, the tasks (and order of them) are the following:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Grab the key bindings (events will be sent upon keypress/keyrelease)
</p>
</li>
<li>
<p>
Iterate through all existing windows (if the window manager is not started as
  the first client of X) and manage them (reparent them, create window
  decorations, etc.)
</p>
</li>
<li>
<p>
When new windows are created, manage them
</p>
</li>
<li>
<p>
Handle the client’s <code>_WM_STATE</code> property, but only <code>_WM_STATE_FULLSCREEN</code> and
  <code>_NET_WM_STATE_DEMANDS_ATTENTION</code>
</p>
</li>
<li>
<p>
Handle the client’s <code>WM_NAME</code> property
</p>
</li>
<li>
<p>
Handle the client’s size hints to display them proportionally
</p>
</li>
<li>
<p>
Handle the client’s urgency hint
</p>
</li>
<li>
<p>
Handle enter notifications (focus follows mouse)
</p>
</li>
<li>
<p>
Handle button (as in mouse buttons) presses for focus/raise on click
</p>
</li>
<li>
<p>
Handle expose events to re-draw own windows such as decorations
</p>
</li>
<li>
<p>
React to the user’s commands: Change focus, Move windows, Switch workspaces,
  Change the layout mode of a container (default/stacking/tabbed), start a new
  application, restart the window manager
</p>
</li>
</ol></div>
<div class="paragraph"><p>In the following chapters, each of these tasks and their implementation details
will be discussed.</p></div>
<div class="sect2">
<h3 id="_tiling_window_managers">1.1. Tiling window managers</h3>
<div class="paragraph"><p>Traditionally, there are two approaches to managing windows: The most common
one nowadays is floating, which means the user can freely move/resize the
windows. The other approach is called tiling, which means that your window
manager distributes windows to use as much space as possible while not
overlapping each other.</p></div>
<div class="paragraph"><p>The idea behind tiling is that you should not need to waste your time
moving/resizing windows while you usually want to get some work done. After
all, most users sooner or later tend to lay out their windows in a way which
corresponds to tiling or stacking mode in i3. Therefore, why not let i3 do this
for you? Certainly, it’s faster than you could ever do it.</p></div>
<div class="paragraph"><p>The problem with most tiling window managers is that they are too inflexible.
In my opinion, a window manager is just another tool, and similar to vim which
can edit all kinds of text files (like source code, HTML, …) and is not limited
to a specific file type, a window manager should not limit itself to a certain
layout (like dwm, awesome, …) but provide mechanisms for you to easily create
the layout you need at the moment.</p></div>
</div>
<div class="sect2">
<h3 id="_the_layout_tree">1.2. The layout tree</h3>
<div class="paragraph"><p>The data structure which i3 uses to keep track of your windows is a tree. Every
node in the tree is a container (type <code>Con</code>). Some containers represent actual
windows (every container with a <code>window != NULL</code>), some represent split
containers and a few have special purposes: they represent workspaces, outputs
(like VGA1, LVDS1, …) or the X11 root window.</p></div>
<div class="paragraph"><p>So, when you open a terminal and immediately open another one, they reside in
the same split container, which uses the default layout. In case of an empty
workspace, the split container we are talking about is the workspace.</p></div>
<div class="paragraph"><p>To get an impression of how different layouts are represented, just play around
and look at the data structures&#8201;&#8212;&#8201;they are exposed as a JSON hash. See
<a href="http://i3wm.org/docs/ipc.html#_tree_reply">http://i3wm.org/docs/ipc.html#_tree_reply</a> for documentation on that and an
example.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_files">2. Files</h2>
<div class="sectionbody">
<div class="dlist"><dl>
<dt class="hdlist1">
include/atoms.xmacro
</dt>
<dd>
<p>
A file containing all X11 atoms which i3 uses. This file will be included
various times (for defining, requesting and receiving the atoms), each time
with a different definition of xmacro().
</p>
</dd>
<dt class="hdlist1">
include/data.h
</dt>
<dd>
<p>
Contains data definitions used by nearly all files. You really need to read
this first.
</p>
</dd>
<dt class="hdlist1">
include/*.h
</dt>
<dd>
<p>
Contains forward definitions for all public functions, as well as
doxygen-compatible comments (so if you want to get a bit more of the big
picture, either browse all header files or use doxygen if you prefer that).
</p>
</dd>
<dt class="hdlist1">
src/config_parser.c
</dt>
<dd>
<p>
Contains a custom configuration parser. See src/command_parser.c for rationale
 on why we use a custom parser.
</p>
</dd>
<dt class="hdlist1">
src/click.c
</dt>
<dd>
<p>
Contains all functions which handle mouse button clicks (right mouse button
clicks initiate resizing and thus are relatively complex).
</p>
</dd>
<dt class="hdlist1">
src/command_parser.c
</dt>
<dd>
<p>
Contains a hand-written parser to parse commands (commands are what
you bind on keys and what you can send to i3 using the IPC interface, like
<em>move left</em> or <em>workspace 4</em>).
</p>
</dd>
<dt class="hdlist1">
src/con.c
</dt>
<dd>
<p>
Contains all functions which deal with containers directly (creating
containers, searching containers, getting specific properties from containers,
…).
</p>
</dd>
<dt class="hdlist1">
src/config.c
</dt>
<dd>
<p>
Contains all functions handling the configuration file (calling the parser
src/config_parser.c) with the correct path, switching key bindings mode).
</p>
</dd>
<dt class="hdlist1">
src/debug.c
</dt>
<dd>
<p>
Contains debugging functions to print unhandled X events.
</p>
</dd>
<dt class="hdlist1">
src/ewmh.c
</dt>
<dd>
<p>
Functions to get/set certain EWMH properties easily.
</p>
</dd>
<dt class="hdlist1">
src/floating.c
</dt>
<dd>
<p>
Contains functions for floating mode (mostly resizing/dragging).
</p>
</dd>
<dt class="hdlist1">
src/handlers.c
</dt>
<dd>
<p>
Contains all handlers for all kinds of X events (new window title, new hints,
unmapping, key presses, button presses, …).
</p>
</dd>
<dt class="hdlist1">
src/ipc.c
</dt>
<dd>
<p>
Contains code for the IPC interface.
</p>
</dd>
<dt class="hdlist1">
src/load_layout.c
</dt>
<dd>
<p>
Contains code for loading layouts from JSON files.
</p>
</dd>
<dt class="hdlist1">
src/log.c
</dt>
<dd>
<p>
Contains the logging functions.
</p>
</dd>
<dt class="hdlist1">
src/main.c
</dt>
<dd>
<p>
Initializes the window manager.
</p>
</dd>
<dt class="hdlist1">
src/manage.c
</dt>
<dd>
<p>
Looks at existing or new windows and decides whether to manage them. If so, it
reparents the window and inserts it into our data structures.
</p>
</dd>
<dt class="hdlist1">
src/match.c
</dt>
<dd>
<p>
A "match" is a data structure which acts like a mask or expression to match
certain windows or not. For example, when using commands, you can specify a
command like this: [title="<strong>Firefox</strong>"] kill. The title member of the match
data structure will then be filled and i3 will check each window using
match_matches_window() to find the windows affected by this command.
</p>
</dd>
<dt class="hdlist1">
src/move.c
</dt>
<dd>
<p>
Contains code to move a container in a specific direction.
</p>
</dd>
<dt class="hdlist1">
src/output.c
</dt>
<dd>
<p>
Functions to handle CT_OUTPUT cons.
</p>
</dd>
<dt class="hdlist1">
src/randr.c
</dt>
<dd>
<p>
The RandR API is used to get (and re-query) the configured outputs (monitors,
…).
</p>
</dd>
<dt class="hdlist1">
src/render.c
</dt>
<dd>
<p>
Renders the tree data structure by assigning coordinates to every node. These
values will later be pushed to X11 in <code>src/x.c</code>.
</p>
</dd>
<dt class="hdlist1">
src/resize.c
</dt>
<dd>
<p>
Contains the functions to resize containers.
</p>
</dd>
<dt class="hdlist1">
src/restore_layout.c
</dt>
<dd>
<p>
Everything for restored containers that is not pure state parsing (which can be
found in load_layout.c).
</p>
</dd>
<dt class="hdlist1">
src/sighandler.c
</dt>
<dd>
<p>
Handles <code>SIGSEGV</code>, <code>SIGABRT</code> and <code>SIGFPE</code> by showing a dialog that i3 crashed.
You can chose to let it dump core, to restart it in-place or to restart it
in-place but forget about the layout.
</p>
</dd>
<dt class="hdlist1">
src/tree.c
</dt>
<dd>
<p>
Contains functions which open or close containers in the tree, change focus or
cleanup ("flatten") the tree. See also <code>src/move.c</code> for another similar
function, which was moved into its own file because it is so long.
</p>
</dd>
<dt class="hdlist1">
src/util.c
</dt>
<dd>
<p>
Contains useful functions which are not really dependent on anything.
</p>
</dd>
<dt class="hdlist1">
src/window.c
</dt>
<dd>
<p>
Handlers to update X11 window properties like <code>WM_CLASS</code>, <code>_NET_WM_NAME</code>,
<code>CLIENT_LEADER</code>, etc.
</p>
</dd>
<dt class="hdlist1">
src/workspace.c
</dt>
<dd>
<p>
Contains all functions related to workspaces (displaying, hiding, renaming…)
</p>
</dd>
<dt class="hdlist1">
src/x.c
</dt>
<dd>
<p>
Transfers our in-memory tree (see <code>src/render.c</code>) to X11.
</p>
</dd>
<dt class="hdlist1">
src/xcb.c
</dt>
<dd>
<p>
Contains wrappers to use xcb more easily.
</p>
</dd>
<dt class="hdlist1">
src/xcursor.c
</dt>
<dd>
<p>
XCursor functions (for cursor themes).
</p>
</dd>
<dt class="hdlist1">
src/xinerama.c
</dt>
<dd>
<p>
Legacy support for Xinerama. See <code>src/randr.c</code> for the preferred API.
</p>
</dd>
</dl></div>
</div>
</div>
<div class="sect1">
<h2 id="_data_structures">3. Data structures</h2>
<div class="sectionbody">
<div class="paragraph"><p>See include/data.h for documented data structures. The most important ones are
explained right here.</p></div>
<div class="paragraph"><p>So, the hierarchy is:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
<strong>X11 root window</strong>, the root container
</p>
</li>
<li>
<p>
<strong>Output container</strong> (LVDS1 in this example)
</p>
</li>
<li>
<p>
<strong>Content container</strong> (there are also containers for dock windows)
</p>
</li>
<li>
<p>
<strong>Workspaces</strong> (Workspace 1 in this example, with horizontal orientation)
</p>
</li>
<li>
<p>
<strong>Split container</strong> (vertically split)
</p>
</li>
<li>
<p>
<strong>X11 window containers</strong>
</p>
</li>
</ol></div>
<div class="paragraph"><p>The data type is <code>Con</code>, in all cases.</p></div>
<div class="sect2">
<h3 id="_x11_root_window">3.1. X11 root window</h3>
<div class="paragraph"><p>The X11 root window is a single window per X11 display (a display is identified
by <code>:0</code> or <code>:1</code> etc.). The root window is what you draw your background image
on. It spans all the available outputs, e.g. <code>VGA1</code> is a specific part of the
root window and <code>LVDS1</code> is a specific part of the root window.</p></div>
</div>
<div class="sect2">
<h3 id="_output_container">3.2. Output container</h3>
<div class="paragraph"><p>Every active output obtained through RandR is represented by one output
container. Outputs are considered active when a mode is configured (meaning
something is actually displayed on the output) and the output is not a clone.</p></div>
<div class="paragraph"><p>For example, if your notebook has a screen resolution of 1280x800 px and you
connect a video projector with a resolution of 1024x768 px, set it up in clone
mode (<code>xrandr --output VGA1 --mode 1024x768 --same-as LVDS1</code>), i3 will
reduce the resolution to the lowest common resolution and disable one of the
cloned outputs afterwards.</p></div>
<div class="paragraph"><p>However, if you configure it using <code>xrandr --output VGA1 --mode 1024x768
--right-of LVDS1</code>, i3 will set both outputs active. For each output, a new
workspace will be assigned. New workspaces are created on the output you are
currently on.</p></div>
</div>
<div class="sect2">
<h3 id="_content_container">3.3. Content container</h3>
<div class="paragraph"><p>Each output has multiple children. Two of them are dock containers which hold
dock clients. The other one is the content container, which holds the actual
content (workspaces) of this output.</p></div>
</div>
<div class="sect2">
<h3 id="_workspace">3.4. Workspace</h3>
<div class="paragraph"><p>A workspace is identified by its name. Basically, you could think of
workspaces as different desks in your office, if you like the desktop
metaphor. They just contain different sets of windows and are completely
separate of each other. Other window managers also call this &#8220;Virtual
desktops&#8221;.</p></div>
</div>
<div class="sect2">
<h3 id="_split_container">3.5. Split container</h3>
<div class="paragraph"><p>A split container is a container which holds an arbitrary amount of split
containers or X11 window containers. It has an orientation (horizontal or
vertical) and a layout.</p></div>
<div class="paragraph"><p>Split containers (and X11 window containers, which are a subtype of split
containers) can have different border styles.</p></div>
</div>
<div class="sect2">
<h3 id="_x11_window_container">3.6. X11 window container</h3>
<div class="paragraph"><p>An X11 window container holds exactly one X11 window. These are the leaf nodes
of the layout tree, they cannot have any children.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_list_queue_macros">4. List/queue macros</h2>
<div class="sectionbody">
<div class="paragraph"><p>i3 makes heavy use of the list macros defined in BSD operating systems. To
ensure that the operating system on which i3 is compiled has all the expected
features, i3 comes with <code>include/queue.h</code>. On BSD systems, you can use man
<code>queue(3)</code>. On Linux, you have to use google (or read the source).</p></div>
<div class="paragraph"><p>The lists used are <code>SLIST</code> (single linked lists), <code>CIRCLEQ</code> (circular
queues) and <code>TAILQ</code> (tail queues). Usually, only forward traversal is necessary,
so an <code>SLIST</code> works fine. If inserting elements at arbitrary positions or at
the end of a list is necessary, a <code>TAILQ</code> is used instead. However, for the
windows inside a container, a <code>CIRCLEQ</code> is necessary to go from the currently
selected window to the window above/below.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_naming_conventions">5. Naming conventions</h2>
<div class="sectionbody">
<div class="paragraph"><p>There is a row of standard variables used in many events. The following names
should be chosen for those:</p></div>
<div class="ulist"><ul>
<li>
<p>
&#8220;conn&#8221; is the xcb_connection_t
</p>
</li>
<li>
<p>
&#8220;event&#8221; is the event of the particular type
</p>
</li>
<li>
<p>
&#8220;con&#8221; names a container
</p>
</li>
<li>
<p>
&#8220;current&#8221; is a loop variable when using <code>TAILQ_FOREACH</code> etc.
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_startup_src_mainx_c_main">6. Startup (src/mainx.c, main())</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
<p>
Establish the xcb connection
</p>
</li>
<li>
<p>
Check for XKB extension on the separate X connection, load Xcursor
</p>
</li>
<li>
<p>
Check for RandR screens (with a fall-back to Xinerama)
</p>
</li>
<li>
<p>
Grab the keycodes for which bindings exist
</p>
</li>
<li>
<p>
Manage all existing windows
</p>
</li>
<li>
<p>
Enter the event loop
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_keybindings">7. Keybindings</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_grabbing_the_bindings">7.1. Grabbing the bindings</h3>
<div class="paragraph"><p>Grabbing the bindings is quite straight-forward. You pass X your combination of
modifiers and the keycode you want to grab and whether you want to grab them
actively or passively. Most bindings (everything except for bindings using
Mode_switch) are grabbed passively, that is, just the window manager gets the
event and cannot replay it.</p></div>
<div class="paragraph"><p>We need to grab bindings that use Mode_switch actively because of a bug in X.
When the window manager receives the keypress/keyrelease event for an actively
grabbed keycode, it has to decide what to do with this event: It can either
replay it so that other applications get it or it can prevent other
applications from receiving it.</p></div>
<div class="paragraph"><p>So, why do we need to grab keycodes actively? Because X does not set the
state-property of keypress/keyrelease events properly. The Mode_switch bit is
not set and we need to get it using XkbGetState. This means we cannot pass X
our combination of modifiers containing Mode_switch when grabbing the key and
therefore need to grab the keycode itself without any modifiers. This means,
if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and
check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it
will handle the event, if not, it will replay the event.</p></div>
</div>
<div class="sect2">
<h3 id="_handling_a_keypress">7.2. Handling a keypress</h3>
<div class="paragraph"><p>As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets
the correct state.</p></div>
<div class="paragraph"><p>Then, it looks through all bindings and gets the one which matches the received
event.</p></div>
<div class="paragraph"><p>The bound command is parsed by the cmdparse lexer/parser, see <code>parse_cmd</code> in
<code>src/cmdparse.y</code>.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_manage_windows_src_main_c_manage_window_and_reparent_window">8. Manage windows (src/main.c, manage_window() and reparent_window())</h2>
<div class="sectionbody">
<div class="paragraph"><p><code>manage_window()</code> does some checks to decide whether the window should be
managed at all:</p></div>
<div class="ulist"><ul>
<li>
<p>
Windows have to be mapped, that is, visible on screen
</p>
</li>
<li>
<p>
The override_redirect must not be set. Windows with override_redirect shall
   not be managed by a window manager
</p>
</li>
</ul></div>
<div class="paragraph"><p>Afterwards, i3 gets the initial geometry and reparents the window (see
<code>reparent_window()</code>) if it wasn’t already managed.</p></div>
<div class="paragraph"><p>Reparenting means that for each window which is reparented, a new window,
slightly larger than the original one, is created. The original window is then
reparented to the bigger one (called "frame").</p></div>
<div class="paragraph"><p>After reparenting, the window type (<code>_NET_WM_WINDOW_TYPE</code>) is checked to see
whether this window is a dock (<code>_NET_WM_WINDOW_TYPE_DOCK</code>), like dzen2 for
example. Docks are handled differently, they don’t have decorations and are not
assigned to a specific container. Instead, they are positioned at the bottom
or top of the screen (in the appropriate dock area containers). To get the
height which needs to be reserved for the window, the <code>_NET_WM_STRUT_PARTIAL</code>
property is used.</p></div>
<div class="paragraph"><p>Furthermore, the list of assignments (to other workspaces, which may be on
other screens) is checked. If the window matches one of the user’s criteria,
it may either be put in floating mode or moved to a different workspace. If the
target workspace is not visible, the window will not be mapped.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_what_happens_when_an_application_is_started">9. What happens when an application is started?</h2>
<div class="sectionbody">
<div class="paragraph"><p>i3 does not care about applications. All it notices is when new windows are
mapped (see <code>src/handlers.c</code>, <code>handle_map_request()</code>). The window is then
reparented (see section "Manage windows").</p></div>
<div class="paragraph"><p>After reparenting the window, <code>render_tree()</code> is called which renders the
internal layout table. The new window has been placed in the currently focused
container and therefore the new window and the old windows (if any) need to be
moved/resized so that the currently active layout (default/stacking/tabbed mode)
is rendered correctly. To move/resize windows, a window is &#8220;configured&#8221; in
X11-speak.</p></div>
<div class="paragraph"><p>Some applications, such as MPlayer obviously assume the window manager is
stupid and try to configure their windows by themselves. This generates an
event called configurerequest. i3 handles these events and tells the window the
size it had before the configurerequest (with the exception of not yet mapped
windows, which get configured like they want to, and floating windows, which
can reconfigure themselves).</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_net_wm_state">10. _NET_WM_STATE</h2>
<div class="sectionbody">
<div class="paragraph"><p>Only the _NET_WM_STATE_FULLSCREEN and _NET_WM_STATE_DEMANDS_ATTENTION atoms
are handled.</p></div>
<div class="paragraph"><p>The former calls &#8220;toggle_fullscreen()&#8221; for the specific client which just
configures the client to use the whole screen on which it currently is.
Also, it is set as fullscreen_client for the i3Screen.</p></div>
<div class="paragraph"><p>The latter is used to set, read and display urgency hints.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_wm_name">11. WM_NAME</h2>
<div class="sectionbody">
<div class="paragraph"><p>When the WM_NAME property of a window changes, its decoration (containing the
title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is
totally uncommon and cumbersome. Therefore, the _NET_WM_NAME atom will be used
if present.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_net_wm_name">12. _NET_WM_NAME</h2>
<div class="sectionbody">
<div class="paragraph"><p>Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME
is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it
to X. Using an appropriate font (ISO-10646), you can see most special
characters (every special character contained in your font).</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_size_hints">13. Size hints</h2>
<div class="sectionbody">
<div class="paragraph"><p>Size hints specify the minimum/maximum size for a given window as well as its
aspect ratio.  This is important for clients like mplayer, who only set the
aspect ratio and resize their window to be as small as possible (but only with
some video outputs, for example in Xv, while when using x11, mplayer does the
necessary centering for itself).</p></div>
<div class="paragraph"><p>So, when an aspect ratio was specified, i3 adjusts the height of the window
until the size maintains the correct aspect ratio. For the code to do this, see
src/layout.c, function resize_client().</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_rendering_src_layout_c_render_layout_and_render_container">14. Rendering (src/layout.c, render_layout() and render_container())</h2>
<div class="sectionbody">
<div class="paragraph"><p>Rendering in i3 version 4 is the step which assigns the correct sizes for
borders, decoration windows, child windows and the stacking order of all
windows. In a separate step (<code>x_push_changes()</code>), these changes are pushed to
X11.</p></div>
<div class="paragraph"><p>Keep in mind that all these properties (<code>rect</code>, <code>window_rect</code> and <code>deco_rect</code>)
are temporary, meaning they will be overwritten by calling <code>render_con</code>.
Persistent position/size information is kept in <code>geometry</code>.</p></div>
<div class="paragraph"><p>The entry point for every rendering operation (except for the case of moving
floating windows around) currently is <code>tree_render()</code> which will re-render
everything that’s necessary (for every output, only the currently displayed
workspace is rendered). This behavior is expected to change in the future,
since for a lot of updates, re-rendering everything is not actually necessary.
Focus was on getting it working correct, not getting it work very fast.</p></div>
<div class="paragraph"><p>What <code>tree_render()</code> actually does is calling <code>render_con()</code> on the root
container and then pushing the changes to X11. The following sections talk
about the different rendering steps, in the order of "top of the tree" (root
container) to the bottom.</p></div>
<div class="sect2">
<h3 id="_rendering_the_root_container">14.1. Rendering the root container</h3>
<div class="paragraph"><p>The i3 root container (<code>con-&gt;type == CT_ROOT</code>) represents the X11 root window.
It contains one child container for every output (like LVDS1, VGA1, …), which
is available on your computer.</p></div>
<div class="paragraph"><p>Rendering the root will first render all tiling windows and then all floating
windows. This is necessary because a floating window can be positioned in such
a way that it is visible on two different outputs. Therefore, by first
rendering all the tiling windows (of all outputs), we make sure that floating
windows can never be obscured by tiling windows.</p></div>
<div class="paragraph"><p>Essentially, though, this code path will just call <code>render_con()</code> for every
output and <code>x_raise_con(); render_con()</code> for every floating window.</p></div>
<div class="paragraph"><p>In the special case of having a "global fullscreen" window (fullscreen mode
spanning all outputs), a shortcut is taken and <code>x_raise_con(); render_con()</code> is
only called for the global fullscreen window.</p></div>
</div>
<div class="sect2">
<h3 id="_rendering_an_output">14.2. Rendering an output</h3>
<div class="paragraph"><p>Output containers (<code>con-&gt;layout == L_OUTPUT</code>) represent a hardware output like
LVDS1, VGA1, etc. An output container has three children (at the moment): One
content container (having workspaces as children) and the top/bottom dock area
containers.</p></div>
<div class="paragraph"><p>The rendering happens in the function <code>render_l_output()</code> in the following
steps:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Find the content container (<code>con-&gt;type == CT_CON</code>)
</p>
</li>
<li>
<p>
Get the currently visible workspace (<code>con_get_fullscreen_con(content,
   CF_OUTPUT)</code>).
</p>
</li>
<li>
<p>
If there is a fullscreened window on that workspace, directly render it and
   return, thus ignoring the dock areas.
</p>
</li>
<li>
<p>
Sum up the space used by all the dock windows (they have a variable height
   only).
</p>
</li>
<li>
<p>
Set the workspace rects (x/y/width/height) based on the position of the
   output (stored in <code>con-&gt;rect</code>) and the usable space
   (<code>con-&gt;rect.{width,height}</code> without the space used for dock windows).
</p>
</li>
<li>
<p>
Recursively raise and render the output’s child containers (meaning dock
   area containers and the content container).
</p>
</li>
</ol></div>
</div>
<div class="sect2">
<h3 id="_rendering_a_workspace_or_split_container">14.3. Rendering a workspace or split container</h3>
<div class="paragraph"><p>From here on, there really is no difference anymore. All containers are of
<code>con-&gt;type == CT_CON</code> (whether workspace or split container) and some of them
have a <code>con-&gt;window</code>, meaning they represent an actual window instead of a
split container.</p></div>
<div class="sect3">
<h4 id="_default_layout">14.3.1. Default layout</h4>
<div class="paragraph"><p>In default layout, containers are placed horizontally or vertically next to
each other (depending on the <code>con-&gt;orientation</code>). If a child is a leaf node (as
opposed to a split container) and has border style "normal", appropriate space
will be reserved for its window decoration.</p></div>
</div>
<div class="sect3">
<h4 id="_stacked_layout">14.3.2. Stacked layout</h4>
<div class="paragraph"><p>In stacked layout, only the focused window is actually shown (this is achieved
by calling <code>x_raise_con()</code> in reverse focus order at the end of <code>render_con()</code>).</p></div>
<div class="paragraph"><p>The available space for the focused window is the size of the container minus
the height of the window decoration for all windows inside this stacked
container.</p></div>
<div class="paragraph"><p>If border style is "1pixel" or "none", no window decoration height will be
reserved (or displayed later on), unless there is more than one window inside
the stacked container.</p></div>
</div>
<div class="sect3">
<h4 id="_tabbed_layout">14.3.3. Tabbed layout</h4>
<div class="paragraph"><p>Tabbed layout works precisely like stacked layout, but the window decoration
position/size is different: They are placed next to each other on a single line
(fixed height).</p></div>
</div>
<div class="sect3">
<h4 id="_dock_area_layout">14.3.4. Dock area layout</h4>
<div class="paragraph"><p>This is a special case. Users cannot choose the dock area layout, but it will be
set for the dock area containers. In the dockarea layout (at the moment!),
windows will be placed above each other.</p></div>
</div>
</div>
<div class="sect2">
<h3 id="_rendering_a_window">14.4. Rendering a window</h3>
<div class="paragraph"><p>A window’s size and position will be determined in the following way:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Subtract the border if border style is not "none" (but "normal" or "1pixel").
</p>
</li>
<li>
<p>
Subtract the X11 border, if the window has an X11 border &gt; 0.
</p>
</li>
<li>
<p>
Obey the aspect ratio of the window (think MPlayer).
</p>
</li>
<li>
<p>
Obey the height- and width-increments of the window (think terminal emulator
   which can only be resized in one-line or one-character steps).
</p>
</li>
</ol></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_pushing_updates_to_x11_drawing">15. Pushing updates to X11 / Drawing</h2>
<div class="sectionbody">
<div class="paragraph"><p>A big problem with i3 before version 4 was that we just sent requests to X11
anywhere in the source code. This was bad because nobody could understand the
entirety of our interaction with X11, it lead to subtle bugs and a lot of edge
cases which we had to consider all over again.</p></div>
<div class="paragraph"><p>Therefore, since version 4, we have a single file, <code>src/x.c</code>, which is
responsible for repeatedly transferring parts of our tree datastructure to X11.</p></div>
<div class="paragraph"><p><code>src/x.c</code> consists of multiple parts:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
The state pushing: <code>x_push_changes()</code>, which calls <code>x_push_node()</code>.
</p>
</li>
<li>
<p>
State modification functions: <code>x_con_init</code>, <code>x_reinit</code>,
   <code>x_reparent_child</code>, <code>x_move_win</code>, <code>x_con_kill</code>, <code>x_raise_con</code>, <code>x_set_name</code>
   and <code>x_set_warp_to</code>.
</p>
</li>
<li>
<p>
Expose event handling (drawing decorations): <code>x_deco_recurse()</code> and
   <code>x_draw_decoration()</code>.
</p>
</li>
</ol></div>
<div class="sect2">
<h3 id="_pushing_state_to_x11">15.1. Pushing state to X11</h3>
<div class="paragraph"><p>In general, the function <code>x_push_changes</code> should be called to push state
changes. Only when the scope of the state change is clearly defined (for
example only the title of a window) and its impact is known beforehand, one can
optimize this and call <code>x_push_node</code> on the appropriate con directly.</p></div>
<div class="paragraph"><p><code>x_push_changes</code> works in the following steps:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Clear the eventmask for all mapped windows. This leads to not getting
   useless ConfigureNotify or EnterNotify events which are caused by our
   requests. In general, we only want to handle user input.
</p>
</li>
<li>
<p>
Stack windows above each other, in reverse stack order (starting with the
   most obscured/bottom window). This is relevant for floating windows which
   can overlap each other, but also for tiling windows in stacked or tabbed
   containers. We also update the <code>_NET_CLIENT_LIST_STACKING</code> hint which is
   necessary for tab drag and drop in Chromium.
</p>
</li>
<li>
<p>
<code>x_push_node</code> will be called for the root container, recursively calling
   itself for the container’s children. This function actually pushes the
   state, see the next paragraph.
</p>
</li>
<li>
<p>
If the pointer needs to be warped to a different position (for example when
   changing focus to a different output), it will be warped now.
</p>
</li>
<li>
<p>
The eventmask is restored for all mapped windows.
</p>
</li>
<li>
<p>
Window decorations will be rendered by calling <code>x_deco_recurse</code> on the root
   container, which then recursively calls itself for the children.
</p>
</li>
<li>
<p>
If the input focus needs to be changed (because the user focused a different
   window), it will be updated now.
</p>
</li>
<li>
<p>
<code>x_push_node_unmaps</code> will be called for the root container. This function
   only pushes UnmapWindow requests. Separating the state pushing is necessary
   to handle fullscreen windows (and workspace switches) in a smooth fashion:
   The newly visible windows should be visible before the old windows are
   unmapped.
</p>
</li>
</ol></div>
<div class="paragraph"><p><code>x_push_node</code> works in the following steps:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Update the window’s <code>WM_NAME</code>, if changed (the <code>WM_NAME</code> is set on i3
   containers mainly for debugging purposes).
</p>
</li>
<li>
<p>
Reparents a child window into the i3 container if the container was created
   for a specific managed window.
</p>
</li>
<li>
<p>
If the size/position of the i3 container changed (due to opening a new
   window or switching layouts for example), the window will be reconfigured.
   Also, the pixmap which is used to draw the window decoration/border on is
   reconfigured (pixmaps are size-dependent).
</p>
</li>
<li>
<p>
Size/position for the child window is adjusted.
</p>
</li>
<li>
<p>
The i3 container is mapped if it should be visible and was not yet mapped.
   When mapping, <code>WM_STATE</code> is set to <code>WM_STATE_NORMAL</code>. Also, the eventmask of
   the child window is updated and the i3 container’s contents are copied from
   the pixmap.
</p>
</li>
<li>
<p>
<code>x_push_node</code> is called recursively for all children of the current
   container.
</p>
</li>
</ol></div>
<div class="paragraph"><p><code>x_push_node_unmaps</code> handles the remaining case of an i3 container being
unmapped if it should not be visible anymore. <code>WM_STATE</code> will be set to
<code>WM_STATE_WITHDRAWN</code>.</p></div>
</div>
<div class="sect2">
<h3 id="_drawing_window_decorations_borders_backgrounds">15.2. Drawing window decorations/borders/backgrounds</h3>
<div class="paragraph"><p><code>x_draw_decoration</code> draws window decorations. It is run for every leaf
container (representing an actual X11 window) and for every non-leaf container
which is in a stacked/tabbed container (because stacked/tabbed containers
display a window decoration for split containers, which consists of a representation
of the child container&#8217;s names.</p></div>
<div class="paragraph"><p>Then, parameters are collected to be able to determine whether this decoration
drawing is actually necessary or was already done. This saves a substantial
number of redraws (depending on your workload, but far over 50%).</p></div>
<div class="paragraph"><p>Assuming that we need to draw this decoration, we start by filling the empty
space around the child window (think of MPlayer with a specific aspect ratio)
in the user-configured client background color.</p></div>
<div class="paragraph"><p>Afterwards, we draw the appropriate border (in case of border styles "normal"
and "1pixel") and the top bar (in case of border style "normal").</p></div>
<div class="paragraph"><p>The last step is drawing the window title on the top bar.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_user_commands_parser_specs_commands_spec">16. User commands (parser-specs/commands.spec)</h2>
<div class="sectionbody">
<div class="paragraph"><p>In the configuration file and when using i3 interactively (with <code>i3-msg</code>, for
example), you use commands to make i3 do things, like focus a different window,
set a window to fullscreen, and so on. An example command is <code>floating enable</code>,
which enables floating mode for the currently focused window. See the
appropriate section in the <a href="userguide.html">User’s Guide</a> for a reference of
all commands.</p></div>
<div class="paragraph"><p>In earlier versions of i3, interpreting these commands was done using lex and
yacc, but experience has shown that lex and yacc are not well suited for our
command language. Therefore, starting from version 4.2, we use a custom parser
for user commands and the configuration file.
The input specification for this parser can be found in the file
<code>parser-specs/*.spec</code>. Should you happen to use Vim as an editor, use
:source parser-specs/highlighting.vim to get syntax highlighting for this file
(highlighting files for other editors are welcome).</p></div>
<div class="listingblock">
<div class="title">Excerpt from commands.spec</div>
<div class="content">
<pre><code>state INITIAL:
  '[' -&gt; call cmd_criteria_init(); CRITERIA
  'move' -&gt; MOVE
  'exec' -&gt; EXEC
  'workspace' -&gt; WORKSPACE
  'exit' -&gt; call cmd_exit()
  'restart' -&gt; call cmd_restart()
  'reload' -&gt; call cmd_reload()</code></pre>
</div></div>
<div class="paragraph"><p>The input specification is written in an extremely simple format. The
specification is then converted into C code by the Perl script
generate-commands-parser.pl (the output file names begin with GENERATED and the
files are stored in the <code>include</code> directory). The parser implementation
<code>src/commands_parser.c</code> includes the generated C code at compile-time.</p></div>
<div class="paragraph"><p>The above excerpt from commands.spec illustrates nearly all features of our
specification format: You describe different states and what can happen within
each state. State names are all-caps; the state in the above excerpt is called
INITIAL. A list of tokens and their actions (separated by an ASCII arrow)
follows. In the excerpt, all tokens are literals, that is, simple text strings
which will be compared with the input. An action is either the name of a state
in which the parser will transition into, or the keyword <em>call</em>, followed by
the name of a function (and optionally a state).</p></div>
<div class="sect2">
<h3 id="_example_the_workspace_state">16.1. Example: The WORKSPACE state</h3>
<div class="paragraph"><p>Let’s have a look at the WORKSPACE state, which is a good example of all
features. This is its definition:</p></div>
<div class="listingblock">
<div class="title">WORKSPACE state (commands.spec)</div>
<div class="content">
<pre><code># workspace next|prev|next_on_output|prev_on_output
# workspace back_and_forth
# workspace &lt;name&gt;
# workspace number &lt;number&gt;
state WORKSPACE:
  direction = 'next_on_output', 'prev_on_output', 'next', 'prev'
      -&gt; call cmd_workspace($direction)
  'back_and_forth'
      -&gt; call cmd_workspace_back_and_forth()
  'number'
      -&gt; WORKSPACE_NUMBER
  workspace = string
      -&gt; call cmd_workspace_name($workspace)</code></pre>
</div></div>
<div class="paragraph"><p>As you can see from the commands, there are multiple different valid variants
of the workspace command:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
workspace &lt;direction&gt;
</dt>
<dd>
<p>
        The word <em>workspace</em> can be followed by any of the tokens <em>next</em>,
        <em>prev</em>, <em>next_on_output</em> or <em>prev_on_output</em>. This command will
        switch to the next or previous workspace (optionally on the same
        output).<br />
        There is one function called <code>cmd_workspace</code>, which is defined
        in <code>src/commands.c</code>. It will handle this kind of command. To know which
        direction was specified, the direction token is stored on the stack
        with the name "direction", which is what the "direction = " means in
        the beginning.<br />
</p>
</dd>
</dl></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">Note that you can specify multiple literals in the same line. This has
        exactly the same effect as if you specified <code>direction =
        'next_on_output' -&gt; call cmd_workspace($direction)</code> and so forth.<br /></td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">Also note that the order of literals is important here: If <em>next</em> were
        ordered before <em>next_on_output</em>, then <em>next_on_output</em> would never
        match.</td>
</tr></table>
</div>
<div class="dlist"><dl>
<dt class="hdlist1">
workspace back_and_forth
</dt>
<dd>
<p>
        This is a very simple case: When the literal <em>back_and_forth</em> is found
        in the input, the function <code>cmd_workspace_back_and_forth</code> will be
        called without parameters and the parser will return to the INITIAL
        state (since no other state was specified).
</p>
</dd>
<dt class="hdlist1">
workspace &lt;name&gt;
</dt>
<dd>
<p>
        In this case, the workspace command is followed by an arbitrary string,
        possibly in quotes, for example "workspace 3" or "workspace bleh".<br />
        This is the first time that the token is actually not a literal (not in
        single quotes), but just called string. Other possible tokens are word
        (the same as string, but stops matching at a whitespace) and end
        (matches the end of the input).
</p>
</dd>
<dt class="hdlist1">
workspace number &lt;number&gt;
</dt>
<dd>
<p>
        The workspace command has to be followed by the keyword <code>number</code>. It
        then transitions into the state <code>WORKSPACE_NUMBER</code>, where the actual
        parameter will be read.
</p>
</dd>
</dl></div>
</div>
<div class="sect2">
<h3 id="_introducing_a_new_command">16.2. Introducing a new command</h3>
<div class="paragraph"><p>The following steps have to be taken in order to properly introduce a new
command (or possibly extend an existing command):</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Define a function beginning with <code>cmd_</code> in the file <code>src/commands.c</code>. Copy
   the prototype of an existing function.
</p>
</li>
<li>
<p>
After adding a comment on what the function does, copy the comment and
   function definition to <code>include/commands.h</code>. Make the comment in the header
   file use double asterisks to make doxygen pick it up.
</p>
</li>
<li>
<p>
Write a test case (or extend an existing test case) for your feature, see
   <a href="testsuite.html">i3 testsuite</a>. For now, it is sufficient to simply call
   your command in all the various possible ways.
</p>
</li>
<li>
<p>
Extend the parser specification in <code>parser-specs/commands.spec</code>. Run the
   testsuite and see if your new function gets called with the appropriate
   arguments for the appropriate input.
</p>
</li>
<li>
<p>
Actually implement the feature.
</p>
</li>
<li>
<p>
Document the feature in the <a href="userguide.html">User’s Guide</a>.
</p>
</li>
</ol></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_moving_containers">17. Moving containers</h2>
<div class="sectionbody">
<div class="paragraph"><p>The movement code is pretty delicate. You need to consider all cases before
making any changes or before being able to fully understand how it works.</p></div>
<div class="sect2">
<h3 id="_case_1_moving_inside_the_same_container">17.1. Case 1: Moving inside the same container</h3>
<div class="paragraph"><p>The reference layout for this case is a single workspace in horizontal
orientation with two containers on it. Focus is on the left container (1).</p></div>
<div class="tableblock">
<table rules="all"
width="15%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="center" valign="top"><p class="table">1</p></td>
<td align="center" valign="top"><p class="table">2</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>When moving the left window to the right (command <code>move right</code>), tree_move will
look for a container with horizontal orientation and finds the parent of the
left container, that is, the workspace. Afterwards, it runs the code branch
commented with "the easy case": it calls TAILQ_NEXT to get the container right
of the current one and swaps both containers.</p></div>
</div>
<div class="sect2">
<h3 id="_case_2_move_a_container_into_a_split_container">17.2. Case 2: Move a container into a split container</h3>
<div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two
containers. The right container is a v-split with two containers. Focus is on
the left container (1).</p></div>
<div class="tableblock">
<table rules="all"
width="15%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td rowspan="2" align="center" valign="middle"><p class="table">1</p></td>
<td align="center" valign="top"><p class="table">2</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">3</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>When moving to the right (command <code>move right</code>), i3 will work like in case 1
("the easy case"). However, as the right container is not a leaf container, but
a v-split, the left container (1) will be inserted at the right position (below
2, assuming that 2 is focused inside the v-split) by calling <code>insert_con_into</code>.</p></div>
<div class="paragraph"><p><code>insert_con_into</code> detaches the container from its parent and inserts it
before/after the given target container. Afterwards, the on_remove_child
callback is called on the old parent container which will then be closed, if
empty.</p></div>
<div class="paragraph"><p>Afterwards, <code>con_focus</code> will be called to fix the focus stack and the tree will
be flattened.</p></div>
</div>
<div class="sect2">
<h3 id="_case_3_moving_to_non_existent_top_bottom">17.3. Case 3: Moving to non-existent top/bottom</h3>
<div class="paragraph"><p>Like in case 1, the reference layout for this case is a single workspace in
horizontal orientation with two containers on it. Focus is on the left
container:</p></div>
<div class="tableblock">
<table rules="all"
width="15%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="center" valign="top"><p class="table">1</p></td>
<td align="center" valign="top"><p class="table">2</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>This time however, the command is <code>move up</code> or <code>move down</code>. tree_move will look
for a container with vertical orientation. As it will not find any,
<code>same_orientation</code> is NULL and therefore i3 will perform a forced orientation
change on the workspace by creating a new h-split container, moving the
workspace contents into it and then changing the workspace orientation to
vertical. Now it will again search for parent containers with vertical
orientation and it will find the workspace.</p></div>
<div class="paragraph"><p>This time, the easy case code path will not be run as we are not moving inside
the same container. Instead, <code>insert_con_into</code> will be called with the focused
container and the container above/below the current one (on the level of
<code>same_orientation</code>).</p></div>
<div class="paragraph"><p>Now, <code>con_focus</code> will be called to fix the focus stack and the tree will be
flattened.</p></div>
</div>
<div class="sect2">
<h3 id="_case_4_moving_to_existent_top_bottom">17.4. Case 4: Moving to existent top/bottom</h3>
<div class="paragraph"><p>The reference layout for this case is a vertical workspace with two containers.
The bottom one is a h-split containing two containers (1 and 2). Focus is on
the bottom left container (1).</p></div>
<div class="tableblock">
<table rules="all"
width="15%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td colspan="2" align="center" valign="top"><p class="table">3</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">1</p></td>
<td align="center" valign="top"><p class="table">2</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>This case is very much like case 3, only this time the forced workspace
orientation change does not need to be performed because the workspace already
is in vertical orientation.</p></div>
</div>
<div class="sect2">
<h3 id="_case_5_moving_in_one_child_h_split">17.5. Case 5: Moving in one-child h-split</h3>
<div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two
containers having a v-split on the left side with a one-child h-split on the
bottom. Focus is on the bottom left container (2(h)):</p></div>
<div class="tableblock">
<table rules="all"
width="15%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="center" valign="top"><p class="table">1</p></td>
<td rowspan="2" align="center" valign="middle"><p class="table">3</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">2(h)</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>In this case, <code>same_orientation</code> will be set to the h-split container around
the focused container. However, when trying the easy case, the next/previous
container <code>swap</code> will be NULL. Therefore, i3 will search again for a
<code>same_orientation</code> container, this time starting from the parent of the h-split
container.</p></div>
<div class="paragraph"><p>After determining a new <code>same_orientation</code> container (if it is NULL, the
orientation will be force-changed), this case is equivalent to case 2 or case
4.</p></div>
</div>
<div class="sect2">
<h3 id="_case_6_floating_containers">17.6. Case 6: Floating containers</h3>
<div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two
containers plus one floating h-split container. Focus is on the floating
container.</p></div>
<div class="paragraph"><p>TODO: nice illustration. table not possible?</p></div>
<div class="paragraph"><p>When moving up/down, the container needs to leave the floating container and it
needs to be placed on the workspace (at workspace level). This is accomplished
by calling the function <code>attach_to_workspace</code>.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_click_handling">18. Click handling</h2>
<div class="sectionbody">
<div class="paragraph"><p>Without much ado, here is the list of cases which need to be considered:</p></div>
<div class="ulist"><ul>
<li>
<p>
click to focus (tiling + floating) and raise (floating)
</p>
</li>
<li>
<p>
click to focus/raise when in stacked/tabbed mode
</p>
</li>
<li>
<p>
floating_modifier + left mouse button to drag a floating con
</p>
</li>
<li>
<p>
floating_modifier + right mouse button to resize a floating con
</p>
</li>
<li>
<p>
click on decoration in a floating con to either initiate a resize (if there
  is more than one child in the floating con) or to drag the
  floating con (if it’s the one at the top).
</p>
</li>
<li>
<p>
click on border in a floating con to resize the floating con
</p>
</li>
<li>
<p>
floating_modifier + right mouse button to resize a tiling con
</p>
</li>
<li>
<p>
click on border/decoration to resize a tiling con
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_gotchas">19. Gotchas</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
<p>
Forgetting to call <code>xcb_flush(conn);</code> after sending a request. This usually
  leads to code which looks like it works fine but which does not work under
  certain conditions.
</p>
</li>
<li>
<p>
Forgetting to call <code>floating_fix_coordinates(con, old_rect, new_rect)</code> after
  moving workspaces across outputs. Coordinates for floating containers are
  not relative to workspace boundaries, so you must correct their coordinates
  or those containers will show up in the wrong workspace or not at all.
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_using_git_sending_patches">20. Using git / sending patches</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_introduction">20.1. Introduction</h3>
<div class="paragraph"><p>For a short introduction into using git, see
<a href="http://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy">http://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy</a>
or, for more documentation, see <a href="http://git-scm.com/documentation">http://git-scm.com/documentation</a></p></div>
<div class="paragraph"><p>Please talk to us before working on new features to see whether they will be
accepted. A good way for this is to open an issue and asking for opinions on it.
Even for accepted features, this can be a good way to refine an idea upfront. However,
we don&#8217;t want to see certain features in i3, e.g., switching window focus in an
Alt+Tab like way.</p></div>
<div class="paragraph"><p>When working on bugfixes, please make sure you mention that you are working on
it in the corresponding bug report at <a href="https://github.com/i3/i3/issues">https://github.com/i3/i3/issues</a>. In case
there is no bug report yet, please create one.</p></div>
<div class="paragraph"><p>After you are done, please submit your work for review as a pull request at
<a href="https://github.com/i3/i3">https://github.com/i3/i3</a>.</p></div>
<div class="paragraph"><p>Do not send emails to the mailing list or any author directly, and don’t submit
them in the bugtracker, since all reviews should be done in public at
<a href="https://github.com/i3/i3">https://github.com/i3/i3</a>. In order to make your review go as fast as possible, you
could have a look at previous reviews and see what the common mistakes are.</p></div>
</div>
<div class="sect2">
<h3 id="_which_branch_to_use">20.2. Which branch to use?</h3>
<div class="paragraph"><p>Work on i3 generally happens in two branches: “master” and “next” (the latter
being the default branch, the one that people get when they check out the git
repository).</p></div>
<div class="paragraph"><p>The contents of “master” are always stable. That is, it contains the source code
of the latest release, plus any bugfixes that were applied since that release.</p></div>
<div class="paragraph"><p>New features are only found in the “next” branch. Therefore, if you are working
on a new feature, use the “next” branch. If you are working on a bugfix, use the
“next” branch, too, but make sure your code also works on “master”.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_thought_experiments">21. Thought experiments</h2>
<div class="sectionbody">
<div class="paragraph"><p>In this section, we collect thought experiments, so that we don’t forget our
thoughts about specific topics. They are not necessary to get into hacking i3,
but if you are interested in one of the topics they cover, you should read them
before asking us why things are the way they are or why we don’t implement
things.</p></div>
<div class="sect2">
<h3 id="_using_cgroups_per_workspace">21.1. Using cgroups per workspace</h3>
<div class="paragraph"><p>cgroups (control groups) are a linux-only feature which provides the ability to
group multiple processes. For each group, you can individually set resource
limits, like allowed memory usage. Furthermore, and more importantly for our
purposes, they serve as a namespace, a label which you can attach to processes
and their children.</p></div>
<div class="paragraph"><p>One interesting use for cgroups is having one cgroup per workspace (or
container, doesn’t really matter). That way, you could set different priorities
and have a workspace for important stuff (say, writing a LaTeX document or
programming) and a workspace for unimportant background stuff (say,
JDownloader). Both tasks can obviously consume a lot of I/O resources, but in
this example it doesn’t really matter if JDownloader unpacks the download a
minute earlier or not. However, your compiler should work as fast as possible.
Having one cgroup per workspace, you would assign more resources to the
programming workspace.</p></div>
<div class="paragraph"><p>Another interesting feature is that an inherent problem of the workspace
concept could be solved by using cgroups: When starting an application on
workspace 1, then switching to workspace 2, you will get the application’s
window(s) on workspace 2 instead of the one you started it on. This is because
the window manager does not have any mapping between the process it starts (or
gets started in any way) and the window(s) which appear.</p></div>
<div class="paragraph"><p>Imagine for example using dmenu: The user starts dmenu by pressing Mod+d, dmenu
gets started with PID 3390. The user then decides to launch Firefox, which
takes a long time. So they enter firefox into dmenu and press enter. Firefox
gets started with PID 4001. When it finally finishes loading, it creates an X11
window and uses MapWindow to make it visible. This is the first time i3
actually gets in touch with Firefox. It decides to map the window, but it has
no way of knowing that this window (even though it has the _NET_WM_PID property
set to 4001) belongs to the dmenu the user started before.</p></div>
<div class="paragraph"><p>How do cgroups help with this? Well, when pressing Mod+d to launch dmenu, i3
would create a new cgroup, let’s call it i3-3390-1. It launches dmenu in that
cgroup, which gets PID 3390. As before, the user enters firefox and Firefox
gets launched with PID 4001. This time, though, the Firefox process with PID
4001 is <strong>also</strong> member of the cgroup i3-3390-1 (because fork()ing in a cgroup
retains the cgroup property). Therefore, when mapping the window, i3 can look
up in which cgroup the process is and can establish a mapping between the
workspace and the window.</p></div>
<div class="paragraph"><p>There are multiple problems with this approach:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Every application has to properly set <code>_NET_WM_PID</code>. This is acceptable and
  patches can be written for the few applications which don’t set the hint yet.
</p>
</li>
<li>
<p>
It does only work on Linux, since cgroups are a Linux-only feature. Again,
  this is acceptable.
</p>
</li>
<li>
<p>
The main problem is that some applications create X11 windows completely
  independent of UNIX processes. An example for this is Chromium (or
  gnome-terminal), which, when being started a second time, communicates with
  the first process and lets the first process open a new window. Therefore, if
  you have a Chromium window on workspace 2 and you are currently working on
  workspace 3, starting <code>chromium</code> does not lead to the desired result (the
  window will open on workspace 2).
</p>
</li>
</ol></div>
<div class="paragraph"><p>Therefore, my conclusion is that the only proper way of fixing the "window gets
opened on the wrong workspace" problem is in the application itself. Most
modern applications support freedesktop startup-notifications  which can be
used for this.</p></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>