X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fuserguide;h=e419fcece37ef988e905a0d5c4f54d39bac0b772;hb=7270206e24d53dfc927e7a965dec30b66b7c7ff5;hp=7eea85423b335f336d7feb806b86b4ec37e68b8c;hpb=94a46a1e35a9cb4e1618feedf669b61a6c193c42;p=i3%2Fi3 diff --git a/docs/userguide b/docs/userguide index 7eea8542..e419fcec 100644 --- a/docs/userguide +++ b/docs/userguide @@ -23,18 +23,25 @@ image:keyboard-layer2.png["Keys to use with Shift+$mod",width=600,link="keyboard 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 the Windows -key (Mod4) being a popular alternative. +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 +55,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 @@ -107,7 +114,7 @@ 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 +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 @@ -142,8 +149,10 @@ 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/i3.config.keycodes[default config] provided +by i3. === Restarting i3 inplace @@ -170,7 +179,8 @@ around. By grabbing the borders and moving them you can resize the window. You 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/i3.config.keycodes[default config]. Floating windows are always on top of tiling windows. @@ -195,9 +205,8 @@ 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 @@ -281,7 +290,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 @@ -299,7 +308,6 @@ a # and can only be used at the beginning of a line: ------------------- [[fonts]] - === Fonts i3 has support for both X core fonts and FreeType fonts (through Pango) to @@ -332,7 +340,6 @@ font pango:Terminus 11px -------------------------------------------------------------- [[keybindings]] - === Keyboard bindings A keyboard binding makes i3 execute a command (see below) upon pressing a @@ -361,8 +368,8 @@ after the keys have been released. *Syntax*: ---------------------------------- -bindsym [--release] [+] command -bindcode [--release] [+] command +bindsym [--release] [+][+] command +bindcode [--release] [+][+] command ---------------------------------- *Examples*: @@ -388,15 +395,15 @@ Available Modifiers: Mod1-Mod5, Shift, Control:: Standard modifiers, see +xmodmap(1)+ -Mode_switch:: -Unlike other window managers, i3 can use Mode_switch as a modifier. This allows -you to remap capslock (for example) to Mode_switch and use it for both: typing -umlauts or special characters 'and' having some comfortably reachable key -bindings. For example, when typing, capslock+1 or capslock+2 for switching -workspaces is totally convenient. Try it :-). +Group1, Group2, Group3, Group4:: +When using multiple keyboard layouts (e.g. with `setxkbmap -layout us,ru`), you +can specify in which XKB group (also called “layout”) a keybinding should be +active. By default, keybindings are translated in Group1 and are active in all +groups. If you want to override keybindings in one of your layouts, specify the +corresponding group. For backwards compatibility, the group “Mode_switch” is an +alias for Group2. [[mousebindings]] - === Mouse bindings A mouse binding makes i3 execute a command upon pressing a specific mouse @@ -433,8 +440,59 @@ bindsym button9 move left bindsym button8 move right -------------------------------- -[[floating_modifier]] +[[binding_modes]] +=== Binding modes + +You can have multiple sets of bindings by using different binding modes. When +you switch to another binding mode, all bindings from the current mode are +released and only the bindings defined in the new mode are valid for as long as +you stay in that binding mode. The only predefined binding mode is +default+, +which is the mode i3 starts out with and to which all bindings not defined in a +specific binding mode belong. + +Working with binding modes consists of two parts: defining a binding mode and +switching to it. For these purposes, there are one config directive and one +command, both of which are called +mode+. The directive is used to define the +bindings belonging to a certain binding mode, while the command will switch to +the specified mode. + +It is recommended to use binding modes in combination with <> in +order to make maintenance easier. Below is an example of how to use a binding +mode. +Note that it is advisable to define bindings for switching back to the default +mode. + +Note that it is possible to use <> for binding modes, but you +need to enable it explicitly by passing the +--pango_markup+ flag to the mode +definition. + +*Syntax*: +---------------------------- +# config directive +mode [--pango_markup] + +# command +mode +---------------------------- + +*Example*: +------------------------------------------------------------------------ +# Press $mod+o followed by either f, t, Esc or Return to launch firefox, +# thunderbird or return to the default mode, respectively. +set $mode_launcher Launch: [f]irefox [t]hunderbird +bindsym $mod+o mode "$mode_launcher" + +mode "$mode_launcher" { + bindsym f exec firefox + bindsym t exec thunderbird + + bindsym Esc mode "default" + bindsym Return mode "default" +} +------------------------------------------------------------------------ + +[[floating_modifier]] === The floating modifier To move floating windows with your mouse, you can either grab their titlebar @@ -503,17 +561,11 @@ default_orientation vertical This option determines in which mode new containers on workspace level will start. -/////////////////////////////// -See also <>. -////////////////////////////// *Syntax*: --------------------------------------------- workspace_layout default|stacking|tabbed --------------------------------------------- -///////////////////////////////////////////// -new_container stack-limit -///////////////////////////////////////////// *Example*: --------------------- @@ -523,20 +575,20 @@ workspace_layout tabbed === Border style for new windows This option determines which border style new windows will have. The default is -"normal". Note that new_float applies only to windows which are starting out as -floating windows, e.g. dialog windows. ++normal+. Note that new_float applies only to windows which are starting out as +floating windows, e.g., dialog windows, but not windows that are floated later on. *Syntax*: --------------------------------------------- -new_window normal|1pixel|none|pixel +new_window normal|none|pixel new_window normal|pixel -new_float normal|1pixel|none|pixel +new_float normal|none|pixel new_float normal|pixel --------------------------------------------- *Example*: --------------------- -new_window 1pixel +new_window pixel --------------------- The "normal" and "pixel" border styles support an optional border width in @@ -568,6 +620,7 @@ hide_edge_borders none|vertical|horizontal|both hide_edge_borders vertical ---------------------- +[[for_window]] === Arbitrary commands for specific windows (for_window) With the +for_window+ command, you can let i3 execute any command when it @@ -585,7 +638,7 @@ for_window for_window [class="XTerm"] floating enable # Make all urxvts use a 1-pixel border: -for_window [class="urxvt"] border 1pixel +for_window [class="urxvt"] border pixel 1 # A less useful, but rather funny example: # makes the window floating as soon as I change @@ -595,17 +648,20 @@ for_window [title="x200: ~/work"] floating enable The valid criteria are the same as those for commands, see <>. -=== Don't focus window upon opening - [[no_focus]] +=== Don't focus window upon opening When a new window appears, it will be focused. The +no_focus+ directive allows preventing -this from happening and can be used in combination with <>. +this from happening and must be used in combination with <>. Note that this does not apply to all cases, e.g., when feeding data into a running application causing it to request being focused. To configure the behavior in such cases, refer to <>. ++no_focus+ will also be ignored for the first window on a workspace as there shouldn't be +a reason to not focus the window in this case. This allows for better usability in +combination with +workspace_layout+. + *Syntax*: ------------------- no_focus @@ -616,6 +672,7 @@ no_focus no_focus [window_role="pop-up"] ------------------------------- +[[variables]] === Variables As you learned in the section about keyboard bindings, you will have @@ -641,9 +698,8 @@ 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). -=== Automatically putting clients on specific workspaces - [[assign_workspace]] +=== Automatically putting clients on specific workspaces To automatically make a specific window show up on a specific workspace, you can use an *assignment*. You can match windows by using any criteria, @@ -727,8 +783,8 @@ also when restarting i3 you should use the +exec_always+ keyword. These commands will be run in order. See <> for details on the special meaning of +;+ (semicolon) -and +,+ (comma): they chain commands together in i3 and need to be escaped if -you want to use them in your command. +and +,+ (comma): they chain commands together in i3, so you need to use quoted +strings if they appear in your command. *Syntax*: --------------------------------------- @@ -748,7 +804,6 @@ exec --no-startup-id urxvt The flag --no-startup-id is explained in <>. [[workspace_screen]] - === Automatically putting workspaces on specific screens If you assign clients to workspaces, it might be handy to put the @@ -798,18 +853,11 @@ client.urgent:: client.placeholder:: Background and text color are used to draw placeholder window contents (when restoring layouts). Border and indicator are ignored. - -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 -will be rendered. - -*Syntax*: -------------------------- -client.background -------------------------- - -Only clients that do not cover the whole area of this window expose the color -used to paint it. +client.background:: + Background color which will be used to paint the background of the + client window on top of which the client will be rendered. Only clients + which do not cover the whole area of this window expose the color. Note + that this colorclass only takes a single color. Colors are in HTML hex format (#rrggbb), see the following example: @@ -821,6 +869,8 @@ client.focused_inactive #333333 #5f676a #ffffff #484e50 client.unfocused #333333 #222222 #888888 #292d2e client.urgent #2f343a #900000 #ffffff #900000 client.placeholder #000000 #0c0c0c #ffffff #000000 + +client.background #ffffff --------------------------------------------------------- Note that for the window decorations, the color around the child window is the @@ -1012,9 +1062,8 @@ force_display_urgency_hint ms force_display_urgency_hint 500 ms --------------------------------- -=== Focus on window activation - [[focus_on_window_activation]] +=== Focus on window activation If a window is activated, e.g., via +google-chrome www.google.com+, it may request to take focus. Since this may not preferable, different reactions can be configured. @@ -1039,6 +1088,7 @@ focus:: none:: The window will neither be focused, nor be marked urgent. +[[show_marks]] === Drawing marks on window decoration If activated, marks on windows are drawn in their window decoration. However, @@ -1057,6 +1107,19 @@ show_marks yes|no show_marks yes -------------- +[[line_continuation]] +=== Line continuation + +Config files support line continuation, meaning when you end a line in a +backslash character (`\`), the line-break will be ignored by the parser. This +feature can be used to create more readable configuration files. + +*Examples*: +------------------- +bindsym Mod1+f \ +fullscreen toggle +------------------- + == Configuring i3bar The bar at the bottom of your monitor is drawn by a separate process called @@ -1118,7 +1181,10 @@ right hand side of the bar. This is useful to display system information like your current IP address, battery status or date/time. The specified command will be passed to +sh -c+, so you can use globbing and -have to have correct quoting etc. +have to have correct quoting etc. Note that for signal handling, depending on +your shell (users of dash(1) are known to be affected), you have to use the +shell’s exec command so that signals are passed to your program, not to the +shell. *Syntax*: ------------------------ @@ -1129,6 +1195,9 @@ status_command ------------------------------------------------- bar { status_command i3status --config ~/.i3status.conf + + # For dash(1) users who want signal handling to work: + status_command exec ~/.bin/my_status_command } ------------------------------------------------- @@ -1184,23 +1253,41 @@ Available modifiers are Mod1-Mod5, Shift, Control (see +xmodmap(1)+). === Mouse button commands Specifies a command to run when a button was pressed on i3bar to override the -default behavior. Currently only the mouse wheel buttons are supported. This is -useful for disabling the scroll wheel action or running scripts that implement -custom behavior for these buttons. +default behavior. This is useful, e.g., for disabling the scroll wheel action +or running scripts that implement custom behavior for these buttons. + +A button is always named +button+, where 1 to 5 are default buttons as follows and higher +numbers can be special buttons on devices offering more buttons: + +button1:: + Left mouse button. +button2:: + Middle mouse button. +button3:: + Right mouse button. +button4:: + Scroll wheel up. +button5:: + Scroll wheel down. + +Please note that the old +wheel_up_cmd+ and +wheel_down_cmd+ commands are deprecated +and will be removed in a future release. We strongly recommend using the more general ++bindsym+ with +button4+ and +button5+ instead. *Syntax*: ---------------------- -wheel_up_cmd -wheel_down_cmd ---------------------- +---------------------------- +bindsym button +---------------------------- *Example*: ---------------------- +--------------------------------------------------------- bar { - wheel_up_cmd nop - wheel_down_cmd exec ~/.i3/scripts/custom_wheel_down + # disable clicking on workspace buttons + bindsym button1 nop + # execute custom script when scrolling downwards + bindsym button5 exec ~/.i3/scripts/custom_wheel_down } ---------------------- +--------------------------------------------------------- === Bar ID @@ -1283,9 +1370,9 @@ You can configure on which output (monitor) the icons should be displayed or you can turn off the functionality entirely. *Syntax*: -------------------------------- -tray_output none|primary|output -------------------------------- +--------------------------------- +tray_output none|primary| +--------------------------------- *Example*: ------------------------- @@ -1295,7 +1382,9 @@ bar { } # show tray icons on the primary monitor -tray_output primary +bar { + tray_output primary +} # show tray icons on the big monitor bar { @@ -1308,6 +1397,28 @@ Note that you might not have a primary output configured yet. To do so, run: xrandr --output --primary ------------------------- +Note that when you use multiple bar configuration blocks, either specify +`tray_output primary` in all of them or explicitly specify `tray_output none` +in bars which should not display the tray, otherwise the different instances +might race each other in trying to display tray icons. + +=== Tray padding + +The tray is shown on the right-hand side of the bar. By default, a padding of 2 +pixels is used for the upper, lower and right-hand side of the tray area and +between the individual icons. + +*Syntax*: +------------------------- +tray_padding [px] +------------------------- + +*Example*: +------------------------- +# Obey Fitts's law +tray_padding 0 +------------------------- + === Font Specifies the font to be used in the bar. See <>. @@ -1390,8 +1501,8 @@ bar { Specifies whether the current binding mode indicator should be shown or not. This is useful if you want to hide the workspace buttons but still be able -to see the current binding mode indicator. -For an example of a +mode+ definition, see <>. +to see the current binding mode indicator. See <> to learn what +modes are and how to use them. The default is to show the mode indicator. @@ -1432,7 +1543,10 @@ inactive_workspace:: will be the case for most workspaces. urgent_workspace:: Border, background and text color for a workspace button when the workspace - contains a window with the urgency hint set. Also applies to +mode+ indicators. + contains a window with the urgency hint set. +binding_mode:: + Border, background and text color for the binding mode indicator. If not used, + the colors will be taken from +urgent_workspace+. *Syntax*: ---------------------------------------- @@ -1457,6 +1571,7 @@ bar { active_workspace #333333 #5f676a #ffffff inactive_workspace #333333 #222222 #888888 urgent_workspace #2f343a #900000 #ffffff + binding_mode #2f343a #900000 #ffffff } } -------------------------------------- @@ -1514,35 +1629,49 @@ for_window [class="^evil-app$"] floating enable, move container to workspace 4 The criteria which are currently implemented are: class:: - Compares the window class (the second part of WM_CLASS) + Compares the window class (the second part of WM_CLASS). Use the + special value +\_\_focused__+ to match all windows having the same window + class as the currently focused window. instance:: - Compares the window instance (the first part of WM_CLASS) + Compares the window instance (the first part of WM_CLASS). Use the + special value +\_\_focused__+ to match all windows having the same window + instance as the currently focused window. window_role:: - Compares the window role (WM_WINDOW_ROLE). + Compares the window role (WM_WINDOW_ROLE). Use the special value + +\_\_focused__+ to match all windows having the same window role as the + currently focused window. window_type:: - Compare the window type (_NET_WM_WINDOW_TYPE). Possible values are - +normal+, +dialog+, +utility+, +toolbar+, +splash+, +menu+, +dropdown_menu+, - +popup_menu+ and +toolti+. + Compare the window type (_NET_WM_WINDOW_TYPE). Possible values are + +normal+, +dialog+, +utility+, +toolbar+, +splash+, +menu+, +dropdown_menu+, + +popup_menu+ and +tooltip+. id:: Compares the X11 window ID, which you can get via +xwininfo+ for example. title:: - Compares the X11 window title (_NET_WM_NAME or WM_NAME as fallback). + Compares the X11 window title (\_NET_WM_NAME or WM_NAME as fallback). + Use the special value +\_\_focused__+ to match all windows having the + same window title as the currently focused window. urgent:: Compares the urgent state of the window. Can be "latest" or "oldest". Matches the latest or oldest urgent window, respectively. (The following aliases are also available: newest, last, recent, first) +workspace:: + Compares the workspace name of the workspace the window belongs to. Use + the special value +\_\_focused__+ to match all windows in the currently + focused workspace. con_mark:: - Compares the mark set for this container, see <>. + Compares the marks set for this container, see <>. A + match is made if any of the container's marks matches the specified + mark. con_id:: Compares the i3-internal container ID, which you can get via the IPC - interface. Handy for scripting. + interface. Handy for scripting. Use the special value +\_\_focused__+ + to match only the currently focused window. -The criteria +class+, +instance+, +role+, +title+ and +mark+ are actually -regular expressions (PCRE). See +pcresyntax(3)+ or +perldoc perlre+ for +The criteria +class+, +instance+, +role+, +title+, +workspace+ and +mark+ are +actually regular expressions (PCRE). See +pcresyntax(3)+ or +perldoc perlre+ for information on how to use them. [[exec]] - === Executing applications (exec) What good is a window manager if you can’t actually start any applications? @@ -1551,8 +1680,8 @@ shell. This implies that you can use globbing (wildcards) and programs will be searched in your +$PATH+. See <> for details on the special meaning of +;+ (semicolon) -and +,+ (comma): they chain commands together in i3 and need to be escaped if -you want to use them in your command. +and +,+ (comma): they chain commands together in i3, so you need to use quoted +strings if they appear in your command. *Syntax*: -------------------------------- @@ -1639,15 +1768,16 @@ bindsym $mod+f fullscreen toggle bindsym $mod+t floating toggle -------------- -=== Focusing/Moving containers +[[_focusing_moving_containers]] +=== Focusing containers -To change the focus, use the focus command: +focus left+, +focus right+, +focus -down+ and +focus up+. - -There are a few special parameters you can use for the focus command: +To change focus, you can use the +focus+ command. The following options are +available: +left|right|up|down:: + Sets focus to the nearest container in the given direction. parent:: - Sets focus to the +Parent Container+ of the current +Container+. + Sets focus to the parent container of the current container. child:: The opposite of +focus parent+, sets the focus to the last focused child container. @@ -1661,23 +1791,16 @@ output:: Followed by a direction or an output name, this will focus the corresponding output. -For moving, use +move left+, +move right+, +move down+ and +move up+. - *Syntax*: ------------------------------------ -focus -focus -focus output <|output> -move [ px] -move [absolute] position [[ px] [ px]|center] ------------------------------------ - -Note that the amount of pixels you can specify for the +move+ command is only -relevant for floating containers. The default amount is 10 pixels. +---------------------------------------------- +focus left|right|down|up +focus parent|child|floating|tiling|mode_toggle +focus output left|right|up|down| +---------------------------------------------- *Examples*: ----------------------- -# Focus container on the left, bottom, top, right: +------------------------------------------------- +# Focus container on the left, bottom, top, right bindsym $mod+j focus left bindsym $mod+k focus down bindsym $mod+l focus up @@ -1694,8 +1817,33 @@ bindsym $mod+x focus output right # Focus the big output bindsym $mod+x focus output HDMI-2 +------------------------------------------------- -# Move container to the left, bottom, top, right: +=== Moving containers + +Use the +move+ command to move a container. + +*Syntax*: +----------------------------------------------------- +# Moves the container into the given direction. +# The optional pixel argument specifies how far the +# container should be moved if it is floating and +# defaults to 10 pixels. +move [ px] + +# Moves the container either to a specific location +# or to the center of the screen. If 'absolute' is +# used, it is moved to the center of all outputs. +move [absolute] position [[ px] [ px]|center] + +# Moves the container to the current position of the +# mouse cursor. Only affects floating containers. +move position mouse +----------------------------------------------------- + +*Examples*: +------------------------------------------------------- +# Move container to the left, bottom, top, right bindsym $mod+j move left bindsym $mod+k move down bindsym $mod+l move up @@ -1705,16 +1853,42 @@ bindsym $mod+semicolon move right # move more than the default bindsym $mod+j move left 20 px -# Move floating container to the center -# of all outputs +# Move floating container to the center of all outputs bindsym $mod+c move absolute position center ----------------------- + +# Move container to the current position of the cursor +bindsym $mod+m move position mouse +------------------------------------------------------- + +=== Sticky floating windows + +If you want a window to stick to the glass, i.e., have it stay on screen even +if you switch to another workspace, you can use the +sticky+ command. For +example, this can be useful for notepads, a media player or a video chat +window. + +Note that while any window can be made sticky through this command, it will +only take effect if the window is floating. + +*Syntax*: +---------------------------- +sticky enable|disable|toggle +---------------------------- + +*Examples*: +------------------------------------------------------ +# make a terminal sticky that was started as a notepad +for_window [instance=notepad] sticky enable +------------------------------------------------------ === 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 -+move container to workspace+. +number or name of the workspace. Pass the optional flag ++--no-auto-back-and-forth+ to disable <> for this specific call +only. + +To move containers to specific workspaces, use +move container to 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 @@ -1725,6 +1899,10 @@ container to workspace next+, +move container to workspace prev+ to move a container to the next/previous workspace and +move container to workspace current+ (the last one makes sense only when used with criteria). ++workspace next+ cycles through either numbered or named workspaces. But when it +reaches the last numbered/named workspace, it looks for named workspaces after +exhausting numbered ones and looks for numbered ones after exhausting named ones. + See <> for how to move a container/workspace to a different RandR output. @@ -1741,8 +1919,8 @@ workspace using +move container to workspace back_and_forth+. ----------------------------------- workspace next|prev|next_on_output|prev_on_output workspace back_and_forth -workspace -workspace number +workspace [--no-auto-back-and-forth] +workspace [--no-auto-back-and-forth] number move [window|container] [to] workspace move [window|container] [to] workspace number @@ -1820,7 +1998,7 @@ rename workspace to i3-msg 'rename workspace 5 to 6' i3-msg 'rename workspace 1 to "1: www"' i3-msg 'rename workspace "1: www" to "10: www"' -i3-msg 'rename workspace to "2: mail" +i3-msg 'rename workspace to "2: mail"' bindsym $mod+r exec i3-input -F 'rename workspace to "%s"' -P 'New name: ' -------------------------------------------------------------------------- @@ -1829,9 +2007,8 @@ bindsym $mod+r exec i3-input -F 'rename workspace to "%s"' -P 'New name: ' See <> for how to move a container/workspace to a different RandR output. -=== Moving containers/workspaces to RandR outputs - [[move_to_outputs]] +=== Moving containers/workspaces to RandR outputs To move a container to another RandR output (addressed by names like +LVDS1+ or +VGA1+) or to a RandR output identified by a specific direction (like +left+, @@ -1853,7 +2030,7 @@ bindsym $mod+x move workspace to output right bindsym $mod+x move container to output VGA1 -------------------------------------------------------- -=== Moving containers/workspaces to marks +=== Moving containers/windows to marks To move a container to another container with a specific mark (see <>), you can use the following command. @@ -1874,7 +2051,6 @@ for_window [instance="tabme"] move window to mark target -------------------------------------------------------- [[resizingconfig]] - === Resizing containers/windows If you want to resize containers/windows using your keyboard, you can use the @@ -1883,6 +2059,7 @@ If you want to resize containers/windows using your keyboard, you can use the *Syntax*: ------------------------------------------------------- resize grow|shrink [ px [or ppt]] +resize set [px] [px] ------------------------------------------------------- Direction can either be one of +up+, +down+, +left+ or +right+. Or you can be @@ -1891,38 +2068,18 @@ space from all the other containers. The optional pixel argument specifies by how many pixels a *floating container* should be grown or shrunk (the default is 10 pixels). The ppt argument means percentage points and specifies by how many percentage points a *tiling container* should be grown or shrunk (the -default is 10 percentage points). - -I recommend using the resize command inside a so called +mode+: - -.Example: Configuration file, defining a mode for resizing ----------------------------------------------------------------------- -mode "resize" { - # These bindings trigger as soon as you enter the resize mode - - # Pressing left will shrink the window’s width. - # Pressing right will grow the window’s width. - # Pressing up will shrink the window’s height. - # Pressing down will grow the window’s height. - bindsym j resize shrink width 10 px or 10 ppt - bindsym k resize grow height 10 px or 10 ppt - bindsym l resize shrink height 10 px or 10 ppt - bindsym semicolon resize grow width 10 px or 10 ppt - - # same bindings, but for the arrow keys - bindsym Left resize shrink width 10 px or 10 ppt - bindsym Down resize grow height 10 px or 10 ppt - bindsym Up resize shrink height 10 px or 10 ppt - bindsym Right resize grow width 10 px or 10 ppt - - # back to normal: Enter or Escape - bindsym Return mode "default" - bindsym Escape mode "default" -} +default is 10 percentage points). Note that +resize set+ will only work for +floating containers. -# Enter resize mode -bindsym $mod+r mode "resize" ----------------------------------------------------------------------- +It is recommended to define bindings for resizing in a dedicated binding mode. +See <> and the example in the i3 +https://github.com/i3/i3/blob/next/i3.config.keycodes[default config] for more +context. + +*Example*: +------------------------------------------------ +for_window [class="urxvt"] resize set 640 480 +------------------------------------------------ === Jumping to specific windows @@ -1945,9 +2102,8 @@ with criteria for that. bindsym $mod+a [class="urxvt" title="VIM"] focus ------------------------------------------------ -=== VIM-like marks (mark/goto) - [[vim_like_marks]] +=== VIM-like marks (mark/goto) This feature is like the jump feature: It allows you to directly jump to a specific window (this means switching to the appropriate workspace and setting @@ -1963,24 +2119,36 @@ for this purpose: It lets you input a command and sends the command to i3. It can also prefix this command and display a custom prompt for the input dialog. The additional +--toggle+ option will remove the mark if the window already has -this mark, add it if the window has none or replace the current mark if it has -another mark. +this mark or add it otherwise. Note that you may need to use this in +combination with +--add+ (see below) as any other marks will otherwise be +removed. + +By default, a window can only have one mark. You can use the +--add+ flag to +put more than one mark on a window. -Refer to +show_marks+ if you don't want marks to be shown in the window decoration. +Refer to <> if you don't want marks to be shown in the window decoration. *Syntax*: ------------------------------- -mark [--toggle] +---------------------------------------------- +mark [--add|--replace] [--toggle] [con_mark="identifier"] focus unmark ------------------------------- +---------------------------------------------- *Example (in a terminal)*: ------------------------------- -$ i3-msg mark irssi -$ i3-msg '[con_mark="irssi"] focus' -$ i3-msg unmark irssi ------------------------------- +--------------------------------------------------------- +# marks the focused container +mark irssi + +# focus the container with the mark "irssi" +'[con_mark="irssi"] focus' + +# remove the mark "irssi" from whichever container has it +unmark irssi + +# remove all marks on all firefox windows +[class="(?i)firefox"] unmark +--------------------------------------------------------- /////////////////////////////////////////////////////////////////// TODO: make i3-input replace %s @@ -1997,55 +2165,72 @@ Alternatively, if you do not want to mess with +i3-input+, you could create seperate bindings for a specific set of labels and then only use those labels. /////////////////////////////////////////////////////////////////// -=== Changing border style +[[pango_markup]] +=== Window title format -To change the border of the current client, you can use +border normal+ to use the normal -border (including window title), +border 1pixel+ to use a 1-pixel border (no window title) -and +border none+ to make the client borderless. +By default, i3 will simply print the X11 window title. Using +title_format+, +this can be customized by setting the format to the desired output. This +directive supports +https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup] +and the following placeholders which will be replaced: -There is also +border toggle+ which will toggle the different border styles. ++%title+:: + The X11 window title (_NET_WM_NAME or WM_NAME as fallback). ++%class+:: + The X11 window class (second part of WM_CLASS). This corresponds to the + +class+ criterion, see <>. ++%instance+:: + The X11 window instance (first part of WM_CLASS). This corresponds to the + +instance+ criterion, see <>. + +Using the <> directive, you can set the title format for any window +based on <>. + +*Syntax*: +--------------------- +title_format +--------------------- *Examples*: ----------------------------- -bindsym $mod+t border normal -bindsym $mod+y border 1pixel -bindsym $mod+u border none ----------------------------- +------------------------------------------------------------------------------------- +# give the focused window a prefix +bindsym $mod+p title_format "Important | %title" -[[stack-limit]] +# print all window titles bold +for_window [class=".*"] title_format "%title" -/////////////////////////////////////////////////////////////////////////////// -TODO: not yet implemented -=== Changing the stack-limit of a container +# print window titles of firefox windows red +for_window [class="(?i)firefox"] title_format "%title" +------------------------------------------------------------------------------------- -If you have a single container with a lot of windows inside it (say, more than -10), the default layout of a stacking container can get a little unhandy. -Depending on your screen’s size, you might end up with only half of the title -lines being actually used, wasting a lot of screen space. +=== Changing border style -Using the +stack-limit+ command, you can limit the number of rows or columns -in a stacking container. i3 will create columns or rows (depending on what -you limited) automatically as needed. +To change the border of the current client, you can use +border normal+ to use the normal +border (including window title), +border pixel 1+ to use a 1-pixel border (no window title) +and +border none+ to make the client borderless. -*Syntax*: ------------------------------ -stack-limit cols|rows ------------------------------ +There is also +border toggle+ which will toggle the different border styles. -*Examples*: -------------------- -# I always want to have two window titles in one line -stack-limit cols 2 +*Syntax*: +----------------------------------------------- +border normal|pixel [] +border none|toggle -# Not more than 5 rows in this stacking container -stack-limit rows 5 -------------------- +# legacy syntax, equivalent to "border pixel 1" +border 1pixel +----------------------------------------------- -image:stacklimit.png[Container limited to two columns] -/////////////////////////////////////////////////////////////////////////////// +*Examples*: +---------------------------------------------- +# use window title, but no border +bindsym $mod+t border normal 0 +# use no window title and a thick border +bindsym $mod+y border pixel 3 +# use neither window title nor border +bindsym $mod+u border none +---------------------------------------------- [[shmlog]] - === Enabling shared memory logging As described in http://i3wm.org/docs/debugging.html, i3 can log to a shared @@ -2194,7 +2379,6 @@ bindsym $mod+Shift+b bar mode invisible bar-1 ------------------------------------------------ [[multi_monitor]] - == Multiple monitors As you can see in the goal list on the website, i3 was specifically developed @@ -2324,6 +2508,7 @@ position the window either at the top or at the bottom of the screen, depending on which hint the application sets. With i3bar, you can configure its position, see <>. +[[presentations]] === Giving presentations (multi-monitor) When giving a presentation, you typically want the audience to see what you see @@ -2332,7 +2517,6 @@ simple). For more complex presentations, you might want to have some notes which only you can see on your screen, while the audience can only see the slides. -[[presentations]] ==== Case 1: everybody gets the same output This is the simple case. You connect your computer to the video projector, turn on both (computer and video projector) and configure your X server to