git.sur5r.net Git - i3/i3.github.io/blob - docs/tree-migrating.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
   4 <head>\r
   5 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
   6 <meta name="generator" content="AsciiDoc 8.6.4" />\r
   7 <title>i3: Tree branch: Migrating</title>\r
   8 <link rel="stylesheet" href="/css/style.css" type="text/css" />\r
   9 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
  10 <script type="text/javascript">\r
  11 /*<![CDATA[*/\r
  12 window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}\r
  13 /*]]>*/\r
  14 </script>\r
  15 <script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\r
  16 </head>\r
  17 <body class="article">\r
  18 \r
  19         <div id="main">\r
  20             <h1 id="title">i3 - improved tiling WM</h1>\r
  21                         <ul id="nav">\r
  22                                 <li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>\r
  23                                 <li><a href="/screenshots">Screens</a></li>\r
  24                                 <li><a href="/contact">Contact</a></li>\r
  25                                 <li><a href="http://bugs.i3wm.org/">Bugs</a></li>\r
  26                         </ul>\r
  27         <br style="clear: both">\r
  28 <div id="content">\r
  29 <div id="header">\r
  30 <h1>Tree branch: Migrating</h1>\r
  31 <span id="author">Michael Stapelberg</span><br />\r
  32 <span id="email"><tt>&lt;<a href="mailto:michael+i3@stapelberg.de">michael+i3@stapelberg.de</a>&gt;</tt></span><br />\r
  33 <span id="revdate">November 2010</span>\r
  34 <div id="toc">
  35   <div id="toctitle">Table of Contents</div>
  36   <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
  37 </div>\r
  38 </div>\r
  39 <div class="sect1">\r
  40 <h2 id="_introduction">1. Introduction</h2>\r
  41 <div class="sectionbody">\r
  42 <div class="paragraph"><p>The tree branch (referring to a branch of i3 in the git repository) is the new\r
  43 version of i3. Due to the very deep changes and heavy refactoring of the source\r
  44 source, we decided to develop it in a seperate branch (instead of using the\r
  45 next/master-branch system like before).</p></div>\r
  46 </div>\r
  47 </div>\r
  48 <div class="sect1">\r
  49 <h2 id="_current_status">2. Current status</h2>\r
  50 <div class="sectionbody">\r
  51 <div class="paragraph"><p>Currently, the code is mostly working. Some of the i3 core developers have been\r
  52 using the tree branch version for a few weeks now. So, if you are eager to try\r
  53 out the new features and help us find bugs, give it a try!</p></div>\r
  54 <div class="paragraph"><p>At the same time, a word of warning is appropriate: This version of i3 might\r
  55 crash unexpectedly, so please be careful with important data (do not work for\r
  56 two days without saving…).</p></div>\r
  57 </div>\r
  58 </div>\r
  59 <div class="sect1">\r
  60 <h2 id="_getting_the_latest_tree_branch_version">3. Getting the latest tree branch version</h2>\r
  61 <div class="sectionbody">\r
  62 <div class="paragraph"><p>Check out the latest version:</p></div>\r
  63 <div class="listingblock">\r
  64 <div class="content">\r
  65 <pre><tt>$ git clone -b tree git://code.stapelberg.de/i3</tt></pre>\r
  66 </div></div>\r
  67 <div class="paragraph"><p>Then build and install it (has the same dependencies as the latest stable i3\r
  68 version):</p></div>\r
  69 <div class="listingblock">\r
  70 <div class="content">\r
  71 <pre><tt>$ cd i3\r
  72 $ make\r
  73 $ sudo cp i3 /usr/bin/i3-tree</tt></pre>\r
  74 </div></div>\r
  75 <div class="paragraph"><p>…and execute <tt>i3-tree</tt> instead of <tt>i3</tt> in your Xsession.</p></div>\r
  76 <div class="paragraph"><p><strong>IMPORTANT:</strong> Please note that configuration file compatibility is not yet done.\r
  77 So, make sure you use/customize the provided <tt>i3.config</tt> file.</p></div>\r
  78 </div>\r
  79 </div>\r
  80 <div class="sect1">\r
  81 <h2 id="_tree">4. Tree</h2>\r
  82 <div class="sectionbody">\r
  83 <div class="paragraph"><p>The most important change and reason for the name is that i3 stores all\r
  84 information about the X11 outputs, workspaces and layout of the windows on them\r
  85 in a tree. The root node is the X11 root window, followed by the X11 outputs,\r
  86 then workspaces and finally the windows themselve. In previous versions of i3\r
  87 we had multiple lists (of outputs, workspaces) and a table for each workspace.\r
  88 That approach turned out to be complicated to use (snapping), understand and\r
  89 implement.</p></div>\r
  90 <div class="sect2">\r
  91 <h3 id="_the_tree_consists_of_containers">4.1. The tree consists of Containers</h3>\r
  92 <div class="paragraph"><p>The building blocks of our tree are so called <tt>Containers</tt>. A <tt>Container</tt> can\r
  93 host a window (meaning an X11 window, one that you can actually see and use,\r
  94 like a browser). Alternatively, it could contain one or more <tt>Containers</tt>. A\r
  95 simple example is the workspace: When you start i3 with a single monitor, a\r
  96 single workspace and you open two terminal windows, you will end up with a tree\r
  97 like this:</p></div>\r
  98 <div class="imageblock" style="float:right;">\r
  99 <div class="content">\r
 100 <img src="tree-layout2.png" alt="layout2" />\r
 101 </div>\r
 102 </div>\r
 103 <div class="imageblock">\r
 104 <div class="content">\r
 105 <img src="tree-shot4.png" alt="shot4" />\r
 106 </div>\r
 107 <div class="title">Figure 1. Two terminals on standard workspace</div>\r
 108 </div>\r
 109 </div>\r
 110 <div class="sect2">\r
 111 <h3 id="_orientation_and_split_containers">4.2. Orientation and Split Containers</h3>\r
 112 <div class="paragraph" id="OrientationSplit"><p>It is only natural to use so-called <tt>Split Containers</tt> in order to build a\r
 113 layout when using a tree as data structure. In i3, every <tt>Container</tt> has an\r
 114 orientation (horizontal, vertical or unspecified). So, in our example with the\r
 115 workspace, the default orientation of the workspace <tt>Container</tt> is horizontal\r
 116 (most monitors are widescreen nowadays). If you change the orientation to\r
 117 vertical (<tt>Alt+v</tt> in the default config) and <strong>then</strong> open two terminals, i3 will\r
 118 configure your windows like this:</p></div>\r
 119 <div class="imageblock">\r
 120 <div class="content">\r
 121 <img src="tree-shot2.png" alt="shot2" />\r
 122 </div>\r
 123 <div class="title">Figure 2. Vertical Workspace Orientation</div>\r
 124 </div>\r
 125 <div class="paragraph"><p>An interesting new feature of the tree branch is the ability to split anything:\r
 126 Let’s assume you have two terminals on a workspace (with horizontal\r
 127 orientation), focus is on the right terminal. Now you want to open another\r
 128 terminal window below the current one. If you would just open a new terminal\r
 129 window, it would show up to the right due to the horizontal workspace\r
 130 orientation. Instead, press <tt>Alt+v</tt> to create a <tt>Vertical Split Container</tt> (to\r
 131 open a <tt>Horizontal Split Container</tt>, use <tt>Alt+h</tt>). Now you can open a new\r
 132 terminal and it will open below the current one:</p></div>\r
 133 <div class="imageblock" style="float:right;">\r
 134 <div class="content">\r
 135 <img src="tree-layout1.png" alt="Layout" />\r
 136 </div>\r
 137 </div>\r
 138 <div class="imageblock">\r
 139 <div class="content">\r
 140 <img src="tree-shot1.png" alt="shot" />\r
 141 </div>\r
 142 <div class="title">Figure 3. Vertical Split Container</div>\r
 143 </div>\r
 144 <div style="clear:both;"></div>\r
 145 <div class="paragraph"><p>You probably guessed it already: There is no limit on how deep your hierarchy\r
 146 of splits can be.</p></div>\r
 147 </div>\r
 148 <div class="sect2">\r
 149 <h3 id="_level_up">4.3. Level up</h3>\r
 150 <div class="paragraph"><p>Let’s stay with our example from above. We have a terminal on the left and two\r
 151 vertically split terminals on the right, focus is on the bottom right one. When\r
 152 you open a new terminal, it will open below the current one.</p></div>\r
 153 <div class="paragraph"><p>So, how can you open a new terminal window to the <strong>right</strong> of the current one?\r
 154 The solution is to use <tt>level up</tt>, which will focus the <tt>Parent Container</tt> of\r
 155 the current <tt>Container</tt>. In this case, you would focus the <tt>Vertical Split\r
 156 Container</tt> which is <strong>inside</strong> the horizontally oriented workspace. Thus, now new\r
 157 windows will be opened to the right of the <tt>Vertical Split Container</tt>:</p></div>\r
 158 <div class="imageblock">\r
 159 <div class="content">\r
 160 <img src="tree-shot3.png" alt="shot3" />\r
 161 </div>\r
 162 <div class="title">Figure 4. Level Up, then open new terminal</div>\r
 163 </div>\r
 164 </div>\r
 165 </div>\r
 166 </div>\r
 167 <div class="sect1">\r
 168 <h2 id="_commands">5. Commands</h2>\r
 169 <div class="sectionbody">\r
 170 <div class="paragraph"><p>The authoritive reference for commands is <tt>src/cmdparse.y</tt>. You can also find\r
 171 most commands in <tt>i3.config</tt>. Here comes a short overview over the important\r
 172 commands:</p></div>\r
 173 <div class="sect2">\r
 174 <h3 id="_manipulating_layout">5.1. Manipulating layout</h3>\r
 175 <div class="listingblock">\r
 176 <div class="content">\r
 177 <pre><tt>layout &lt;default|stacked|tabbed&gt;</tt></pre>\r
 178 </div></div>\r
 179 </div>\r
 180 <div class="sect2">\r
 181 <h3 id="_changing_focus">5.2. Changing Focus</h3>\r
 182 <div class="listingblock">\r
 183 <div class="content">\r
 184 <pre><tt>next &lt;horizontal|vertical&gt;\r
 185 prev &lt;horizontal|vertical&gt;</tt></pre>\r
 186 </div></div>\r
 187 <div class="listingblock">\r
 188 <div class="title">Examples:</div>\r
 189 <div class="content">\r
 190 <pre><tt>bindsym Mod1+Left prev h\r
 191 bindsym Mod1+Right next h\r
 192 bindsym Mod1+Down next v\r
 193 bindsym Mod1+Up prev v</tt></pre>\r
 194 </div></div>\r
 195 </div>\r
 196 <div class="sect2">\r
 197 <h3 id="_moving">5.3. Moving</h3>\r
 198 <div class="listingblock">\r
 199 <div class="content">\r
 200 <pre><tt>move &lt;before|after&gt; &lt;horizontal|vertical&gt;</tt></pre>\r
 201 </div></div>\r
 202 <div class="listingblock">\r
 203 <div class="title">Examples:</div>\r
 204 <div class="content">\r
 205 <pre><tt>bindsym Mod1+Shift+Left move before h\r
 206 bindsym Mod1+Shift+Right move after h\r
 207 bindsym Mod1+Shift+Down move before v\r
 208 bindsym Mod1+Shift+Up move after v</tt></pre>\r
 209 </div></div>\r
 210 </div>\r
 211 <div class="sect2">\r
 212 <h3 id="_changing_workspace">5.4. Changing workspace</h3>\r
 213 <div class="listingblock">\r
 214 <div class="content">\r
 215 <pre><tt>workspace &lt;name&gt;</tt></pre>\r
 216 </div></div>\r
 217 <div class="listingblock">\r
 218 <div class="title">Examples:</div>\r
 219 <div class="content">\r
 220 <pre><tt>bindsym Mod1+1 workspace 1\r
 221 bindsym Mod1+2 workspace 2\r
 222 …</tt></pre>\r
 223 </div></div>\r
 224 </div>\r
 225 <div class="sect2">\r
 226 <h3 id="_moving_containers_to_workspaces">5.5. Moving Containers to workspaces</h3>\r
 227 <div class="listingblock">\r
 228 <div class="content">\r
 229 <pre><tt>move workspace &lt;name&gt;</tt></pre>\r
 230 </div></div>\r
 231 <div class="listingblock">\r
 232 <div class="content">\r
 233 <pre><tt>bindsym Mod1+Shift+1 move workspace 1\r
 234 bindsym Mod1+Shift+2 move workspace 2\r
 235 …</tt></pre>\r
 236 </div></div>\r
 237 </div>\r
 238 <div class="sect2">\r
 239 <h3 id="_changing_border_style">5.6. Changing border style</h3>\r
 240 <div class="listingblock">\r
 241 <div class="content">\r
 242 <pre><tt>border &lt;normal|none|1pixel&gt;</tt></pre>\r
 243 </div></div>\r
 244 </div>\r
 245 <div class="sect2">\r
 246 <h3 id="_changing_container_mode">5.7. Changing container mode</h3>\r
 247 <div class="listingblock">\r
 248 <div class="content">\r
 249 <pre><tt>mode &lt;tiling|floating|toggle&gt;</tt></pre>\r
 250 </div></div>\r
 251 </div>\r
 252 </div>\r
 253 </div>\r
 254 <div class="sect1">\r
 255 <h2 id="_the_rest">6. The rest</h2>\r
 256 <div class="sectionbody">\r
 257 <div class="paragraph"><p>What is not mentioned here explicitly is either unchanged and can be read in\r
 258 the <a href="http://i3.zekjur.net/docs/userguide.html">i3 User’s Guide</a> or it is not yet\r
 259 implemented.</p></div>\r
 260 </div>\r
 261 </div>\r
 262 </div>\r
 263 <div id="footnotes"><hr /></div>\r
 264 <div id="footer">\r
 265 <div id="footer-text">\r
 266 Last updated 2011-07-22 20:29:30 CEST\r
 267 </div>\r
 268 </div>\r
 269 </body>\r
 270 </html>\r