i3 User’s Guide
===============
Michael Stapelberg <michael+i3@stapelberg.de>
-July 2011
-
-*********************************************************************************
-This document is not yet finished. The tree branch is still in development. The
-information provided here should be correct, just not complete yet.
-*********************************************************************************
+August 2011
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
question(s) on the mailing list.
-//////////////////////////////////////////////////////////////////////////////
== Default keybindings
For the "too long; didn’t read" people, here is an overview of the default
image:keyboard-layer2.png["Keys to use with Shift+mod",width=600,link="keyboard-layer2.png"]
-As i3 uses keycodes in the default configuration, it does not matter which
-keyboard layout you actually use. The key positions are what matters (of course
-you can also use keysymbols, see <<keybindings>>).
-
The red keys are the modifiers you need to press (by default), the blue keys
are your homerow.
-//////////////////////////////////////////////////////////////////////////////
== Using i3
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+h+ for stacking and
+To switch modes, press +mod+e+ for default, +mod+s+ for stacking and
+mod+w+ for tabbed.
image:modes.png[Container modes]
*Examples*:
------------------------------------------------
# enable floating mode for all XTerm windows
-for_window [class="XTerm"] mode floating
+for_window [class="XTerm"] floating enable
# Make all urxvts use a 1-pixel border:
for_window [class="urxvt"] border 1pixel
# A less useful, but rather funny example:
# makes the window floating as soon as I change
# directory to ~/work
-for_window [title="x200: ~/work"] mode floating
+for_window [title="x200: ~/work"] floating enable
------------------------------------------------
=== Variables
*Examples*:
--------------------------------
-exec i3status | dzen2 -dock
+exec i3status | i3bar -d
exec_always ~/my_script.sh
--------------------------------
A client which is not the focused one of its container.
client.urgent::
A client which has its urgency hint activated.
-bar.focused::
- The current workspace in the bottom bar.
-bar.unfocused::
- All other workspaces in the bottom bar.
-bar.urgent::
- A workspace which has at least one client with an activated urgency hint.
You can also specify the color to be used to paint the background of the client
windows. This color will be used to paint the window on top of which the client
Colors are in HTML hex format (#rrggbb), see the following example:
-*Examples*:
---------------------------------------
-# class border backgr. text
-client.focused #2F343A #900000 #FFFFFF
---------------------------------------
+*Examples (default colors)*:
+-----------------------------------------------
+# class border backgr. text
+client.focused #4c7899 #285577 #ffffff
+client.focused_inactive #333333 #5f676a #ffffff
+client.unfocused #333333 #222222 #888888
+client.urgent #2f343a #900000 #ffffff
+-----------------------------------------------
Note that for the window decorations, the color around the child window is the
background color, and the border color is only the two thin lines at the top of
of i3.
You can override the default path through the environment-variable +I3SOCK+ or
-by specifying the +ipc-socket+ directive.
+by specifying the +ipc-socket+ directive. This is discouraged, though, since i3
+does the right thing by default.
*Examples*:
----------------------------
popup_during_fullscreen ignore
------------------------------
+=== Focus wrapping
+
+When being in a tabbed or stacked container, the first container will be
+focused when you use +focus down+ on the last container -- the focus wraps. If
+however there is another stacked/tabbed container in that direction, focus will
+be set on that container. This is the default behaviour so you can navigate to
+all your windows without having to use +focus parent+.
+
+If you want the focus to *always* wrap and you are aware of using +focus
+parent+ to switch to different containers, you can use the
++force_focus_wrapping+ configuration directive. After enabling it, the focus
+will always wrap.
+
+*Syntax*:
+-----------------------------
+force_focus_wrapping <yes|no>
+-----------------------------
+
+*Example*:
+------------------------
+force_focus_wrapping yes
+------------------------
+
== List of commands
=== Splitting containers
---------------------------
*Example*:
---------------
-split vertical
---------------
+------------------------------
+bindsym mod+v split vertical
+bindsym mod+h split horizontal
+------------------------------
=== Manipulating layout
bindsym mod+semicolon move right
----------------------
-=== Changing workspaces/moving containers to workspaces
+=== Changing (named) workspaces/moving to workspaces
To change to a specific workspace, use the +workspace+ command, followed by the
number or name of the workspace. To move containers to specific workspaces, use
workspace 1, 3, 4 and 9 and you want to cycle through them with a single key
combination.
+To move a container to another xrandr output such as +LVDS1+ or +VGA1+, you can
+use the +move output+ command followed by the name of the target output. You
+may also use +left+, +right+, +up+, +down+ instead of the xrandr output name to
+move to the the next output in the specified direction.
+
*Examples*:
-------------------------
bindsym mod+1 workspace 1
...
-------------------------
+==== Named workspaces
+
+Workspaces are identified by their name. So, instead of using numbers in the
+workspace command, you can use an arbitrary name:
+
+*Example*:
+-------------------------
+bindsym mod+1 workspace mail
+...
+-------------------------
+
+If you want the workspace to have a number *and* a name, just prefix the
+number, like this:
+
+*Example*:
+-------------------------
+bindsym mod+1 workspace 1: mail
+bindsym mod+2 workspace 2: www
+...
+-------------------------
+
+Note that the workspace will really be named "1: mail". i3 treats workspace
+names beginning with a number in a slightly special way. Normally, named
+workspaces are ordered the way they appeared. When they start with a number, i3
+will order them numerically.
+
[[resizingconfig]]
=== Resizing containers/windows
bindsym j resize shrink left
bindsym Shift+j resize grow left
- bindsym k resize grow bottom
- bindsym Shift+k resize shrink bottom
+ bindsym k resize grow down
+ bindsym Shift+k resize shrink down
- bindsym l resize shrink top
- bindsym Shift+l resize grow top
+ bindsym l resize shrink up
+ bindsym Shift+l resize grow up
bindsym semicolon resize grow right
bindsym Shift+semicolon resize shrink right
projects / i3 / i3 / blobdiff