From 8ef51a7cfa42668c13d94842197dda4d28522369 Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Thu, 28 Jul 2011 22:51:34 +0200 Subject: [PATCH] update docs/userguide (various little fixes/updates) --- docs/userguide | 193 ++++++++++++++++++++++++++----------------------- 1 file changed, 103 insertions(+), 90 deletions(-) diff --git a/docs/userguide b/docs/userguide index 451162fb..0c9ad600 100644 --- a/docs/userguide +++ b/docs/userguide @@ -1,7 +1,7 @@ i3 User’s Guide =============== Michael Stapelberg -May 2011 +July 2011 ********************************************************************************* This document is not yet finished. The tree branch is still in development. The @@ -18,13 +18,13 @@ question(s) on the mailing list. For the "too long; didn’t read" people, here is an overview of the default keybindings (click to see the full size image): -*Keys to use with Mod1 (alt):* +*Keys to use with mod (alt):* -image:keyboard-layer1.png["Keys to use with Mod1 (alt)",width=600,link="keyboard-layer1.png"] +image:keyboard-layer1.png["Keys to use with mod (alt)",width=600,link="keyboard-layer1.png"] -*Keys to use with Shift+Mod1:* +*Keys to use with Shift+mod:* -image:keyboard-layer2.png["Keys to use with Shift+Mod1",width=600,link="keyboard-layer2.png"] +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 @@ -37,13 +37,13 @@ are your homerow. == Using i3 Throughout this guide, the keyword +mod+ will be used to refer to the -configured modifier. This is the windows key (mod4) by default, with alt (mod1) +configured modifier. This is the alt key (Mod1) by default, with windows (Mod4) being a popular alternative. === Opening terminals and moving around One very basic operation is opening a new terminal. By default, the keybinding -for this is mod+Enter, that is Win+Enter in the default configuration. By +for this is mod+Enter, that is Alt+Enter in the default configuration. By pressing mod+Enter, a new terminal will be opened. It will fill the whole space available on your screen. @@ -61,7 +61,7 @@ you may know from the editor +vi+. However, in i3, your homerow is used for these keys (in +vi+, the keys are shifted to the left by one for compatibility with most keyboard layouts). Therefore, +mod+J+ is left, +mod+K+ is down, +mod+L+ is up and `mod+;` is right. So, to switch between the terminals, -use +mod+K+ or +mod+L+. +use +mod+K+ or +mod+L+. Of course, you can also use the arrow keys. At the moment, your workspace is split (it contains two terminals) in a specific direction (horizontal by default). Every window can be split @@ -75,9 +75,9 @@ TODO: picture of the tree To split a window vertically, press +mod+v+. To split it horizontally, press +mod+h+. -=== Changing container modes +=== Changing the container layout -A container can have the following modes: +A split container can have one of the following layouts: default:: Windows are sized so that every window gets an equal amount of space in the @@ -89,15 +89,15 @@ tabbed:: 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 +Mod1+e+ for default, +Mod1+h+ for stacking and -+Mod1+w+ for tabbed. +To switch modes, press +mod+e+ for default, +mod+h+ for stacking and ++mod+w+ for tabbed. image:modes.png[Container modes] === Toggling fullscreen mode for a window -To display a window fullscreen or to go out of fullscreen mode again, press -+mod+f+. +To display a window in fullscreen mode or to go out of fullscreen mode again, +press +mod+f+. There is also a global fullscreen mode in i3 in which the client will use all available outputs. @@ -105,19 +105,19 @@ available outputs. === Opening other applications Aside from opening applications from a terminal, you can also use the handy -+dmenu+ which is opened by pressing +mod+p+ by default. Just type the name -(or a part of it) of the application which you want to open. The application -typed has to be in your +$PATH+ for this to work. ++dmenu+ which is opened by pressing +mod+d+ by default. Just type the name +(or a part of it) of the application which you want to open. The corresponding +application has to be in your +$PATH+ for this to work. Additionally, if you have applications you open very frequently, you can create a keybinding for starting the application directly. See the section -"Configuring i3" for details. +<> for details. === Closing windows If an application does not provide a mechanism for closing (most applications provide a menu, the escape key or a shortcut like +Control+W+ to close), you -can press +Mod1+Shift+q+ to kill a window. For applications which support +can press +mod+Shift+q+ to kill a window. For applications which support the WM_DELETE protocol, this will correctly close the application (saving any modifications or doing other cleanup). If the application doesn’t support the WM_DELETE protocol your X server will kill the window and the behaviour @@ -182,13 +182,12 @@ Floating windows are always on top of tiling windows. == Tree -The most important change and reason for the name is that i3 stores all -information about the X11 outputs, workspaces and layout of the windows on them -in a tree. The root node is the X11 root window, followed by the X11 outputs, -then workspaces and finally the windows themselve. In previous versions of i3 -we had multiple lists (of outputs, workspaces) and a table for each workspace. -That approach turned out to be complicated to use (snapping), understand and -implement. +i3 stores all information about the X11 outputs, workspaces and layout of the +windows on them in a tree. The root node is the X11 root window, followed by +the X11 outputs, then dock areas and a content container, then workspaces and +finally the windows themselve. In previous versions of i3 we had multiple lists +(of outputs, workspaces) and a table for each workspace. That approach turned +out to be complicated to use (snapping), understand and implement. === The tree consists of Containers @@ -211,7 +210,7 @@ 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 (+Alt+v+ in the default config) and *then* open two terminals, i3 will +vertical (+mod+v+ 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"] @@ -221,8 +220,8 @@ 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 +Alt+v+ to create a +Vertical Split Container+ (to -open a +Horizontal Split Container+, use +Alt+h+). Now you can open a new +orientation. Instead, press +mod+v+ to create a +Vertical Split Container+ (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-layout1.png["Layout",float="right"] @@ -247,7 +246,7 @@ windows will be opened to the right of the +Vertical Split Container+: image::tree-shot3.png["shot3",title="Focus parent, then open new terminal"] - +[[configuring]] == Configuring i3 This is where the real fun begins ;-). Most things are very dependant on your @@ -266,6 +265,14 @@ To change the configuration of i3, copy +/etc/i3/config+ to +\~/.i3/config+ (or +~/.config/i3/config+ if you like the XDG directory scheme) and edit it with a text editor. +On first start (and on all following starts, unless you have a configuration +file), i3 will offer you to create a configuration file. You can tell the +wizard to use either Alt (Mod1) or Windows (Mod4) as modifier in the config +file. Also, the created config file will use the key symbols of your current +keyboard layout. To start the wizard, use the command +i3-config-wizard+. +Please note that you must not have +~/.i3/config+, otherwise the wizard will +exit. + === Comments It is possible and recommended to use comments in your configuration file to @@ -279,10 +286,9 @@ a # and can only be used at the beginning of a line: === Fonts -i3 uses X core fonts (not Xft) for rendering window titles and the internal -workspace bar. 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 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. If i3 cannot open the configured font, it will output an error in the logfile and fall back to a working font. @@ -310,9 +316,9 @@ also mix your bindings, though i3 will not protect you from overlapping ones). are the ones you use in Xmodmap to remap your keys. To get the current mapping of your keys, use +xmodmap -pke+. -* Keycodes do not need to have a symbol assigned (handy for some hotkeys - on some notebooks) and they will not change their meaning as you switch to a - different keyboard layout (when using +xmodmap+). +* Keycodes do not need to have a symbol assigned (handy for custom vendor + hotkeys on some notebooks) and they will not change their meaning as you + switch to a different keyboard layout (when using +xmodmap+). My recommendation is: If you often switch keyboard layouts but you want to keep your bindings in the same physical location on the keyboard, use keycodes. @@ -328,10 +334,10 @@ bindcode [Modifiers+]keycode command *Examples*: -------------------------------- # Fullscreen -bindsym Mod1+f f +bindsym mod+f f # Restart -bindsym Mod1+Shift+r restart +bindsym mod+Shift+r restart # Notebook-specific hotkeys bindcode 214 exec /home/michael/toggle_beamer.sh @@ -369,7 +375,7 @@ you hold the shift button as well, the resize will be proportional. floating_modifier -------------------------------- -*Examples*: +*Example*: -------------------------------- floating_modifier Mod1 -------------------------------- @@ -390,7 +396,7 @@ workspace_layout new_container stack-limit ///////////////////////////////////////////// -*Examples*: +*Example*: --------------------- workspace_layout tabbed --------------------- @@ -404,7 +410,7 @@ This option determines which border style new windows will have. new_window --------------------------------------------- -*Examples*: +*Example*: --------------------- new_window 1pixel --------------------- @@ -421,7 +427,7 @@ variables can be handy. set $name value -------------- -*Examples*: +*Example*: ------------------------ set $m Mod1 bindsym $m+Shift+r restart @@ -431,19 +437,19 @@ Variables are directly replaced in the file when parsing. There is no fancy handling and there are absolutely no plans to change this. If you need a more dynamic configuration you should create a little script which generates a configuration file and run it before starting i3 (for example in your -+.xsession+ file). ++~/.xsession+ file). === Automatically putting clients on specific workspaces [[assign_workspace]] -It is recommended that you match on window classes wherever possible because -some applications first create their window, and then worry about setting the -correct title. Firefox with Vimperator comes to mind. The window starts up -being named Firefox, and only when Vimperator is loaded does the title change. -As i3 will get the title as soon as the application maps the window (mapping -means actually displaying it on the screen), you’d need to have to match on -'Firefox' in this case. +It is recommended that you match on window classes insetead of window titles +whenever possible because some applications first create their window, and then +worry about setting the correct title. Firefox with Vimperator comes to mind. +The window starts up being named Firefox, and only when Vimperator is loaded +does the title change. As i3 will get the title as soon as the application maps +the window (mapping means actually displaying it on the screen), you’d need to +have to match on 'Firefox' in this case. You can prefix or suffix workspaces with a `~` to specify that matching clients should be put into floating mode. If you specify only a `~`, the client will @@ -573,10 +579,12 @@ i3 uses unix sockets to provide an IPC interface. This allows third-party programs to get information from i3, such as the current workspaces (to display a workspace bar), and to control i3. -To enable it, you have to configure a path where the unix socket will be -stored. The default path is +/tmp/i3-ipc.sock+. +The IPC socket is enabled by default and will be created in ++/tmp/i3-%u/ipc-socket.%p+ where +%u+ is your UNIX username and +%p+ is the PID +of i3. -You can override the default path through the environment-variable +I3SOCK+. +You can override the default path through the environment-variable +I3SOCK+ or +by specifying the +ipc-socket+ directive. *Examples*: ---------------------------- @@ -610,21 +618,21 @@ focus_follows_mouse no To change the layout of the current container to stacking, use +layout stacking+, for default use +layout default+ and for tabbed, use +layout -tabbed+. To make the current client (!) fullscreen, use +fullscreen+, to make +tabbed+. To make the current window (!) fullscreen, use +fullscreen+, to make it floating (or tiling again) use +floating enable+ respectively +floating disable+ (or +floating toggle+): *Examples*: -------------- -bindsym Mod1+s layout stacking -bindsym Mod1+l layout default -bindsym Mod1+w layout tabbed +bindsym mod+s layout stacking +bindsym mod+l layout default +bindsym mod+w layout tabbed # Toggle fullscreen -bindsym Mod1+f fullscreen +bindsym mod+f fullscreen # Toggle floating/tiling -bindsym Mod1+t floating toggle +bindsym mod+t floating toggle -------------- === Focusing/Moving containers @@ -650,28 +658,29 @@ For moving, use +move left+, +move right+, +move down+ and +move up+. *Examples*: ---------------------- # Focus clients on the left, bottom, top, right: -bindsym Mod1+j focus left -bindsym Mod1+k focus down -bindsym Mod1+l focus up -bindsym Mod1+semicolon focus right +bindsym mod+j focus left +bindsym mod+k focus down +bindsym mod+l focus up +bindsym mod+semicolon focus right # Focus parent container -bindsym Mod1+u focus parent +bindsym mod+u focus parent # Focus last floating/tiling container -bindsym Mod1+g focus mode_toggle +bindsym mod+g focus mode_toggle # Move client to the left, bottom, top, right: -bindsym Mod1+j move left -bindsym Mod1+k move down -bindsym Mod1+l move up -bindsym Mod1+semicolon move right +bindsym mod+j move left +bindsym mod+k move down +bindsym mod+l move up +bindsym mod+semicolon move right ---------------------- === Changing workspaces/moving containers to workspaces To change to a specific workspace, use the +workspace+ command, followed by the -number or name of the workspace. To move containers, use +move workspace+. +number or name of the workspace. To move containers to specific workspaces, use ++move workspace+. You can also switch to the next and previous workspace with the commands +workspace next+ and +workspace prev+, which is handy, for example, if you have @@ -680,12 +689,12 @@ combination. *Examples*: ------------------------- -bindsym Mod1+1 workspace 1 -bindsym Mod1+2 workspace 2 +bindsym mod+1 workspace 1 +bindsym mod+2 workspace 2 ... -bindsym Mod1+Shift+1 move workspace 1 -bindsym Mod1+Shift+2 move workspace 2 +bindsym mod+Shift+1 move workspace 1 +bindsym mod+Shift+2 move workspace 2 ... ------------------------- @@ -721,7 +730,7 @@ mode "resize" { } # Enter resize mode -bindsym Mod1+r mode "resize" +bindsym mod+r mode "resize" ---------------------------------------------------------------------- === Jumping to specific windows @@ -731,7 +740,7 @@ specific window. For example, while working on workspace 3 you may want to jump to your mail client to email your boss that you’ve achieved some important goal. Instead of figuring out how to navigate to your mailclient, it would be more convenient to have a shortcut. You can use the +focus+ command -for that. +with criteria for that. *Syntax*: ---------------------------------------------------- @@ -742,7 +751,7 @@ for that. *Examples*: ------------------------------------------------ # Get me to the next open VIM instance -bindsym Mod1+a [class="urxvt" title="VIM"] focus +bindsym mod+a [class="urxvt" title="VIM"] focus ------------------------------------------------ === VIM-like marks (mark/goto) @@ -763,19 +772,25 @@ can also prefix this command and display a custom prompt for the input dialog. *Syntax*: ------------------------------ -mark +mark identifier [con_mark="identifier"] focus ------------------------------ +*Example (in a terminal)*: +------------------------------ +$ i3-msg mark irssi +$ i3-msg '[con_mark="irssi"] focus' +------------------------------ + /////////////////////////////////////////////////////////////////// TODO: make i3-input replace %s *Examples*: --------------------------------------- # Read 1 character and mark the current window with this character -bindsym Mod1+m exec i3-input -p 'mark ' -l 1 -P 'Mark: ' +bindsym mod+m exec i3-input -p 'mark ' -l 1 -P 'Mark: ' # Read 1 character and go to the window with the character -bindsym Mod1+g exec i3-input -p 'goto ' -l 1 -P 'Goto: ' +bindsym mod+g exec i3-input -p 'goto ' -l 1 -P 'Goto: ' --------------------------------------- Alternatively, if you do not want to mess with +i3-input+, you could create @@ -792,9 +807,9 @@ There is also +border toggle+ which will toggle the different border styles. *Examples*: ---------------------------- -bindsym Mod1+t border normal -bindsym Mod1+y border 1pixel -bindsym Mod1+u border none +bindsym mod+t border normal +bindsym mod+y border 1pixel +bindsym mod+u border none ---------------------------- [[stack-limit]] @@ -834,16 +849,14 @@ image:stacklimit.png[Container limited to two columns] You can make i3 reload its configuration file with +reload+. You can also restart i3 inplace with the +restart+ command to get it out of some weird state (if that should ever happen) or to perform an upgrade without having to restart -your X session. However, your layout is not preserved at the moment, meaning -that all open windows will end up in a single container in default layout -after the restart. To exit i3 properly, you can use the +exit+ command, +your X session. To exit i3 properly, you can use the +exit+ command, however you don’t need to (simply killing your X session is fine as well). *Examples*: ---------------------------- -bindsym Mod1+Shift+r restart -bindsym Mod1+Shift+w reload -bindsym Mod1+Shift+e exit +bindsym mod+Shift+r restart +bindsym mod+Shift+w reload +bindsym mod+Shift+e exit ---------------------------- [[multi_monitor]]