<h1>i3 User’s Guide</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
+<span id="revdate">August 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>
</p>\r
</dd>\r
</dl></div>\r
-<div class="paragraph"><p>To switch modes, press <tt>mod+e</tt> for default, <tt>mod+h</tt> for stacking and\r
+<div class="paragraph"><p>To switch modes, press <tt>mod+e</tt> for default, <tt>mod+s</tt> for stacking and\r
<tt>mod+w</tt> for tabbed.</p></div>\r
<div class="paragraph"><p><span class="image">\r
<img src="modes.png" alt="Container modes" />\r
paradigm but can be useful for some corner cases like "Save as" dialog\r
windows, or toolbar windows (GIMP or similar). Those windows usually set the\r
appropriate hint and are opened in floating mode by default.</p></div>\r
-<div class="paragraph"><p>You can enable floating mode for a window by pressing <tt>mod+Shift+Space</tt>. By\r
+<div class="paragraph"><p>You can toggle floating mode for a window by pressing <tt>mod+Shift+Space</tt>. By\r
dragging the window’s titlebar with your mouse you can move the window\r
around. By grabbing the borders and moving them you can resize the window. You\r
can also do that by using the <a href="#floating_modifier">[floating_modifier]</a>.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>new_window <normal|1pixel|borderless></tt></pre>\r
+<pre><tt>new_window <normal|1pixel|none></tt></pre>\r
</div></div>\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
<div class="listingblock">\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt># enable floating mode for all XTerm windows\r
-for_window [class="XTerm"] mode floating\r
+for_window [class="XTerm"] floating enable\r
\r
# Make all urxvts use a 1-pixel border:\r
for_window [class="urxvt"] border 1pixel\r
# A less useful, but rather funny example:\r
# makes the window floating as soon as I change\r
# directory to ~/work\r
-for_window [title="x200: ~/work"] mode floating</tt></pre>\r
+for_window [title="x200: ~/work"] floating enable</tt></pre>\r
</div></div>\r
+<div class="paragraph"><p>The valid criteria are the same as those for commands, see <a href="#command_criteria">[command_criteria]</a>.</p></div>\r
</div>\r
<div class="sect2">\r
<h3 id="_variables">4.9. Variables</h3>\r
terminal program’s background color to avoid black gaps between the rendered\r
area of the termianal and the i3 border.</p></div>\r
<div class="paragraph"><p>Colors are in HTML hex format (#rrggbb), see the following example:</p></div>\r
-<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
+<div class="paragraph"><p><strong>Examples (default colors)</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt># class border backgr. text\r
-client.focused #2F343A #900000 #FFFFFF</tt></pre>\r
+<pre><tt># class border backgr. text\r
+client.focused #4c7899 #285577 #ffffff\r
+client.focused_inactive #333333 #5f676a #ffffff\r
+client.unfocused #333333 #222222 #888888\r
+client.urgent #2f343a #900000 #ffffff</tt></pre>\r
</div></div>\r
<div class="paragraph"><p>Note that for the window decorations, the color around the child window is the\r
background color, and the border color is only the two thin lines at the top of\r
<tt>/tmp/i3-%u/ipc-socket.%p</tt> where <tt>%u</tt> is your UNIX username and <tt>%p</tt> is the PID\r
of i3.</p></div>\r
<div class="paragraph"><p>You can override the default path through the environment-variable <tt>I3SOCK</tt> or\r
-by specifying the <tt>ipc-socket</tt> directive.</p></div>\r
+by specifying the <tt>ipc-socket</tt> directive. This is discouraged, though, since i3\r
+does the right thing by default.</p></div>\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>popup_during_fullscreen ignore</tt></pre>\r
</div></div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_focus_wrapping">4.17. Focus wrapping</h3>\r
+<div class="paragraph"><p>When being in a tabbed or stacked container, the first container will be\r
+focused when you use <tt>focus down</tt> on the last container — the focus wraps. If\r
+however there is another stacked/tabbed container in that direction, focus will\r
+be set on that container. This is the default behaviour so you can navigate to\r
+all your windows without having to use <tt>focus parent</tt>.</p></div>\r
+<div class="paragraph"><p>If you want the focus to <strong>always</strong> wrap and you are aware of using <tt>focus\r
+parent</tt> to switch to different containers, you can use the\r
+<tt>force_focus_wrapping</tt> configuration directive. After enabling it, the focus\r
+will always wrap.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>force_focus_wrapping <yes|no></tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>force_focus_wrapping yes</tt></pre>\r
+</div></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
<h2 id="_list_of_commands">5. List of commands</h2>\r
<div class="sectionbody">\r
+<div class="paragraph"><p>Commands are what you bind to specific keypresses. You can also issue commands\r
+at runtime without pressing a key by using the IPC interface. An easy way to\r
+do this is to use the <tt>i3-msg</tt> utility:</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt># execute this on your shell to make the current container borderless\r
+i3-msg border none</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Commands can be chained by using <tt>;</tt> (a semicolon). So, to move a window to a\r
+specific workspace and immediately switch to that workspace, you can configure\r
+the following keybinding:</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>bindsym mod+x move workspace 3; workspace 3</tt></pre>\r
+</div></div>\r
+<div class="paragraph" id="command_criteria"><p>Furthermore, you can change the scope of a command, that is, which containers\r
+should be affected by that command, by using various criteria. These are\r
+prefixed in square brackets to every command. If you want to kill all windows\r
+which have the class Firefox, use:</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>bindsym mod+x [class="Firefox"] kill</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>The criteria which are currently implemented are:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+class\r
+</dt>\r
+<dd>\r
+<p>\r
+ Compares the window class (the second part of WM_CLASS)\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+instance\r
+</dt>\r
+<dd>\r
+<p>\r
+ Compares the window instance (the first part of WM_CLASS)\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+id\r
+</dt>\r
+<dd>\r
+<p>\r
+ Compares the X11 window ID, which you can get via <tt>xwininfo</tt> for example.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+title\r
+</dt>\r
+<dd>\r
+<p>\r
+ Compares the X11 window title (_NET_WM_NAME or WM_NAME as fallback).\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+mark\r
+</dt>\r
+<dd>\r
+<p>\r
+ Compares the mark set for this container, see <a href="#vim_like_marks">[vim_like_marks]</a>.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+con_id\r
+</dt>\r
+<dd>\r
+<p>\r
+ Compares the i3-internal container ID, which you can get via the IPC\r
+ interface. Handy for scripting.\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p>Note that currently all criteria are compared case-insensitive and do not\r
+support regular expressions. This is planned to change in the future.</p></div>\r
<div class="sect2">\r
<h3 id="_splitting_containers">5.1. Splitting containers</h3>\r
<div class="paragraph"><p>The split command makes the current window a split container. Split containers\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>split vertical</tt></pre>\r
+<pre><tt>bindsym mod+v split vertical\r
+bindsym mod+h split horizontal</tt></pre>\r
</div></div>\r
</div>\r
<div class="sect2">\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_changing_workspaces_moving_containers_to_workspaces">5.4. Changing workspaces/moving containers to workspaces</h3>\r
+<h3 id="_changing_named_workspaces_moving_to_workspaces">5.4. Changing (named) workspaces/moving to workspaces</h3>\r
<div class="paragraph"><p>To change to a specific workspace, use the <tt>workspace</tt> command, followed by the\r
number or name of the workspace. To move containers to specific workspaces, use\r
<tt>move workspace</tt>.</p></div>\r
<tt>workspace next</tt> and <tt>workspace prev</tt>, which is handy, for example, if you have\r
workspace 1, 3, 4 and 9 and you want to cycle through them with a single key\r
combination.</p></div>\r
+<div class="paragraph"><p>To move a container to another xrandr output such as <tt>LVDS1</tt> or <tt>VGA1</tt>, you can\r
+use the <tt>move output</tt> command followed by the name of the target output. You\r
+may also use <tt>left</tt>, <tt>right</tt>, <tt>up</tt>, <tt>down</tt> instead of the xrandr output name to\r
+move to the the next output in the specified direction.</p></div>\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
bindsym mod+Shift+2 move workspace 2\r
...</tt></pre>\r
</div></div>\r
+<div class="sect3">\r
+<h4 id="_named_workspaces">5.4.1. Named workspaces</h4>\r
+<div class="paragraph"><p>Workspaces are identified by their name. So, instead of using numbers in the\r
+workspace command, you can use an arbitrary name:</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>bindsym mod+1 workspace mail\r
+...</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>If you want the workspace to have a number <strong>and</strong> a name, just prefix the\r
+number, like this:</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>bindsym mod+1 workspace 1: mail\r
+bindsym mod+2 workspace 2: www\r
+...</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Note that the workspace will really be named "1: mail". i3 treats workspace\r
+names beginning with a number in a slightly special way. Normally, named\r
+workspaces are ordered the way they appeared. When they start with a number, i3\r
+will order them numerically.</p></div>\r
+</div>\r
</div>\r
<div class="sect2">\r
<h3 id="resizingconfig">5.5. Resizing containers/windows</h3>\r
<div class="paragraph"><p>If you want to resize containers/windows using your keyboard, you can use the\r
-<tt>resize</tt> command, I recommend using it inside a so called <tt>mode</tt>:</p></div>\r
+<tt>resize</tt> command:</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>resize <grow|shrink> <direction> [<px> px] [or <ppt> ppt]</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Direction can be one of <tt>up</tt>, <tt>down</tt>, <tt>left</tt> or <tt>right</tt>. The optional pixel\r
+argument specifies by how many pixels a <strong>floating container</strong> should be grown or\r
+shrinked (the default is 10 pixels). The ppt argument means percentage points\r
+and specifies by how many percentage points a <strong>tiling container</strong> should be\r
+grown or shrinked (the default is 10 percentage points).</p></div>\r
+<div class="paragraph"><p>I recommend using the resize command inside a so called <tt>mode</tt>:</p></div>\r
<div class="listingblock">\r
<div class="title">Example: Configuration file, defining a mode for resizing</div>\r
<div class="content">\r
bindsym j resize shrink left\r
bindsym Shift+j resize grow left\r
\r
- bindsym k resize grow bottom\r
- bindsym Shift+k resize shrink bottom\r
+ bindsym k resize grow down\r
+ bindsym Shift+k resize shrink down\r
\r
- bindsym l resize shrink top\r
- bindsym Shift+l resize grow top\r
+ bindsym l resize shrink up\r
+ bindsym Shift+l resize grow up\r
\r
bindsym semicolon resize grow right\r
bindsym Shift+semicolon resize shrink right\r
\r
- bindcode 36 mode default\r
+ # back to normal: Enter or Escape\r
+ bindsym Return mode "default"\r
+ bindsym Escape mode "default"\r
}\r
\r
# Enter resize mode\r
projects / i3 / i3.github.io / blobdiff