"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
<head>\r
-<link rel="icon" type="image/png" href="/favicon.png">\r
+<link rel="icon" type="image/x-icon" href="/favicon.ico">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.4" />\r
+<meta name="generator" content="AsciiDoc 8.6.10" />\r
<title>i3: Hacking i3: How To</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<script type="text/javascript">\r
/*<![CDATA[*/\r
-window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}\r
+document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes(); asciidoc.toc(2);}, false);\r
/*]]>*/\r
</script>\r
<script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\r
<ul id="nav">\r
<li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>\r
<li><a href="/screenshots">Screens</a></li>\r
+ <li><a href="https://www.reddit.com/r/i3wm/">FAQ</a></li>\r
<li><a href="/contact">Contact</a></li>\r
- <li><a href="http://bugs.i3wm.org/">Bugs</a></li>\r
+ <li><a href="https://github.com/i3/i3/issues">Bugs</a></li>\r
</ul>\r
<br style="clear: both">\r
<div id="content">\r
<div id="header">\r
<h1>Hacking i3: How To</h1>\r
<span id="author">Michael Stapelberg</span><br />\r
-<span id="email"><tt><<a href="mailto:michael+i3@stapelberg.de">michael+i3@stapelberg.de</a>></tt></span><br />\r
-<span id="revdate">July 2011</span>\r
-<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>
+<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
+<span id="revdate">February 2013</span>\r
+<div id="toc">\r
+ <div id="toctitle">Table of Contents</div>\r
+ <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>\r
</div>\r
</div>\r
<div id="preamble">\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_window_managers">1. Window Managers</h2>\r
+<h2 id="_building_i3">1. Building i3</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>You can build i3 like you build any other software package which uses autotools.\r
+Here’s a memory refresher:</p></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>$ autoreconf -fi\r
+$ mkdir -p build && cd build\r
+$ ../configure\r
+$ make -j8</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>(The autoreconf -fi step is unnecessary if you are building from a release tarball,\r
+ but shouldn’t hurt either.)</p></div>\r
+<div class="sect2">\r
+<h3 id="_build_system_features">1.1. Build system features</h3>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate\r
+ directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building\r
+ in a separate directory is common practice anyway. In case this causes any\r
+ trouble when packaging i3 for your distribution, please open an issue.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+“make check” runs the i3 testsuite. See docs/testsuite for details.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+“make distcheck” (runs testsuite on “make dist” result, tiny bit quicker\r
+ feedback cycle than waiting for the travis build to catch the issue).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+“make uninstall” (occasionally requested by users who compile from source)\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+“make” will build manpages/docs by default if the tools are installed.\r
+ Conversely, manpages/docs are not tried to be built for users who don’t want\r
+ to install all these dependencies to get started hacking on i3.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+non-release builds will enable address sanitizer by default. Use the\r
+ --disable-sanitizers configure option to turn off all sanitizers, and see\r
+ --help for available sanitizers.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Support for pre-compiled headers (PCH) has been dropped for now in the\r
+ interest of simplicity. If you need support for PCH, please open an issue.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Coverage reports are now generated using “make check-code-coverage”, which\r
+ requires specifying --enable-code-coverage when calling configure.\r
+</p>\r
+</li>\r
+</ul></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_using_git_sending_patches">2. Using git / sending patches</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>For a short introduction into using git, see\r
+<a href="https://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy">https://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy</a>\r
+or, for more documentation, see <a href="https://git-scm.com/documentation">https://git-scm.com/documentation</a></p></div>\r
+<div class="paragraph"><p>Please talk to us before working on new features to see whether they will be\r
+accepted. A good way for this is to open an issue and asking for opinions on it.\r
+Even for accepted features, this can be a good way to refine an idea upfront. However,\r
+we don’t want to see certain features in i3, e.g., switching window focus in an\r
+Alt+Tab like way.</p></div>\r
+<div class="paragraph"><p>When working on bugfixes, please make sure you mention that you are working on\r
+it in the corresponding bug report at <a href="https://github.com/i3/i3/issues">https://github.com/i3/i3/issues</a>. In case\r
+there is no bug report yet, please create one.</p></div>\r
+<div class="paragraph"><p>After you are done, please submit your work for review as a pull request at\r
+<a href="https://github.com/i3/i3">https://github.com/i3/i3</a>.</p></div>\r
+<div class="paragraph"><p>Do not send emails to the mailing list or any author directly, and don’t submit\r
+them in the bugtracker, since all reviews should be done in public at\r
+<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\r
+could have a look at previous reviews and see what the common mistakes are.</p></div>\r
+<div class="sect2">\r
+<h3 id="_which_branch_to_use">2.1. Which branch to use?</h3>\r
+<div class="paragraph"><p>Work on i3 generally happens in two branches: “master” and “next” (the latter\r
+being the default branch, the one that people get when they check out the git\r
+repository).</p></div>\r
+<div class="paragraph"><p>The contents of “master” are always stable. That is, it contains the source code\r
+of the latest release, plus any bugfixes that were applied since that release.</p></div>\r
+<div class="paragraph"><p>New features are only found in the “next” branch. Therefore, if you are working\r
+on a new feature, use the “next” branch. If you are working on a bugfix, use the\r
+“next” branch, too, but make sure your code also works on “master”.</p></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_window_managers">3. Window Managers</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>A window manager is not necessarily needed to run X, but it is usually used in\r
combination with X to facilitate some things. The window manager’s job is to\r
</li>\r
<li>\r
<p>\r
-Handle the client’s <tt>_WM_STATE</tt> property, but only the <tt>_WM_STATE_FULLSCREEN</tt>\r
+Handle the client’s <tt>_WM_STATE</tt> property, but only <tt>_WM_STATE_FULLSCREEN</tt> and\r
+ <tt>_NET_WM_STATE_DEMANDS_ATTENTION</tt>\r
</p>\r
</li>\r
<li>\r
<div class="paragraph"><p>In the following chapters, each of these tasks and their implementation details\r
will be discussed.</p></div>\r
<div class="sect2">\r
-<h3 id="_tiling_window_managers">1.1. Tiling window managers</h3>\r
+<h3 id="_tiling_window_managers">3.1. Tiling window managers</h3>\r
<div class="paragraph"><p>Traditionally, there are two approaches to managing windows: The most common\r
one nowadays is floating, which means the user can freely move/resize the\r
windows. The other approach is called tiling, which means that your window\r
all, most users sooner or later tend to lay out their windows in a way which\r
corresponds to tiling or stacking mode in i3. Therefore, why not let i3 do this\r
for you? Certainly, it’s faster than you could ever do it.</p></div>\r
-<div class="paragraph"><p>The problem with most tiling window managers is that they are too unflexible.\r
+<div class="paragraph"><p>The problem with most tiling window managers is that they are too inflexible.\r
In my opinion, a window manager is just another tool, and similar to vim which\r
can edit all kinds of text files (like source code, HTML, …) and is not limited\r
to a specific file type, a window manager should not limit itself to a certain\r
the layout you need at the moment.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_the_layout_table">1.2. The layout table</h3>\r
-<div class="sidebarblock">\r
-<div class="content">\r
-<div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on\r
-time, but we will update this soon. Please talk to us on IRC if you need to\r
-know stuff <strong>NOW</strong> :).</p></div>\r
-</div></div>\r
+<h3 id="_the_layout_tree">3.2. The layout tree</h3>\r
+<div class="paragraph"><p>The data structure which i3 uses to keep track of your windows is a tree. Every\r
+node in the tree is a container (type <tt>Con</tt>). Some containers represent actual\r
+windows (every container with a <tt>window != NULL</tt>), some represent split\r
+containers and a few have special purposes: they represent workspaces, outputs\r
+(like VGA1, LVDS1, …) or the X11 root window.</p></div>\r
+<div class="paragraph"><p>So, when you open a terminal and immediately open another one, they reside in\r
+the same split container, which uses the default layout. In case of an empty\r
+workspace, the split container we are talking about is the workspace.</p></div>\r
+<div class="paragraph"><p>To get an impression of how different layouts are represented, just play around\r
+and look at the data structures — they are exposed as a JSON hash. See\r
+<a href="https://i3wm.org/docs/ipc.html#_tree_reply">https://i3wm.org/docs/ipc.html#_tree_reply</a> for documentation on that and an\r
+example.</p></div>\r
</div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_files">2. Files</h2>\r
+<h2 id="_files">4. Files</h2>\r
<div class="sectionbody">\r
<div class="dlist"><dl>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
-src/cfgparse.l\r
-</dt>\r
-<dd>\r
-<p>\r
-Contains the lexer for i3’s configuration file, written for <tt>flex(1)</tt>.\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-src/cfgparse.y\r
+src/config_parser.c\r
</dt>\r
<dd>\r
<p>\r
-Contains the parser for i3’s configuration file, written for <tt>bison(1)</tt>.\r
+Contains a custom configuration parser. See src/command_parser.c for rationale\r
+ on why we use a custom parser.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
-src/cmdparse.l\r
-</dt>\r
-<dd>\r
-<p>\r
-Contains the lexer for i3 commands, written for <tt>flex(1)</tt>.\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-src/cmdparse.y\r
+src/command_parser.c\r
</dt>\r
<dd>\r
<p>\r
-Contains the parser for i3 commands, written for <tt>bison(1)</tt>.\r
+Contains a hand-written parser to parse commands (commands are what\r
+you bind on keys and what you can send to i3 using the IPC interface, like\r
+<em>move left</em> or <em>workspace 4</em>).\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
<dd>\r
<p>\r
Contains all functions handling the configuration file (calling the parser\r
-(src/cfgparse.y) with the correct path, switching key bindings mode).\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-src/debug.c\r
-</dt>\r
-<dd>\r
-<p>\r
-Contains debugging functions to print unhandled X events.\r
+src/config_parser.c) with the correct path, switching key bindings mode).\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</dt>\r
<dd>\r
<p>\r
-iFunctions to get/set certain EWMH properties easily.\r
+Functions to get/set certain EWMH properties easily.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</dt>\r
<dd>\r
<p>\r
-Handles the setting of loglevels, contains the logging functions.\r
+Contains the logging functions.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+src/restore_layout.c\r
+</dt>\r
+<dd>\r
+<p>\r
+Everything for restored containers that is not pure state parsing (which can be\r
+found in load_layout.c).\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
src/sighandler.c\r
</dt>\r
<dd>\r
</dt>\r
<dd>\r
<p>\r
-Contains useful functions which are not really dependant on anything.\r
+Contains useful functions which are not really dependent on anything.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_data_structures">3. Data structures</h2>\r
+<h2 id="_data_structures">5. Data structures</h2>\r
<div class="sectionbody">\r
-<div class="sidebarblock">\r
-<div class="content">\r
-<div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on\r
-time, but we will update this soon. Please talk to us on IRC if you need to\r
-know stuff <strong>NOW</strong> :).</p></div>\r
-</div></div>\r
+<div class="paragraph"><p>See include/data.h for documented data structures. The most important ones are\r
+explained right here.</p></div>\r
<div class="paragraph"><p>So, the hierarchy is:</p></div>\r
<div class="olist arabic"><ol class="arabic">\r
<li>\r
</li>\r
<li>\r
<p>\r
-<strong>Virtual screens</strong> (Screen 0 in this example)\r
+<strong>Output container</strong> (LVDS1 in this example)\r
</p>\r
</li>\r
<li>\r
</ol></div>\r
<div class="paragraph"><p>The data type is <tt>Con</tt>, in all cases.</p></div>\r
<div class="sect2">\r
-<h3 id="_virtual_screens">3.1. Virtual screens</h3>\r
-<div class="paragraph"><p>A virtual screen (type <tt>i3Screen</tt>) is generated from the connected outputs\r
-obtained through RandR. The difference to the raw RandR outputs as seen\r
-when using <tt>xrandr(1)</tt> is that it falls back to the lowest common resolution of\r
-the actual enabled outputs.</p></div>\r
+<h3 id="_x11_root_window">5.1. X11 root window</h3>\r
+<div class="paragraph"><p>The X11 root window is a single window per X11 display (a display is identified\r
+by <tt>:0</tt> or <tt>:1</tt> etc.). The root window is what you draw your background image\r
+on. It spans all the available outputs, e.g. <tt>VGA1</tt> is a specific part of the\r
+root window and <tt>LVDS1</tt> is a specific part of the root window.</p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_output_container">5.2. Output container</h3>\r
+<div class="paragraph"><p>Every active output obtained through RandR is represented by one output\r
+container. Outputs are considered active when a mode is configured (meaning\r
+something is actually displayed on the output) and the output is not a clone.</p></div>\r
<div class="paragraph"><p>For example, if your notebook has a screen resolution of 1280x800 px and you\r
connect a video projector with a resolution of 1024x768 px, set it up in clone\r
-mode (<tt>xrandr --output VGA1 --mode 1024x768 --same-as LVDS1</tt>), i3 will have\r
-one virtual screen.</p></div>\r
+mode (<tt>xrandr --output VGA1 --mode 1024x768 --same-as LVDS1</tt>), i3 will\r
+reduce the resolution to the lowest common resolution and disable one of the\r
+cloned outputs afterwards.</p></div>\r
<div class="paragraph"><p>However, if you configure it using <tt>xrandr --output VGA1 --mode 1024x768\r
---right-of LVDS1</tt>, i3 will generate two virtual screens. For each virtual\r
-screen, a new workspace will be assigned. New workspaces are created on the\r
-screen you are currently on.</p></div>\r
+--right-of LVDS1</tt>, i3 will set both outputs active. For each output, a new\r
+workspace will be assigned. New workspaces are created on the output you are\r
+currently on.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_workspace">3.2. Workspace</h3>\r
+<h3 id="_content_container">5.3. Content container</h3>\r
+<div class="paragraph"><p>Each output has multiple children. Two of them are dock containers which hold\r
+dock clients. The other one is the content container, which holds the actual\r
+content (workspaces) of this output.</p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_workspace">5.4. Workspace</h3>\r
<div class="paragraph"><p>A workspace is identified by its name. Basically, you could think of\r
workspaces as different desks in your office, if you like the desktop\r
-methaphor. They just contain different sets of windows and are completely\r
+metaphor. They just contain different sets of windows and are completely\r
separate of each other. Other window managers also call this “Virtual\r
desktops”.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_the_layout_table_2">3.3. The layout table</h3>\r
-<div class="sidebarblock">\r
-<div class="content">\r
-<div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on\r
-time, but we will update this soon. Please talk to us on IRC if you need to\r
-know stuff <strong>NOW</strong> :).</p></div>\r
-</div></div>\r
-</div>\r
-<div class="sect2">\r
-<h3 id="_container">3.4. Container</h3>\r
-<div class="sidebarblock">\r
-<div class="content">\r
-<div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on\r
-time, but we will update this soon. Please talk to us on IRC if you need to\r
-know stuff <strong>NOW</strong> :).</p></div>\r
-</div></div>\r
+<h3 id="_split_container">5.5. Split container</h3>\r
+<div class="paragraph"><p>A split container is a container which holds an arbitrary amount of split\r
+containers or X11 window containers. It has an orientation (horizontal or\r
+vertical) and a layout.</p></div>\r
+<div class="paragraph"><p>Split containers (and X11 window containers, which are a subtype of split\r
+containers) can have different border styles.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_client">3.5. Client</h3>\r
-<div class="paragraph"><p>A client is x11-speak for a window.</p></div>\r
+<h3 id="_x11_window_container">5.6. X11 window container</h3>\r
+<div class="paragraph"><p>An X11 window container holds exactly one X11 window. These are the leaf nodes\r
+of the layout tree, they cannot have any children.</p></div>\r
</div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_list_queue_macros">4. List/queue macros</h2>\r
+<h2 id="_list_queue_macros">6. List/queue macros</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>i3 makes heavy use of the list macros defined in BSD operating systems. To\r
ensure that the operating system on which i3 is compiled has all the expected\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_naming_conventions">5. Naming conventions</h2>\r
+<h2 id="_naming_conventions">7. Naming conventions</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>There is a row of standard variables used in many events. The following names\r
should be chosen for those:</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_startup_src_mainx_c_main">6. Startup (src/mainx.c, main())</h2>\r
+<h2 id="_startup_src_mainx_c_main">8. Startup (src/mainx.c, main())</h2>\r
<div class="sectionbody">\r
<div class="ulist"><ul>\r
<li>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_keybindings">7. Keybindings</h2>\r
+<h2 id="_keybindings">9. Keybindings</h2>\r
<div class="sectionbody">\r
<div class="sect2">\r
-<h3 id="_grabbing_the_bindings">7.1. Grabbing the bindings</h3>\r
+<h3 id="_grabbing_the_bindings">9.1. Grabbing the bindings</h3>\r
<div class="paragraph"><p>Grabbing the bindings is quite straight-forward. You pass X your combination of\r
modifiers and the keycode you want to grab and whether you want to grab them\r
actively or passively. Most bindings (everything except for bindings using\r
will handle the event, if not, it will replay the event.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_handling_a_keypress">7.2. Handling a keypress</h3>\r
+<h3 id="_handling_a_keypress">9.2. Handling a keypress</h3>\r
<div class="paragraph"><p>As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets\r
the correct state.</p></div>\r
<div class="paragraph"><p>Then, it looks through all bindings and gets the one which matches the received\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_manage_windows_src_main_c_manage_window_and_reparent_window">8. Manage windows (src/main.c, manage_window() and reparent_window())</h2>\r
+<h2 id="_manage_windows_src_main_c_manage_window_and_reparent_window">10. Manage windows (src/main.c, manage_window() and reparent_window())</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p><tt>manage_window()</tt> does some checks to decide whether the window should be\r
managed at all:</p></div>\r
</p>\r
</li>\r
</ul></div>\r
-<div class="paragraph"><p>Afterwards, i3 gets the intial geometry and reparents the window (see\r
+<div class="paragraph"><p>Afterwards, i3 gets the initial geometry and reparents the window (see\r
<tt>reparent_window()</tt>) if it wasn’t already managed.</p></div>\r
<div class="paragraph"><p>Reparenting means that for each window which is reparented, a new window,\r
slightly larger than the original one, is created. The original window is then\r
whether this window is a dock (<tt>_NET_WM_WINDOW_TYPE_DOCK</tt>), like dzen2 for\r
example. Docks are handled differently, they don’t have decorations and are not\r
assigned to a specific container. Instead, they are positioned at the bottom\r
-of the screen. To get the height which needs to be reserved for the window,\r
-the <tt>_NET_WM_STRUT_PARTIAL</tt> property is used.</p></div>\r
+or top of the screen (in the appropriate dock area containers). To get the\r
+height which needs to be reserved for the window, the <tt>_NET_WM_STRUT_PARTIAL</tt>\r
+property is used.</p></div>\r
<div class="paragraph"><p>Furthermore, the list of assignments (to other workspaces, which may be on\r
other screens) is checked. If the window matches one of the user’s criteria,\r
it may either be put in floating mode or moved to a different workspace. If the\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_what_happens_when_an_application_is_started">9. What happens when an application is started?</h2>\r
+<h2 id="_what_happens_when_an_application_is_started">11. What happens when an application is started?</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>i3 does not care for applications. All it notices is when new windows are\r
+<div class="paragraph"><p>i3 does not care about applications. All it notices is when new windows are\r
mapped (see <tt>src/handlers.c</tt>, <tt>handle_map_request()</tt>). The window is then\r
reparented (see section "Manage windows").</p></div>\r
<div class="paragraph"><p>After reparenting the window, <tt>render_tree()</tt> is called which renders the\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_net_wm_state">10. _NET_WM_STATE</h2>\r
+<h2 id="_net_wm_state">12. _NET_WM_STATE</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>Only the _NET_WM_STATE_FULLSCREEN atom is handled. It calls\r
-“toggle_fullscreen()” for the specific client which just configures the\r
-client to use the whole screen on which it currently is. Also, it is set as\r
-fullscreen_client for the i3Screen.</p></div>\r
+<div class="paragraph"><p>Only the _NET_WM_STATE_FULLSCREEN and _NET_WM_STATE_DEMANDS_ATTENTION atoms\r
+are handled.</p></div>\r
+<div class="paragraph"><p>The former calls “toggle_fullscreen()” for the specific client which just\r
+configures the client to use the whole screen on which it currently is.\r
+Also, it is set as fullscreen_client for the i3Screen.</p></div>\r
+<div class="paragraph"><p>The latter is used to set, read and display urgency hints.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_wm_name">11. WM_NAME</h2>\r
+<h2 id="_wm_name">13. WM_NAME</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>When the WM_NAME property of a window changes, its decoration (containing the\r
title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_net_wm_name">12. _NET_WM_NAME</h2>\r
+<h2 id="_net_wm_name">14. _NET_WM_NAME</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME\r
is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_size_hints">13. Size hints</h2>\r
+<h2 id="_size_hints">15. Size hints</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Size hints specify the minimum/maximum size for a given window as well as its\r
aspect ratio. This is important for clients like mplayer, who only set the\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_rendering_src_layout_c_render_layout_and_render_container">14. Rendering (src/layout.c, render_layout() and render_container())</h2>\r
+<h2 id="_rendering_src_layout_c_render_layout_and_render_container">16. Rendering (src/layout.c, render_layout() and render_container())</h2>\r
<div class="sectionbody">\r
-<div class="sidebarblock">\r
-<div class="content">\r
-<div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on\r
-time, but we will update this soon. Please talk to us on IRC if you need to\r
-know stuff <strong>NOW</strong> :).</p></div>\r
-</div></div>\r
+<div class="paragraph"><p>Rendering in i3 version 4 is the step which assigns the correct sizes for\r
+borders, decoration windows, child windows and the stacking order of all\r
+windows. In a separate step (<tt>x_push_changes()</tt>), these changes are pushed to\r
+X11.</p></div>\r
+<div class="paragraph"><p>Keep in mind that all these properties (<tt>rect</tt>, <tt>window_rect</tt> and <tt>deco_rect</tt>)\r
+are temporary, meaning they will be overwritten by calling <tt>render_con</tt>.\r
+Persistent position/size information is kept in <tt>geometry</tt>.</p></div>\r
+<div class="paragraph"><p>The entry point for every rendering operation (except for the case of moving\r
+floating windows around) currently is <tt>tree_render()</tt> which will re-render\r
+everything that’s necessary (for every output, only the currently displayed\r
+workspace is rendered). This behavior is expected to change in the future,\r
+since for a lot of updates, re-rendering everything is not actually necessary.\r
+Focus was on getting it working correct, not getting it work very fast.</p></div>\r
+<div class="paragraph"><p>What <tt>tree_render()</tt> actually does is calling <tt>render_con()</tt> on the root\r
+container and then pushing the changes to X11. The following sections talk\r
+about the different rendering steps, in the order of "top of the tree" (root\r
+container) to the bottom.</p></div>\r
+<div class="sect2">\r
+<h3 id="_rendering_the_root_container">16.1. Rendering the root container</h3>\r
+<div class="paragraph"><p>The i3 root container (<tt>con->type == CT_ROOT</tt>) represents the X11 root window.\r
+It contains one child container for every output (like LVDS1, VGA1, …), which\r
+is available on your computer.</p></div>\r
+<div class="paragraph"><p>Rendering the root will first render all tiling windows and then all floating\r
+windows. This is necessary because a floating window can be positioned in such\r
+a way that it is visible on two different outputs. Therefore, by first\r
+rendering all the tiling windows (of all outputs), we make sure that floating\r
+windows can never be obscured by tiling windows.</p></div>\r
+<div class="paragraph"><p>Essentially, though, this code path will just call <tt>render_con()</tt> for every\r
+output and <tt>x_raise_con(); render_con()</tt> for every floating window.</p></div>\r
+<div class="paragraph"><p>In the special case of having a "global fullscreen" window (fullscreen mode\r
+spanning all outputs), a shortcut is taken and <tt>x_raise_con(); render_con()</tt> is\r
+only called for the global fullscreen window.</p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_rendering_an_output">16.2. Rendering an output</h3>\r
+<div class="paragraph"><p>Output containers (<tt>con->layout == L_OUTPUT</tt>) represent a hardware output like\r
+LVDS1, VGA1, etc. An output container has three children (at the moment): One\r
+content container (having workspaces as children) and the top/bottom dock area\r
+containers.</p></div>\r
+<div class="paragraph"><p>The rendering happens in the function <tt>render_l_output()</tt> in the following\r
+steps:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+Find the content container (<tt>con->type == CT_CON</tt>)\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Get the currently visible workspace (<tt>con_get_fullscreen_con(content,\r
+ CF_OUTPUT)</tt>).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+If there is a fullscreened window on that workspace, directly render it and\r
+ return, thus ignoring the dock areas.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Sum up the space used by all the dock windows (they have a variable height\r
+ only).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Set the workspace rects (x/y/width/height) based on the position of the\r
+ output (stored in <tt>con->rect</tt>) and the usable space\r
+ (<tt>con->rect.{width,height}</tt> without the space used for dock windows).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Recursively raise and render the output’s child containers (meaning dock\r
+ area containers and the content container).\r
+</p>\r
+</li>\r
+</ol></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_rendering_a_workspace_or_split_container">16.3. Rendering a workspace or split container</h3>\r
+<div class="paragraph"><p>From here on, there really is no difference anymore. All containers are of\r
+<tt>con->type == CT_CON</tt> (whether workspace or split container) and some of them\r
+have a <tt>con->window</tt>, meaning they represent an actual window instead of a\r
+split container.</p></div>\r
+<div class="sect3">\r
+<h4 id="_default_layout">16.3.1. Default layout</h4>\r
+<div class="paragraph"><p>In default layout, containers are placed horizontally or vertically next to\r
+each other (depending on the <tt>con->orientation</tt>). If a child is a leaf node (as\r
+opposed to a split container) and has border style "normal", appropriate space\r
+will be reserved for its window decoration.</p></div>\r
+</div>\r
+<div class="sect3">\r
+<h4 id="_stacked_layout">16.3.2. Stacked layout</h4>\r
+<div class="paragraph"><p>In stacked layout, only the focused window is actually shown (this is achieved\r
+by calling <tt>x_raise_con()</tt> in reverse focus order at the end of <tt>render_con()</tt>).</p></div>\r
+<div class="paragraph"><p>The available space for the focused window is the size of the container minus\r
+the height of the window decoration for all windows inside this stacked\r
+container.</p></div>\r
+<div class="paragraph"><p>If border style is "1pixel" or "none", no window decoration height will be\r
+reserved (or displayed later on), unless there is more than one window inside\r
+the stacked container.</p></div>\r
+</div>\r
+<div class="sect3">\r
+<h4 id="_tabbed_layout">16.3.3. Tabbed layout</h4>\r
+<div class="paragraph"><p>Tabbed layout works precisely like stacked layout, but the window decoration\r
+position/size is different: They are placed next to each other on a single line\r
+(fixed height).</p></div>\r
+</div>\r
+<div class="sect3">\r
+<h4 id="_dock_area_layout">16.3.4. Dock area layout</h4>\r
+<div class="paragraph"><p>This is a special case. Users cannot choose the dock area layout, but it will be\r
+set for the dock area containers. In the dockarea layout (at the moment!),\r
+windows will be placed above each other.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_rendering_a_window">16.4. Rendering a window</h3>\r
+<div class="paragraph"><p>A window’s size and position will be determined in the following way:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+Subtract the border if border style is not "none" (but "normal" or "1pixel").\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Subtract the X11 border, if the window has an X11 border > 0.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Obey the aspect ratio of the window (think MPlayer).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Obey the height- and width-increments of the window (think terminal emulator\r
+ which can only be resized in one-line or one-character steps).\r
+</p>\r
+</li>\r
+</ol></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_user_commands_commandmode_src_cmdparse_l_y">15. User commands / commandmode (src/cmdparse.{l,y})</h2>\r
+<h2 id="_pushing_updates_to_x11_drawing">17. Pushing updates to X11 / Drawing</h2>\r
<div class="sectionbody">\r
-<div class="sidebarblock">\r
+<div class="paragraph"><p>A big problem with i3 before version 4 was that we just sent requests to X11\r
+anywhere in the source code. This was bad because nobody could understand the\r
+entirety of our interaction with X11, it lead to subtle bugs and a lot of edge\r
+cases which we had to consider all over again.</p></div>\r
+<div class="paragraph"><p>Therefore, since version 4, we have a single file, <tt>src/x.c</tt>, which is\r
+responsible for repeatedly transferring parts of our tree datastructure to X11.</p></div>\r
+<div class="paragraph"><p><tt>src/x.c</tt> consists of multiple parts:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+The state pushing: <tt>x_push_changes()</tt>, which calls <tt>x_push_node()</tt>.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+State modification functions: <tt>x_con_init</tt>, <tt>x_reinit</tt>,\r
+ <tt>x_reparent_child</tt>, <tt>x_move_win</tt>, <tt>x_con_kill</tt>, <tt>x_raise_con</tt>, <tt>x_set_name</tt>\r
+ and <tt>x_set_warp_to</tt>.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Expose event handling (drawing decorations): <tt>x_deco_recurse()</tt> and\r
+ <tt>x_draw_decoration()</tt>.\r
+</p>\r
+</li>\r
+</ol></div>\r
+<div class="sect2">\r
+<h3 id="_pushing_state_to_x11">17.1. Pushing state to X11</h3>\r
+<div class="paragraph"><p>In general, the function <tt>x_push_changes</tt> should be called to push state\r
+changes. Only when the scope of the state change is clearly defined (for\r
+example only the title of a window) and its impact is known beforehand, one can\r
+optimize this and call <tt>x_push_node</tt> on the appropriate con directly.</p></div>\r
+<div class="paragraph"><p><tt>x_push_changes</tt> works in the following steps:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+Clear the eventmask for all mapped windows. This leads to not getting\r
+ useless ConfigureNotify or EnterNotify events which are caused by our\r
+ requests. In general, we only want to handle user input.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Stack windows above each other, in reverse stack order (starting with the\r
+ most obscured/bottom window). This is relevant for floating windows which\r
+ can overlap each other, but also for tiling windows in stacked or tabbed\r
+ containers. We also update the <tt>_NET_CLIENT_LIST_STACKING</tt> hint which is\r
+ necessary for tab drag and drop in Chromium.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>x_push_node</tt> will be called for the root container, recursively calling\r
+ itself for the container’s children. This function actually pushes the\r
+ state, see the next paragraph.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+If the pointer needs to be warped to a different position (for example when\r
+ changing focus to a different output), it will be warped now.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The eventmask is restored for all mapped windows.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Window decorations will be rendered by calling <tt>x_deco_recurse</tt> on the root\r
+ container, which then recursively calls itself for the children.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+If the input focus needs to be changed (because the user focused a different\r
+ window), it will be updated now.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>x_push_node_unmaps</tt> will be called for the root container. This function\r
+ only pushes UnmapWindow requests. Separating the state pushing is necessary\r
+ to handle fullscreen windows (and workspace switches) in a smooth fashion:\r
+ The newly visible windows should be visible before the old windows are\r
+ unmapped.\r
+</p>\r
+</li>\r
+</ol></div>\r
+<div class="paragraph"><p><tt>x_push_node</tt> works in the following steps:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+Update the window’s <tt>WM_NAME</tt>, if changed (the <tt>WM_NAME</tt> is set on i3\r
+ containers mainly for debugging purposes).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Reparents a child window into the i3 container if the container was created\r
+ for a specific managed window.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+If the size/position of the i3 container changed (due to opening a new\r
+ window or switching layouts for example), the window will be reconfigured.\r
+ Also, the pixmap which is used to draw the window decoration/border on is\r
+ reconfigured (pixmaps are size-dependent).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Size/position for the child window is adjusted.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The i3 container is mapped if it should be visible and was not yet mapped.\r
+ When mapping, <tt>WM_STATE</tt> is set to <tt>WM_STATE_NORMAL</tt>. Also, the eventmask of\r
+ the child window is updated and the i3 container’s contents are copied from\r
+ the pixmap.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>x_push_node</tt> is called recursively for all children of the current\r
+ container.\r
+</p>\r
+</li>\r
+</ol></div>\r
+<div class="paragraph"><p><tt>x_push_node_unmaps</tt> handles the remaining case of an i3 container being\r
+unmapped if it should not be visible anymore. <tt>WM_STATE</tt> will be set to\r
+<tt>WM_STATE_WITHDRAWN</tt>.</p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_drawing_window_decorations_borders_backgrounds">17.2. Drawing window decorations/borders/backgrounds</h3>\r
+<div class="paragraph"><p><tt>x_draw_decoration</tt> draws window decorations. It is run for every leaf\r
+container (representing an actual X11 window) and for every non-leaf container\r
+which is in a stacked/tabbed container (because stacked/tabbed containers\r
+display a window decoration for split containers, which consists of a representation\r
+of the child container’s names.</p></div>\r
+<div class="paragraph"><p>Then, parameters are collected to be able to determine whether this decoration\r
+drawing is actually necessary or was already done. This saves a substantial\r
+number of redraws (depending on your workload, but far over 50%).</p></div>\r
+<div class="paragraph"><p>Assuming that we need to draw this decoration, we start by filling the empty\r
+space around the child window (think of MPlayer with a specific aspect ratio)\r
+in the user-configured client background color.</p></div>\r
+<div class="paragraph"><p>Afterwards, we draw the appropriate border (in case of border styles "normal"\r
+and "1pixel") and the top bar (in case of border style "normal").</p></div>\r
+<div class="paragraph"><p>The last step is drawing the window title on the top bar.</p></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_user_commands_parser_specs_commands_spec">18. User commands (parser-specs/commands.spec)</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>In the configuration file and when using i3 interactively (with <tt>i3-msg</tt>, for\r
+example), you use commands to make i3 do things, like focus a different window,\r
+set a window to fullscreen, and so on. An example command is <tt>floating enable</tt>,\r
+which enables floating mode for the currently focused window. See the\r
+appropriate section in the <a href="userguide.html">User’s Guide</a> for a reference of\r
+all commands.</p></div>\r
+<div class="paragraph"><p>In earlier versions of i3, interpreting these commands was done using lex and\r
+yacc, but experience has shown that lex and yacc are not well suited for our\r
+command language. Therefore, starting from version 4.2, we use a custom parser\r
+for user commands and the configuration file.\r
+The input specification for this parser can be found in the file\r
+<tt>parser-specs/*.spec</tt>. Should you happen to use Vim as an editor, use\r
+:source parser-specs/highlighting.vim to get syntax highlighting for this file\r
+(highlighting files for other editors are welcome).</p></div>\r
+<div class="listingblock">\r
+<div class="title">Excerpt from commands.spec</div>\r
<div class="content">\r
-<div class="paragraph"><p>This section has not been updated for v4.0 yet, sorry! We wanted to release on\r
-time, but we will update this soon. Please talk to us on IRC if you need to\r
-know stuff <strong>NOW</strong> :).</p></div>\r
+<pre><tt>state INITIAL:\r
+ '[' -> call cmd_criteria_init(); CRITERIA\r
+ 'move' -> MOVE\r
+ 'exec' -> EXEC\r
+ 'workspace' -> WORKSPACE\r
+ 'exit' -> call cmd_exit()\r
+ 'restart' -> call cmd_restart()\r
+ 'reload' -> call cmd_reload()</tt></pre>\r
</div></div>\r
+<div class="paragraph"><p>The input specification is written in an extremely simple format. The\r
+specification is then converted into C code by the Perl script\r
+generate-commands-parser.pl (the output file names begin with GENERATED and the\r
+files are stored in the <tt>include</tt> directory). The parser implementation\r
+<tt>src/commands_parser.c</tt> includes the generated C code at compile-time.</p></div>\r
+<div class="paragraph"><p>The above excerpt from commands.spec illustrates nearly all features of our\r
+specification format: You describe different states and what can happen within\r
+each state. State names are all-caps; the state in the above excerpt is called\r
+INITIAL. A list of tokens and their actions (separated by an ASCII arrow)\r
+follows. In the excerpt, all tokens are literals, that is, simple text strings\r
+which will be compared with the input. An action is either the name of a state\r
+in which the parser will transition into, or the keyword <em>call</em>, followed by\r
+the name of a function (and optionally a state).</p></div>\r
+<div class="sect2">\r
+<h3 id="_example_the_workspace_state">18.1. Example: The WORKSPACE state</h3>\r
+<div class="paragraph"><p>Let’s have a look at the WORKSPACE state, which is a good example of all\r
+features. This is its definition:</p></div>\r
+<div class="listingblock">\r
+<div class="title">WORKSPACE state (commands.spec)</div>\r
+<div class="content">\r
+<pre><tt># workspace next|prev|next_on_output|prev_on_output\r
+# workspace back_and_forth\r
+# workspace <name>\r
+# workspace number <number>\r
+state WORKSPACE:\r
+ direction = 'next_on_output', 'prev_on_output', 'next', 'prev'\r
+ -> call cmd_workspace($direction)\r
+ 'back_and_forth'\r
+ -> call cmd_workspace_back_and_forth()\r
+ 'number'\r
+ -> WORKSPACE_NUMBER\r
+ workspace = string\r
+ -> call cmd_workspace_name($workspace)</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>As you can see from the commands, there are multiple different valid variants\r
+of the workspace command:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+workspace <direction>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The word <em>workspace</em> can be followed by any of the tokens <em>next</em>,\r
+ <em>prev</em>, <em>next_on_output</em> or <em>prev_on_output</em>. This command will\r
+ switch to the next or previous workspace (optionally on the same\r
+ output).<br />\r
+ There is one function called <tt>cmd_workspace</tt>, which is defined\r
+ in <tt>src/commands.c</tt>. It will handle this kind of command. To know which\r
+ direction was specified, the direction token is stored on the stack\r
+ with the name "direction", which is what the "direction = " means in\r
+ the beginning.<br />\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">Note that you can specify multiple literals in the same line. This has\r
+ exactly the same effect as if you specified <tt>direction =\r
+ 'next_on_output' -> call cmd_workspace($direction)</tt> and so forth.<br /></td>\r
+</tr></table>\r
+</div>\r
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">Also note that the order of literals is important here: If <em>next</em> were\r
+ ordered before <em>next_on_output</em>, then <em>next_on_output</em> would never\r
+ match.</td>\r
+</tr></table>\r
+</div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+workspace back_and_forth\r
+</dt>\r
+<dd>\r
+<p>\r
+ This is a very simple case: When the literal <em>back_and_forth</em> is found\r
+ in the input, the function <tt>cmd_workspace_back_and_forth</tt> will be\r
+ called without parameters and the parser will return to the INITIAL\r
+ state (since no other state was specified).\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+workspace <name>\r
+</dt>\r
+<dd>\r
+<p>\r
+ In this case, the workspace command is followed by an arbitrary string,\r
+ possibly in quotes, for example "workspace 3" or "workspace bleh".<br />\r
+ This is the first time that the token is actually not a literal (not in\r
+ single quotes), but just called string. Other possible tokens are word\r
+ (the same as string, but stops matching at a whitespace) and end\r
+ (matches the end of the input).\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+workspace number <number>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The workspace command has to be followed by the keyword <tt>number</tt>. It\r
+ then transitions into the state <tt>WORKSPACE_NUMBER</tt>, where the actual\r
+ parameter will be read.\r
+</p>\r
+</dd>\r
+</dl></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_introducing_a_new_command">18.2. Introducing a new command</h3>\r
+<div class="paragraph"><p>The following steps have to be taken in order to properly introduce a new\r
+command (or possibly extend an existing command):</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+Define a function beginning with <tt>cmd_</tt> in the file <tt>src/commands.c</tt>. Copy\r
+ the prototype of an existing function.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+After adding a comment on what the function does, copy the comment and\r
+ function definition to <tt>include/commands.h</tt>. Make the comment in the header\r
+ file use double asterisks to make doxygen pick it up.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Write a test case (or extend an existing test case) for your feature, see\r
+ <a href="testsuite.html">i3 testsuite</a>. For now, it is sufficient to simply call\r
+ your command in all the various possible ways.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Extend the parser specification in <tt>parser-specs/commands.spec</tt>. Run the\r
+ testsuite and see if your new function gets called with the appropriate\r
+ arguments for the appropriate input.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Actually implement the feature.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Document the feature in the <a href="userguide.html">User’s Guide</a>.\r
+</p>\r
+</li>\r
+</ol></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_moving_containers">16. Moving containers</h2>\r
+<h2 id="_moving_containers">19. Moving containers</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>The movement code is pretty delicate. You need to consider all cases before\r
making any changes or before being able to fully understand how it works.</p></div>\r
<div class="sect2">\r
-<h3 id="_case_1_moving_inside_the_same_container">16.1. Case 1: Moving inside the same container</h3>\r
+<h3 id="_case_1_moving_inside_the_same_container">19.1. Case 1: Moving inside the same container</h3>\r
<div class="paragraph"><p>The reference layout for this case is a single workspace in horizontal\r
orientation with two containers on it. Focus is on the left container (1).</p></div>\r
<div class="tableblock">\r
of the current one and swaps both containers.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_case_2_move_a_container_into_a_split_container">16.2. Case 2: Move a container into a split container</h3>\r
+<h3 id="_case_2_move_a_container_into_a_split_container">19.2. Case 2: Move a container into a split container</h3>\r
<div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two\r
containers. The right container is a v-split with two containers. Focus is on\r
the left container (1).</p></div>\r
be flattened.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_case_3_moving_to_non_existant_top_bottom">16.3. Case 3: Moving to non-existant top/bottom</h3>\r
+<h3 id="_case_3_moving_to_non_existent_top_bottom">19.3. Case 3: Moving to non-existent top/bottom</h3>\r
<div class="paragraph"><p>Like in case 1, the reference layout for this case is a single workspace in\r
horizontal orientation with two containers on it. Focus is on the left\r
container:</p></div>\r
flattened.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_case_4_moving_to_existant_top_bottom">16.4. Case 4: Moving to existant top/bottom</h3>\r
+<h3 id="_case_4_moving_to_existent_top_bottom">19.4. Case 4: Moving to existent top/bottom</h3>\r
<div class="paragraph"><p>The reference layout for this case is a vertical workspace with two containers.\r
The bottom one is a h-split containing two containers (1 and 2). Focus is on\r
the bottom left container (1).</p></div>\r
is in vertical orientation.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_case_5_moving_in_one_child_h_split">16.5. Case 5: Moving in one-child h-split</h3>\r
+<h3 id="_case_5_moving_in_one_child_h_split">19.5. Case 5: Moving in one-child h-split</h3>\r
<div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two\r
containers having a v-split on the left side with a one-child h-split on the\r
bottom. Focus is on the bottom left container (2(h)):</p></div>\r
4.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_case_6_floating_containers">16.6. Case 6: Floating containers</h3>\r
+<h3 id="_case_6_floating_containers">19.6. Case 6: Floating containers</h3>\r
<div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two\r
containers plus one floating h-split container. Focus is on the floating\r
container.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_click_handling">17. Click handling</h2>\r
+<h2 id="_click_handling">20. Click handling</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Without much ado, here is the list of cases which need to be considered:</p></div>\r
<div class="ulist"><ul>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_gotchas">18. Gotchas</h2>\r
+<h2 id="_gotchas">21. Gotchas</h2>\r
<div class="sectionbody">\r
<div class="ulist"><ul>\r
<li>\r
certain conditions.\r
</p>\r
</li>\r
+<li>\r
+<p>\r
+Forgetting to call <tt>floating_fix_coordinates(con, old_rect, new_rect)</tt> after\r
+ moving workspaces across outputs. Coordinates for floating containers are\r
+ not relative to workspace boundaries, so you must correct their coordinates\r
+ or those containers will show up in the wrong workspace or not at all.\r
+</p>\r
+</li>\r
</ul></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_using_git_sending_patches">19. Using git / sending patches</h2>\r
+<h2 id="_thought_experiments">22. Thought experiments</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>For a short introduction into using git, see\r
-<a href="http://www.spheredev.org/wiki/Git_for_the_lazy">http://www.spheredev.org/wiki/Git_for_the_lazy</a> or, for more documentation, see\r
-<a href="http://git-scm.com/documentation">http://git-scm.com/documentation</a></p></div>\r
-<div class="paragraph"><p>When you want to send a patch because you fixed a bug or implemented a cool\r
-feature (please talk to us before working on features to see whether they are\r
-maybe already implemented, not possible for some some reason, or don’t fit\r
-into the concept), please use git to create a patchfile.</p></div>\r
-<div class="paragraph"><p>First of all, update your working copy to the latest version of the master\r
-branch:</p></div>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>git pull</tt></pre>\r
-</div></div>\r
-<div class="paragraph"><p>Afterwards, make the necessary changes for your bugfix/feature. Then, review\r
-the changes using <tt>git diff</tt> (you might want to enable colors in the diff using\r
-<tt>git config diff.color auto</tt>). When you are definitely done, use <tt>git commit\r
--a</tt> to commit all changes you’ve made.</p></div>\r
-<div class="paragraph"><p>Then, use the following command to generate a patchfile which we can directly\r
-apply to the branch, preserving your commit message and name:</p></div>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>git format-patch origin</tt></pre>\r
-</div></div>\r
-<div class="paragraph"><p>Just send us the generated file via email.</p></div>\r
+<div class="paragraph"><p>In this section, we collect thought experiments, so that we don’t forget our\r
+thoughts about specific topics. They are not necessary to get into hacking i3,\r
+but if you are interested in one of the topics they cover, you should read them\r
+before asking us why things are the way they are or why we don’t implement\r
+things.</p></div>\r
+<div class="sect2">\r
+<h3 id="_using_cgroups_per_workspace">22.1. Using cgroups per workspace</h3>\r
+<div class="paragraph"><p>cgroups (control groups) are a linux-only feature which provides the ability to\r
+group multiple processes. For each group, you can individually set resource\r
+limits, like allowed memory usage. Furthermore, and more importantly for our\r
+purposes, they serve as a namespace, a label which you can attach to processes\r
+and their children.</p></div>\r
+<div class="paragraph"><p>One interesting use for cgroups is having one cgroup per workspace (or\r
+container, doesn’t really matter). That way, you could set different priorities\r
+and have a workspace for important stuff (say, writing a LaTeX document or\r
+programming) and a workspace for unimportant background stuff (say,\r
+JDownloader). Both tasks can obviously consume a lot of I/O resources, but in\r
+this example it doesn’t really matter if JDownloader unpacks the download a\r
+minute earlier or not. However, your compiler should work as fast as possible.\r
+Having one cgroup per workspace, you would assign more resources to the\r
+programming workspace.</p></div>\r
+<div class="paragraph"><p>Another interesting feature is that an inherent problem of the workspace\r
+concept could be solved by using cgroups: When starting an application on\r
+workspace 1, then switching to workspace 2, you will get the application’s\r
+window(s) on workspace 2 instead of the one you started it on. This is because\r
+the window manager does not have any mapping between the process it starts (or\r
+gets started in any way) and the window(s) which appear.</p></div>\r
+<div class="paragraph"><p>Imagine for example using dmenu: The user starts dmenu by pressing Mod+d, dmenu\r
+gets started with PID 3390. The user then decides to launch Firefox, which\r
+takes a long time. So they enter firefox into dmenu and press enter. Firefox\r
+gets started with PID 4001. When it finally finishes loading, it creates an X11\r
+window and uses MapWindow to make it visible. This is the first time i3\r
+actually gets in touch with Firefox. It decides to map the window, but it has\r
+no way of knowing that this window (even though it has the _NET_WM_PID property\r
+set to 4001) belongs to the dmenu the user started before.</p></div>\r
+<div class="paragraph"><p>How do cgroups help with this? Well, when pressing Mod+d to launch dmenu, i3\r
+would create a new cgroup, let’s call it i3-3390-1. It launches dmenu in that\r
+cgroup, which gets PID 3390. As before, the user enters firefox and Firefox\r
+gets launched with PID 4001. This time, though, the Firefox process with PID\r
+4001 is <strong>also</strong> member of the cgroup i3-3390-1 (because fork()ing in a cgroup\r
+retains the cgroup property). Therefore, when mapping the window, i3 can look\r
+up in which cgroup the process is and can establish a mapping between the\r
+workspace and the window.</p></div>\r
+<div class="paragraph"><p>There are multiple problems with this approach:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+Every application has to properly set <tt>_NET_WM_PID</tt>. This is acceptable and\r
+ patches can be written for the few applications which don’t set the hint yet.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+It does only work on Linux, since cgroups are a Linux-only feature. Again,\r
+ this is acceptable.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The main problem is that some applications create X11 windows completely\r
+ independent of UNIX processes. An example for this is Chromium (or\r
+ gnome-terminal), which, when being started a second time, communicates with\r
+ the first process and lets the first process open a new window. Therefore, if\r
+ you have a Chromium window on workspace 2 and you are currently working on\r
+ workspace 3, starting <tt>chromium</tt> does not lead to the desired result (the\r
+ window will open on workspace 2).\r
+</p>\r
+</li>\r
+</ol></div>\r
+<div class="paragraph"><p>Therefore, my conclusion is that the only proper way of fixing the "window gets\r
+opened on the wrong workspace" problem is in the application itself. Most\r
+modern applications support freedesktop startup-notifications which can be\r
+used for this.</p></div>\r
+</div>\r
</div>\r
</div>\r
</div>\r
<div id="footnotes"><hr /></div>\r
<div id="footer" lang="de">\r
-© 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>\r
+ © 2009-present Michael Stapelberg,\r
+ <a href="/impress.html">Impressum</a>,\r
+ <a href="https://github.com/i3/i3.github.io">Source</a>\r
</div>\r
</body>\r
</html>\r
projects / i3 / i3.github.io / blobdiff