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