i3 User’s Guide
===============
-Michael Stapelberg <michael+i3@stapelberg.de>
-April 2012
+Michael Stapelberg <michael@i3wm.org>
+August 2012
This document contains all the information you need to configure and use the i3
window manager. If it does not, please contact us on IRC (preferred) or post your
A split container can have one of the following layouts:
-default::
+splith/splitv::
Windows are sized so that every window gets an equal amount of space in the
-container.
+container. splith distributes the windows horizontally (windows are right next
+to each other), splitv distributes them vertically (windows are on top of each
+other).
stacking::
Only the focused window in the container is displayed. You get a list of
windows at the top of the container.
The same principle as +stacking+, but the list of windows at the top is only
a single line which is vertically split.
-To switch modes, press +mod+e+ for default, +mod+s+ for stacking and
-+mod+w+ for tabbed.
+To switch modes, press +mod+e+ for splith/splitv (it toggles), +mod+s+ for
+stacking and +mod+w+ for tabbed.
image:modes.png[Container modes]
It is only natural to use so-called +Split Containers+ in order to build a
layout when using a tree as data structure. In i3, every +Container+ has an
-orientation (horizontal, vertical or unspecified). So, in our example with the
-workspace, the default orientation of the workspace +Container+ is horizontal
-(most monitors are widescreen nowadays). If you change the orientation to
-vertical (+mod+v+ in the default config) and *then* open two terminals, i3 will
-configure your windows like this:
+orientation (horizontal, vertical or unspecified) and the orientation depends
+on the layout the container is in (vertical for splitv and stacking, horizontal
+for splith and tabbed). So, in our example with the workspace, the default
+layout of the workspace +Container+ is splith (most monitors are widescreen
+nowadays). If you change the layout to splitv (+mod+l+ in the default config)
+and *then* open two terminals, i3 will configure your windows like this:
image::tree-shot2.png["shot2",title="Vertical Workspace Orientation"]
-An interesting new feature of the tree branch is the ability to split anything:
-Let’s assume you have two terminals on a workspace (with horizontal
-orientation), focus is on the right terminal. Now you want to open another
-terminal window below the current one. If you would just open a new terminal
-window, it would show up to the right due to the horizontal workspace
-orientation. Instead, press +mod+v+ to create a +Vertical Split Container+ (to
+An interesting new feature of i3 since version 4 is the ability to split anything:
+Let’s assume you have two terminals on a workspace (with splith layout, that is
+horizontal orientation), focus is on the right terminal. Now you want to open
+another terminal window below the current one. If you would just open a new
+terminal window, it would show up to the right due to the splith layout.
+Instead, press +mod+v+ to split the container with the splitv layout (to
open a +Horizontal Split Container+, use +mod+h+). Now you can open a new
terminal and it will open below the current one:
image::tree-shot3.png["shot3",title="Focus parent, then open new terminal"]
+=== Implicit containers
+
+In some cases, i3 needs to implicitly create a container to fulfill your
+command.
+
+One example is the following scenario: You start i3 with a single monitor and a
+single workspace on which you open three terminal windows. All these terminal
+windows are directly attached to one node inside i3’s layout tree, the
+workspace node. By default, the workspace node’s orientation is +horizontal+.
+
+Now you move one of these terminals down (+mod+k+ by default). The workspace
+node’s orientation will be changed to +vertical+. The terminal window you moved
+down is directly attached to the workspace and appears on the bottom of the
+screen. A new (horizontal) container was created to accomodate the other two
+terminal windows. You will notice this when switching to tabbed mode (for
+example). You would end up having one tab called "another container" and the
+other one being the terminal window you moved down.
+
[[configuring]]
== Configuring i3
# This is a comment
-------------------
+[[fonts]]
+
=== Fonts
-i3 uses X core fonts (not Xft) for rendering window titles. You can use
-+xfontsel(1)+ to generate such a font description. To see special characters
-(Unicode), you need to use a font which supports the ISO-10646 encoding.
+i3 has support for both X core fonts and FreeType fonts (through Pango) to
+render window titles.
+
+To generate an X core font description, you can use +xfontsel(1)+. To see
+special characters (Unicode), you need to use a font which supports the
+ISO-10646 encoding.
+
+A FreeType font description is composed by a font family, a style, a weight,
+a variant, a stretch and a size.
+FreeType fonts support right-to-left rendering and contain often more
+Unicode glyphs than X core fonts.
If i3 cannot open the configured font, it will output an error in the logfile
and fall back to a working font.
*Syntax*:
------------------------------
font <X core font description>
+font xft:<a FreeType font description>
------------------------------
*Examples*:
--------------------------------------------------------------
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+font xft:DejaVu Sans Mono 10
--------------------------------------------------------------
[[keybindings]]
=== Border style for new windows
-This option determines which border style new windows will have.
+This option determines which border style new windows will have. The default is
+"normal".
*Syntax*:
---------------------------------------------
new_window 1pixel
---------------------
+=== Hiding vertical borders
+
+You can hide vertical borders adjacent to the screen edges using
++hide_edge_borders+. This is useful if you are using scrollbars, or do not want
+to waste even two pixels in displayspace. Default is none.
+
+*Syntax*:
+----------------------------
+hide_edge_borders <none|vertical|horizontal|both>
+----------------------------
+
+*Example*:
+----------------------
+hide_edge_borders vertical
+----------------------
+
=== Arbitrary commands for specific windows (for_window)
With the +for_window+ command, you can let i3 execute any command when it
=== Focus follows mouse
-If you have a setup where your mouse usually is in your way (like a touchpad
-on your laptop which you do not want to disable completely), you might want
-to disable 'focus follows mouse' and control focus only by using your keyboard.
-The mouse will still be useful inside the currently active window (for example
-to click on links in your browser window).
+By default, window focus follows your mouse movements. However, if you have a
+setup where your mouse usually is in your way (like a touchpad on your laptop
+which you do not want to disable completely), you might want to disable 'focus
+follows mouse' and control focus only by using your keyboard. The mouse will
+still be useful inside the currently active window (for example to click on
+links in your browser window).
*Syntax*:
----------------------------
=== Font
-Specifies the font (again, X core font, not Xft, just like in i3) to be used in
-the bar.
+Specifies the font to be used in the bar. See <<fonts>>.
*Syntax*:
---------------------
--------------------------------------------------------------
bar {
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+ font xft:DejaVu Sans Mono 10
}
--------------------------------------------------------------
=== Splitting containers
The split command makes the current window a split container. Split containers
-can contain multiple windows. Every split container has an orientation, it is
-either split horizontally (a new window gets placed to the right of the current
-one) or vertically (a new window gets placed below the current one).
+can contain multiple windows. Depending on the layout of the split container,
+new windows get placed to the right of the current one (splith) or new windows
+get placed below the current one (splitv).
If you apply this command to a split container with the same orientation,
nothing will happen. If you use a different orientation, the split container’s
-orientation will be changed (if it does not have more than one window).
+orientation will be changed (if it does not have more than one window). Use
++layout toggle split+ to change the layout of any split container from splitv
+to splith or vice-versa.
*Syntax*:
---------------------------
=== Manipulating layout
-Use +layout default+, +layout stacking+ or +layout tabbed+ to change the
-current container layout to default, stacking or tabbed layout, respectively.
+Use +layout toggle split+, +layout stacking+ or +layout tabbed+ to change the
+current container layout to splith/splitv, stacking or tabbed layout,
+respectively.
To make the current window (!) fullscreen, use +fullscreen+, to make
it floating (or tiling again) use +floating enable+ respectively +floating disable+
(or +floating toggle+):
+*Syntax*:
+--------------
+layout <tabbed|stacking>
+layout toggle [split|all]
+--------------
+
*Examples*:
--------------
bindsym mod+s layout stacking
-bindsym mod+l layout default
+bindsym mod+l layout toggle split
bindsym mod+w layout tabbed
+# Toggle between stacking/tabbed/split:
+bindsym mod+x layout toggle
+
+# Toggle between stacking/tabbed/splith/splitv:
+bindsym mod+x layout toggle all
+
# Toggle fullscreen
bindsym mod+f fullscreen
projects / i3 / i3 / blobdiff