X-Git-Url: https://git.sur5r.net/?p=i3%2Fi3.github.io;a=blobdiff_plain;f=_docs%2Fuserguide;h=acdc0a587e1834854fb6aebf532388e8cfde8d92;hp=97a9ab06a296f8bbf7ba486d5a4c4a1f50b7ab5b;hb=b7b358394f5c709bb8c098e4f3d29e4e2816371f;hpb=70adb9194c6845a41b292d59b931d2f18ed9f84b diff --git a/_docs/userguide b/_docs/userguide index 97a9ab0..acdc0a5 100644 --- a/_docs/userguide +++ b/_docs/userguide @@ -1,40 +1,48 @@ i3 User’s Guide =============== -Michael Stapelberg -August 2011 +Michael Stapelberg +March 2013 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. +window manager. If it does not, please check https://www.reddit.com/r/i3wm/ +first, then 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 keybindings (click to see the full size image): -*Keys to use with mod (alt):* +*Keys to use with $mod (Alt):* -image:keyboard-layer1.png["Keys to use with mod (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+mod:* +*Keys to use with Shift+$mod:* -image:keyboard-layer2.png["Keys to use with Shift+mod",width=600,link="keyboard-layer2.png"] +image:keyboard-layer2.png["Keys to use with Shift+$mod",width=600,link="keyboard-layer2.png"] The red keys are the modifiers you need to press (by default), the blue keys are your homerow. +Note that when starting i3 without a config file, i3-config-wizard will offer +you to create a config file in which the key positions (!) match what you see +in the image above, regardless of the keyboard layout you are using. If you +prefer to use a config file where the key letters match what you are seeing +above, just decline i3-config-wizard’s offer and base your config on ++/etc/i3/config+. + == Using i3 -Throughout this guide, the keyword +mod+ will be used to refer to the -configured modifier. This is the alt key (Mod1) by default, with windows (Mod4) -being a popular alternative. +Throughout this guide, the keyword +$mod+ will be used to refer to the +configured modifier. This is the Alt key (+Mod1+) by default, with the Windows +key (+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 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. +for this is +$mod+Enter+, that is Alt+Enter (+Mod1+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. image:single_terminal.png[Single terminal] @@ -48,9 +56,9 @@ image:two_terminals.png[Two terminals] To move the focus between the two terminals, you can use the direction keys which 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+. Of course, you can also use the arrow keys. +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+. 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 @@ -61,16 +69,18 @@ windows. TODO: picture of the tree -To split a window vertically, press +mod+v+. To split it horizontally, press -+mod+h+. +To split a window vertically, press +$mod+v+ before you create the new window. +To split it horizontally, press +$mod+h+. === Changing the container layout 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. @@ -78,23 +88,23 @@ 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 +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] === Toggling fullscreen mode for a window To display a window in fullscreen mode or to go out of fullscreen mode again, -press +mod+f+. +press +$mod+f+. There is also a global fullscreen mode in i3 in which the client will span all -available outputs. +available outputs (the command is +fullscreen toggle global+). === Opening other applications Aside from opening applications from a terminal, you can also use the handy -+dmenu+ which is opened by pressing +mod+d+ by default. Just type the name ++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. @@ -105,8 +115,8 @@ create a keybinding for starting the application directly. See the section === 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 +mod+Shift+q+ to kill a window. For applications which support +provide a menu, the escape key or a shortcut like +Control+w+ to close), you +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 @@ -116,7 +126,7 @@ depends on the application. Workspaces are an easy way to group a set of windows. By default, you are on the first workspace, as the bar on the bottom left indicates. To switch to -another workspace, press +mod+num+ where +num+ is the number of the workspace +another workspace, press +$mod+num+ where +num+ is the number of the workspace you want to use. If the workspace does not exist yet, it will be created. A common paradigm is to put the web browser on one workspace, communication @@ -130,7 +140,7 @@ focus to that screen. === Moving windows to workspaces -To move a window to another workspace, simply press +mod+Shift+num+ where +To move a window to another workspace, simply press +$mod+Shift+num+ where +num+ is (like when switching workspaces) the number of the target workspace. Similarly to switching workspaces, the target workspace will be created if it does not yet exist. @@ -140,32 +150,38 @@ it does not yet exist. The easiest way to resize a container is by using the mouse: Grab the border and move it to the wanted size. -See <> for how to configure i3 to be able to resize -columns/rows with your keyboard. +You can also use <> to define a mode for resizing via the +keyboard. To see an example for this, look at the +https://github.com/i3/i3/blob/next/etc/config.keycodes[default config] provided +by i3. === Restarting i3 inplace -To restart i3 inplace (and thus get into a clean state if there is a bug, or -to upgrade to a newer version of i3) you can use +mod+Shift+r+. +To restart i3 in place (and thus get into a clean state if there is a bug, or +to upgrade to a newer version of i3) you can use +$mod+Shift+r+. === Exiting i3 -To cleanly exit i3 without killing your X server, you can use +mod+Shift+e+. +To cleanly exit i3 without killing your X server, you can use +$mod+Shift+e+. +By default, a dialog will ask you to confirm if you really want to quit. === Floating -Floating mode is the opposite of tiling mode. The position and size of a window -are not managed by i3, but by you. Using this mode violates the tiling -paradigm but can be useful for some corner cases like "Save as" dialog -windows, or toolbar windows (GIMP or similar). Those windows usually set the -appropriate hint and are opened in floating mode by default. +Floating mode is the opposite of tiling mode. The position and size of +a window are not managed automatically by i3, but manually by +you. Using this mode violates the tiling paradigm but can be useful +for some corner cases like "Save as" dialog windows, or toolbar +windows (GIMP or similar). Those windows usually set the appropriate +hint and are opened in floating mode by default. -You can enable floating mode for a window by pressing +mod+Shift+Space+. By +You can toggle floating mode for a window by pressing +$mod+Shift+Space+. By dragging the window’s titlebar with your mouse you can move the window around. By grabbing the borders and moving them you can resize the window. You -can also do that by using the <>. +can also do that by using the <>. Another way to resize +floating windows using the mouse is to right-click on the titlebar and drag. -For resizing floating windows with your keyboard, see <>. +For resizing floating windows with your keyboard, see the resizing binding mode +provided by the i3 https://github.com/i3/i3/blob/next/etc/config.keycodes[default config]. Floating windows are always on top of tiling windows. @@ -174,7 +190,7 @@ Floating windows are always on top of tiling windows. 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 +finally the windows themselves. 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. @@ -190,27 +206,27 @@ like this: image::tree-layout2.png["layout2",float="right"] image::tree-shot4.png["shot4",title="Two terminals on standard workspace"] -=== Orientation and Split Containers - [[OrientationSplit]] +=== Orientation and Split Containers 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+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"] -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 -open a +Horizontal Split Container+, use +mod+h+). Now you can open a new +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-layout1.png["Layout",float="right"] @@ -235,10 +251,29 @@ windows will be opened to the right of the +Vertical Split Container+: 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+Shift+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 accommodate the +other two terminal windows. You will notice this when switching to tabbed mode +(for example). You would end up having one tab with a representation of the split +container (e.g., "H[urxvt firefox]") and the other one being the terminal window +you moved down. + [[configuring]] == Configuring i3 -This is where the real fun begins ;-). Most things are very dependant on your +This is where the real fun begins ;-). Most things are very dependent on your ideal working environment so we can’t make reasonable defaults for them. While not using a programming language for the configuration, i3 stays @@ -256,7 +291,7 @@ 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 +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 @@ -273,11 +308,20 @@ a # and can only be used at the beginning of a line: # 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. @@ -285,15 +329,18 @@ and fall back to a working font. *Syntax*: ------------------------------ font +font pango: [