--- /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.10" />\r
+<title>i3: External workspace bars</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>External workspace bars</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 2013</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>i3 comes with i3bar by default, a simple bar that is sufficient for most users.\r
+In case you are unhappy with it, this document explains how to use a different,\r
+external workspace bar. Note that we do not provide support for external\r
+programs.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_internal_and_external_bars">1. Internal and external bars</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>The internal workspace bar of i3 is meant to be a reasonable default so that\r
+you can use i3 without having too much hassle when setting it up. It is quite\r
+simple and intended to stay this way.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_dock_mode">2. dock mode</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>You typically want to see the same workspace bar on every workspace on a\r
+specific screen. Also, you don’t want to place the workspace bar somewhere\r
+in your layout by hand. This is where dock mode comes in: When a program sets\r
+the appropriate hint (_NET_WM_WINDOW_TYPE_DOCK), it will be managed in dock\r
+mode by i3. That means it will be placed at the bottom or top of the screen\r
+(while other edges of the screen are possible in the NetWM standard, this is\r
+not yet implemented in i3), it will not overlap any other window and it will be\r
+on every workspace for the specific screen it was placed on initially.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_the_ipc_interface">3. The IPC interface</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>In the context of using an external workspace bar, the IPC interface needs to\r
+provide the bar program with the current workspaces and output (as in VGA-1,\r
+LVDS-1, …) configuration. In the other direction, the program has to be able\r
+to switch to specific workspaces.</p></div>\r
+<div class="paragraph"><p>By default, the IPC interface is enabled and you can get the path to the socket\r
+by calling <tt>i3 --get-socketpath</tt>.</p></div>\r
+<div class="paragraph"><p>To learn more about the protocol which is used for IPC, see <tt>docs/ipc</tt>.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_output_changes_on_the_fly">4. Output changes (on-the-fly)</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>i3 implements the RandR API and can handle changing outputs quite well. So, an\r
+external workspace bar implementation needs to make sure that when you change\r
+the resolution of any of your screens (or enable/disable an output), the bars\r
+will be adjusted properly.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_i3_wsbar_an_example_implementation">5. i3-wsbar, an example implementation</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p><tt>i3-wsbar</tt> used to be the reference implementation before we had <tt>i3bar</tt>.\r
+Nowadays, it is not shipped with release tarballs, but you can still get it at\r
+<a href="https://github.com/i3/i3/blob/next/contrib/i3-wsbar">https://github.com/i3/i3/blob/next/contrib/i3-wsbar</a></p></div>\r
+<div class="sect2">\r
+<h3 id="_the_big_picture">5.1. The big picture</h3>\r
+<div class="paragraph"><p>The most common reason to use an external workspace bar is to integrate system\r
+information such as what <tt>i3status</tt> or <tt>conky</tt> provide into the workspace bar.\r
+So, we have <tt>i3status</tt> or a similar program, which only provides\r
+text output (formatted in some way). To display this text nicely on the screen,\r
+there are programs such as dzen2, xmobar and similar. We will stick to dzen2\r
+from here on. So, we have the output of i3status, which needs to go into dzen2\r
+somehow. But we also want to display the list of workspaces. <tt>i3-wsbar</tt> takes\r
+input on stdin, combines it with a formatted workspace list and pipes it to\r
+dzen2.</p></div>\r
+<div class="paragraph"><p>Please note that <tt>i3-wsbar</tt> does not print its output to stdout. Instead, it\r
+launches the dzen2 instances on its own. This is necessary to handle changes\r
+in the available outputs (to place a new dzen2 on a new screen for example).</p></div>\r
+<div class="paragraph"><p><span class="image">\r
+<a class="image" href="wsbar.png">\r
+<img src="wsbar.png" alt="Overview" />\r
+</a>\r
+</span></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_running_i3_wsbar">5.2. Running i3-wsbar</h3>\r
+<div class="paragraph"><p>The most simple usage of i3-wsbar looks like this:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>i3-wsbar -c "dzen2 -x %x -dock"</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>The <tt>%x</tt> in the command name will be replaced by the X position of the output\r
+for which this workspace bar is running. i3 will automatically place the\r
+workspace bar on the correct output when dzen2 is started in dock mode. The\r
+bar which you will see should look exactly like the internal bar of i3.</p></div>\r
+<div class="paragraph"><p>To actually get a benefit, you want to give <tt>i3-wsbar</tt> some input:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>i3status | i3-wsbar -c "dzen2 -x %x -dock"</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