--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
+ "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/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.9" />\r
+<title>i3: Layout saving in i3</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
+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
+</head>\r
+<body class="article">\r
+\r
+ <div id="main">\r
+ <a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>\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="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>Layout saving in i3</h1>\r
+<span id="author">Michael Stapelberg</span><br />\r
+<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
+<span id="revdate">April 2014</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>
+</div>\r
+</div>\r
+<div id="preamble">\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>Layout saving/restoring is a feature that was introduced in i3 v4.8.</p></div>\r
+<div class="paragraph"><p>Layout saving/restoring allows you to load a JSON layout file so that you can\r
+have a base layout to start working with after powering on your computer.\r
+Dynamic use-cases also come to mind: if you frequently (but not always!) need a\r
+grid layout of terminals with ping/traceroute commands to diagnose network\r
+issues, you can easily automate opening these windows in just the right layout.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_saving_the_layout">1. Saving the layout</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>You can save the layout of either a single workspace or an entire output (e.g.\r
+LVDS1). Of course, you can repeat this step multiple times if you want to\r
+save/restore multiple workspaces/outputs.</p></div>\r
+<div class="paragraph"><p><tt>i3-save-tree(1)</tt> is a tool to save the layout. It will print a JSON\r
+representation of i3’s internal layout data structures to stdout. Typically,\r
+you may want to take a quick look at the output, then save it to a file and\r
+tweak it a little bit:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>i3-save-tree --workspace 1 > ~/.i3/workspace-1.json</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Please note that the output of <tt>i3-save-tree(1)</tt> is <strong>NOT useful</strong> until you\r
+manually modify it — you need to tell i3 how to match/distinguish windows (for\r
+example based on their WM_CLASS, title, etc.). By default, all the different\r
+window properties are included in the output, but commented out. This is partly\r
+to avoid relying on heuristics and partly to make you aware how i3 works so\r
+that you can easily solve layout restoring problems.</p></div>\r
+<div class="paragraph"><p>How to modify the file manually is described in <a href="#EditingLayoutFiles">[EditingLayoutFiles]</a>.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_restoring_the_layout">2. Restoring the layout</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>After restoring the example layout from <a href="#EditingLayoutFiles">[EditingLayoutFiles]</a>, i3 will open\r
+placeholder windows for all the windows that were specified in the layout file.\r
+You can recognize the placeholder windows by the watch symbol\r
+<span class="footnote"><br />[Depending on the font you are using, a placeholder symbol may show up\r
+instead of the watch symbol.]<br /></span> in the center of the window, and by the swallow\r
+criteria specification at the top of the window:</p></div>\r
+<div class="paragraph"><p><span class="image">\r
+<a class="image" href="layout-saving-1.png">\r
+<img src="layout-saving-1.png" alt="Restored layout" width="400" />\r
+</a>\r
+</span></p></div>\r
+<div class="paragraph"><p>When an application opens a window that matches the specified swallow criteria,\r
+it will be placed in the corresponding placeholder window. We say it gets\r
+<strong>swallowed</strong> by the placeholder container, hence the term.</p></div>\r
+<div class="paragraph"><p>Note: Swallowing windows into unsatisfied placeholder windows takes precedence\r
+over\r
+<a href="http://i3wm.org/docs/userguide.html#_automatically_putting_clients_on_specific_workspaces">assignment\r
+rules</a>. For example, if you assign all Emacs windows to workspace 1 in your i3\r
+configuration file, but there is a placeholder window on workspace 2 which\r
+matches Emacs as well, your newly started Emacs window will end up in the\r
+placeholder window on workspace 2.</p></div>\r
+<div class="paragraph"><p>The placeholder windows are just regular windows, so feel free to move them\r
+around or close them, for example.</p></div>\r
+<div class="sect2">\r
+<h3 id="_append_layout_command">2.1. append_layout command</h3>\r
+<div class="paragraph"><p>The <tt>append_layout</tt> command is used to load a layout file into i3. It accepts a\r
+path (relative to i3’s current working directory or absolute) to a JSON file.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>append_layout <path></tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt># From a terminal or script:\r
+i3-msg "workspace 1; append_layout /home/michael/.i3/workspace-1.json"\r
+\r
+# In your i3 configuration file, you can autostart i3-msg like this:\r
+# (Note that those lines will quickly become long, so typically you would store\r
+# them in a script with proper indentation.)\r
+exec --no-startup-id "i3-msg 'workspace 1; append_layout /home/michael/.i3/workspace-1.json'"</tt></pre>\r
+</div></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_editing_layout_files">3. Editing layout files</h2>\r
+<div class="sectionbody">\r
+<div class="sect2">\r
+<h3 id="EditingLayoutFiles">3.1. Anatomy of a layout file</h3>\r
+<div class="paragraph"><p>Here is an example layout file that we’ll discuss:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{\r
+ // splitv split container with 2 children\r
+ "layout": "splitv",\r
+ "percent": 0.4,\r
+ "type": "con",\r
+ "nodes": [\r
+ {\r
+ "border": "none",\r
+ "name": "irssi",\r
+ "percent": 0.5,\r
+ "type": "con",\r
+ "swallows": [\r
+ {\r
+ "class": "^URxvt$",\r
+ "instance": "^irssi$"\r
+ }\r
+ ]\r
+ },\r
+ {\r
+ // stacked split container with 2 children\r
+ "layout": "stacked",\r
+ "percent": 0.5,\r
+ "type": "con",\r
+ "nodes": [\r
+ {\r
+ "name": "notmuch",\r
+ "percent": 0.5,\r
+ "type": "con",\r
+ "swallows": [\r
+ {\r
+ "class": "^Emacs$",\r
+ "instance": "^notmuch$"\r
+ }\r
+ ]\r
+ },\r
+ {\r
+ "name": "midna: ~",\r
+ "percent": 0.5,\r
+ "type": "con"\r
+ }\r
+ ]\r
+ }\r
+ ]\r
+}\r
+\r
+{\r
+ // stacked split container with 1 children\r
+ "layout": "stacked",\r
+ "percent": 0.6,\r
+ "type": "con",\r
+ "nodes": [\r
+ {\r
+ "name": "chrome",\r
+ "type": "con",\r
+ "swallows": [\r
+ {\r
+ "class": "^Google-chrome$"\r
+ }\r
+ ]\r
+ }\r
+ ]\r
+}</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>In this layout, the screen is divided into two columns. In the left column,\r
+which covers 40% of the screen, there is a terminal emulator running irssi on\r
+the top, and a stacked split container with an Emacs window and a terminal\r
+emulator on the bottom. In the right column, there is a stacked container with\r
+a Chrome window:</p></div>\r
+<div class="paragraph"><p><span class="image">\r
+<a class="image" href="layout-saving-1.png">\r
+<img src="layout-saving-1.png" alt="Restored layout" width="400" />\r
+</a>\r
+</span></p></div>\r
+<div class="paragraph"><p>The structure of this JSON file looks a lot like the <tt>TREE</tt> reply, see\r
+<a href="http://build.i3wm.org/docs/ipc.html#_tree_reply">http://build.i3wm.org/docs/ipc.html#_tree_reply</a> for documentation on that. Some\r
+properties are excluded because they are not relevant when restoring a layout.</p></div>\r
+<div class="paragraph"><p>Most importantly, look at the "swallows" section of each window. This is where\r
+you need to be more or less specific. As an example, remember the section about\r
+the Emacs window:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>"swallows": [\r
+ {\r
+ "class": "^Emacs$",\r
+ "instance": "^notmuch$"\r
+ }\r
+]</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Here you can see that i3 will require both the class and the instance to match.\r
+Therefore, if you just start Emacs via dmenu, it will not get swallowed by that\r
+container. Only if you start Emacs with the proper instance name (<tt>emacs24\r
+--name notmuch</tt>), it will get swallowed.</p></div>\r
+<div class="paragraph"><p>You can match on "class", "instance", "window_role" and "title". All values are\r
+case-sensitive regular expressions (PCRE). Use <tt>xprop(1)</tt> and click into a\r
+window to see its properties:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ xprop\r
+WM_WINDOW_ROLE(STRING) = "gimp-toolbox-color-dialog"\r
+WM_CLASS(STRING) = "gimp-2.8", "Gimp-2.8"\r
+_NET_WM_NAME(UTF8_STRING) = "Change Foreground Color"</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>The first part of <tt>WM_CLASS</tt> is the "instance" (gimp-2.8 in this case), the\r
+second part is the "class" (Gimp-2.8 in this case). "title" matches against\r
+<tt>_NET_WM_NAME</tt> and "window_role" matches against <tt>WM_WINDOW_ROLE</tt>.</p></div>\r
+<div class="paragraph"><p>In general, you should try to be as specific as possible in your swallow\r
+criteria. Try to use criteria that match one window and only one window, to\r
+have a reliable startup procedure.</p></div>\r
+<div class="paragraph"><p>If you specify multiple swallow criteria, the placeholder will be replaced by\r
+the window which matches any of the criteria. As an example:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>// Matches either Emacs or Gvim, whichever one is started first.\r
+"swallows": [\r
+ {"class": "^Emacs$"},\r
+ {"class": "^Gvim$"}\r
+]</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_json_standard_non_compliance">3.2. JSON standard non-compliance</h3>\r
+<div class="paragraph"><p>A layout file as generated by <tt>i3-save-tree(1)</tt> is not strictly valid JSON:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+Layout files contain multiple “JSON documents” on the top level, whereas the\r
+ JSON standard only allows precisely one “document” (array or hash).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Layout files contain comments which are not standardized, but understood by\r
+ many parsers.\r
+</p>\r
+</li>\r
+</ol></div>\r
+<div class="paragraph"><p>Both deviations from the JSON standard are to make manual editing by humans\r
+easier. In case you are writing a more elaborate tool for manipulating these\r
+layouts, you can either use a JSON parser that supports these deviations (for\r
+example libyajl), transform the layout file to a JSON-conforming file, or\r
+<a href="http://cr.i3wm.org/">submit a patch</a> to make <tt>i3-save-tree(1)</tt> optionally\r
+output standard-conforming JSON.</p></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_troubleshooting">4. Troubleshooting</h2>\r
+<div class="sectionbody">\r
+<div class="sect2">\r
+<h3 id="_restoring_a_vertically_split_workspace">4.1. Restoring a vertically split workspace</h3>\r
+<div class="paragraph"><p>When using <tt>i3-save-tree</tt> with the <tt>--workspace</tt> switch, only the <strong>contents</strong> of\r
+the workspace will be dumped. This means that properties of the workspace\r
+itself will be lost.</p></div>\r
+<div class="paragraph"><p>This is relevant for, e.g., a vertically split container as the base container of\r
+a workspace. Since the split mode is a property of the workspace, it will not be\r
+stored. In this case, you will have to manually wrap your layout in such a\r
+container:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>// vim:ts=4:sw=4:et\r
+{\r
+ // this is a manually added container to restore the vertical split\r
+ "layout": "splitv",\r
+ "percent": 0.5,\r
+ "type": "con",\r
+ "nodes": [\r
+\r
+ // the dumped workspace layout goes here\r
+\r
+ ]\r
+}</tt></pre>\r
+</div></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
+</div>\r
+</body>\r
+</html>\r
projects / i3 / i3.github.io / blobdiff