X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fuserguide;h=52165e2dffe3b46013af118e81f5e268bd8fe81f;hb=eaf7a49e28b7ff8e1820a1b23350647574a0ed5a;hp=e07e544d93b242560021ceb90d406fa1eb8a8dcb;hpb=7a77c5f0bb988ec2fff52e231590fff93a4ee6b9;p=i3%2Fi3 diff --git a/docs/userguide b/docs/userguide index e07e544d..52165e2d 100644 --- a/docs/userguide +++ b/docs/userguide @@ -4,8 +4,9 @@ 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 check http://faq.i3wm.org/ first, then -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 @@ -151,7 +152,7 @@ and move it to the wanted size. 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 +https://github.com/i3/i3/blob/next/etc/config.keycodes[default config] provided by i3. === Restarting i3 inplace @@ -180,7 +181,7 @@ 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 the resizing binding mode -provided by the i3 https://github.com/i3/i3/blob/next/i3.config.keycodes[default config]. +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. @@ -296,6 +297,15 @@ 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. +Since i3 4.0, a new configuration format is used. i3 will try to automatically +detect the format version of a config file based on a few different keywords, +but if you want to make sure that your config is read with the new format, +include the following line in your config file: + +--------------------- +# i3 config file (v4) +--------------------- + === Comments It is possible and recommended to use comments in your configuration file to @@ -411,9 +421,9 @@ button in the scope of the clicked container (see <>). You can configure mouse bindings in a similar way to key bindings. *Syntax*: -------------------------------------------------------------------------------- -bindsym [--release] [--border] [--whole-window] [+]button command -------------------------------------------------------------------------------- +---------------------------------------------------------------------------------------------------- +bindsym [--release] [--border] [--whole-window] [--exclude-titlebar] [+]button command +---------------------------------------------------------------------------------------------------- By default, the binding will only run when you click on the titlebar of the window. If the +--release+ flag is given, it will run when the mouse button @@ -423,6 +433,9 @@ If the +--whole-window+ flag is given, the binding will also run when any part of the window is clicked, with the exception of the border. To have a bind run when the border is clicked, specify the +--border+ flag. +If the +--exclude-titlebar+ flag is given, the titlebar will not be considered +for the keybinding. + *Examples*: -------------------------------- # The middle button over a titlebar kills the window @@ -478,7 +491,7 @@ mode *Example*: ------------------------------------------------------------------------ -# Press $mod+o followed by either f, t, Esc or Return to launch firefox, +# Press $mod+o followed by either f, t, Escape 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" @@ -487,7 +500,7 @@ mode "$mode_launcher" { bindsym f exec firefox bindsym t exec thunderbird - bindsym Esc mode "default" + bindsym Escape mode "default" bindsym Return mode "default" } ------------------------------------------------------------------------ @@ -604,15 +617,18 @@ new_window pixel 3 --------------------- -=== Hiding vertical borders +[[_hiding_vertical_borders]] +=== Hiding borders adjacent to the screen edges -You can hide vertical borders adjacent to the screen edges using +You can hide container 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. +to waste even two pixels in displayspace. The "smart" setting hides borders on +workspaces with only one window visible, but keeps them on workspaces with +multiple windows visible. Default is none. *Syntax*: ----------------------------------------------- -hide_edge_borders none|vertical|horizontal|both +hide_edge_borders none|vertical|horizontal|both|smart ----------------------------------------------- *Example*: @@ -698,6 +714,38 @@ 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). +Also see <> to learn how to create variables based on resources +loaded from the X resource database. + +[[xresources]] +=== X resources + +<> can also be created using a value configured in the X resource +database. This is useful, for example, to avoid configuring color values within +the i3 configuration. Instead, the values can be configured, once, in the X +resource database to achieve an easily maintainable, consistent color theme +across many X applications. + +Defining a resource will load this resource from the resource database and +assign its value to the specified variable. A fallback must be specified in +case the resource cannot be loaded from the database. + +*Syntax*: +---------------------------------------------------- +set_from_resource $ +---------------------------------------------------- + +*Example*: +---------------------------------------------------------------------------- +# The ~/.Xresources should contain a line such as +# *color0: #121212 +# and must be loaded properly, e.g., by using +# xrdb ~/.Xresources +# This value is picked up on by other applications (e.g., the URxvt terminal +# emulator) and can be used in i3 like this: +set_from_resource $black i3wm.color0 #000000 +---------------------------------------------------------------------------- + [[assign_workspace]] === Automatically putting clients on specific workspaces @@ -718,7 +766,7 @@ considered. *Syntax*: ------------------------------------------------------------ -assign [→] [workspace] +assign [→] [workspace] [number] ------------------------------------------------------------ *Examples*: @@ -735,6 +783,12 @@ assign [class="^URxvt$"] → 2 # Assignment to a named workspace assign [class="^URxvt$"] → work +# Assign to the workspace with number 2, regardless of name +assign [class="^URxvt$"] → number 2 + +# You can also specify a number + name. If the workspace with number 2 exists, assign will skip the text part. +assign [class="^URxvt$"] → number "2: work" + # Start urxvt -name irssi assign [class="^URxvt$" instance="^irssi$"] → 3 ---------------------- @@ -784,7 +838,7 @@ 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, so you need to use quoted -strings if they appear in your command. +strings (as shown in <>) if they appear in your command. *Syntax*: --------------------------------------- @@ -835,9 +889,9 @@ workspace "2: vim" output VGA1 You can change all colors which i3 uses to draw the window decorations. *Syntax*: ------------------------------------------------------- - ------------------------------------------------------- +-------------------------------------------------------------------- + +-------------------------------------------------------------------- Where colorclass can be one of: @@ -862,20 +916,20 @@ client.background:: Colors are in HTML hex format (#rrggbb), see the following example: *Examples (default colors)*: ---------------------------------------------------------- -# class border backgr. text indicator -client.focused #4c7899 #285577 #ffffff #2e9ef4 -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 +---------------------------------------------------------------------- +# class border backgr. text indicator child_border +client.focused #4c7899 #285577 #ffffff #2e9ef4 #285577 +client.focused_inactive #333333 #5f676a #ffffff #484e50 #5f676a +client.unfocused #333333 #222222 #888888 #292d2e #222222 +client.urgent #2f343a #900000 #ffffff #900000 #900000 +client.placeholder #000000 #0c0c0c #ffffff #000000 #0c0c0c client.background #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 -the window. +"child_border", and "border" color is only the two thin lines around the +titlebar. The indicator color is used for indicating where a new window will be opened. For horizontal split containers, the right border will be painted in indicator @@ -910,12 +964,12 @@ the next section. === Focus follows mouse -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). +By default, window focus follows your mouse movements as the mouse crosses +window borders. 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*: -------------------------- @@ -1091,9 +1145,9 @@ none:: [[show_marks]] === Drawing marks on window decoration -If activated, marks on windows are drawn in their window decoration. However, -any mark starting with an underscore in its name (+_+) will not be drawn even if -this option is activated. +If activated, marks (see <>) on windows are drawn in their window +decoration. However, any mark starting with an underscore in its name (+_+) will +not be drawn even if this option is activated. The default for this option is +yes+. @@ -1113,11 +1167,15 @@ show_marks yes 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. +Commented lines are not continued. *Examples*: ------------------- bindsym Mod1+f \ fullscreen toggle + +# this line is not continued \ +bindsym Mod1+F fullscreen toggle ------------------- == Configuring i3bar @@ -1236,7 +1294,7 @@ the windows key). The default value for the hidden_state is hide. ------------------------- mode dock|hide|invisible hidden_state hide|show -modifier +modifier |none ------------------------ *Example*: @@ -1248,7 +1306,8 @@ bar { } ---------------- -Available modifiers are Mod1-Mod5, Shift, Control (see +xmodmap(1)+). +Available modifiers are Mod1-Mod5, Shift, Control (see +xmodmap(1)+). You can +also use "none" if you don't want any modifier to trigger this behavior. === Mouse button commands @@ -1337,7 +1396,7 @@ directive multiple times. *Syntax*: --------------- -output +output primary| --------------- *Example*: @@ -1359,7 +1418,19 @@ bar { statusline #ffffff } } + +# show bar on the primary monitor and on HDMI2 +bar { + output primary + output HDMI2 + status_command i3status +} + ------------------------------- +Note that you might not have a primary output configured yet. To do so, run: +------------------------- +xrandr --output --primary +------------------------- === Tray output @@ -1369,6 +1440,11 @@ NetworkManager, VLC, Pidgin, etc. can place little icons. You can configure on which output (monitor) the icons should be displayed or you can turn off the functionality entirely. +You can use multiple +tray_output+ directives in your config to specify a list +of outputs on which you want the tray to appear. The first available output in +that list as defined by the order of the directives will be used for the tray +output. + *Syntax*: --------------------------------- tray_output none|primary| @@ -1529,6 +1605,15 @@ statusline:: Text color to be used for the statusline. separator:: Text color to be used for the separator. +focused_background:: + Background color of the bar on the currently focused monitor output. If + not used, the color will be taken from +background+. +focused_statusline:: + Text color to be used for the statusline on the currently focused + monitor output. If not used, the color will be taken from +statusline+. +focused_separator:: + Text color to be used for the separator on the currently focused + monitor output. If not used, the color will be taken from +separator+. focused_workspace:: Border, background and text color for a workspace button when the workspace has focus. @@ -1624,6 +1709,9 @@ bindsym $mod+x [class="Firefox" window_role="About"] kill # enable floating mode and move container to workspace 4 for_window [class="^evil-app$"] floating enable, move container to workspace 4 + +# move all floating windows to the scratchpad +bindsym $mod+x [floating] move scratchpad ------------------------------------ The criteria which are currently implemented are: @@ -1643,7 +1731,7 @@ window_role:: window_type:: Compare the window type (_NET_WM_WINDOW_TYPE). Possible values are +normal+, +dialog+, +utility+, +toolbar+, +splash+, +menu+, +dropdown_menu+, - +popup_menu+ and +tooltip+. + +popup_menu+, +tooltip+ and +notification+. id:: Compares the X11 window ID, which you can get via +xwininfo+ for example. title:: @@ -1664,7 +1752,12 @@ con_mark:: 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. +floating:: + Only matches floating windows. This criterion requires no value. +tiling:: + Only matches tiling windows. This criterion requires no value. The criteria +class+, +instance+, +role+, +title+, +workspace+ and +mark+ are actually regular expressions (PCRE). See +pcresyntax(3)+ or +perldoc perlre+ for @@ -1680,7 +1773,7 @@ searched in your +$PATH+. See <> for details on the special meaning of +;+ (semicolon) and +,+ (comma): they chain commands together in i3, so you need to use quoted -strings if they appear in your command. +strings (as shown in <>) if they appear in your command. *Syntax*: -------------------------------- @@ -1704,6 +1797,27 @@ launching. So, if an application is not startup-notification aware (most GTK and Qt using applications seem to be, though), you will end up with a watch cursor for 60 seconds. +[[exec_quoting]] +If the command to be executed contains a +;+ (semicolon) and/or a +,+ (comma), +the entire command must be quoted. For example, to have a keybinding for the +shell command +notify-send Hello, i3+, you would add an entry to your +configuration file like this: + +*Example*: +------------------------------ +# Execute a command with a comma in it +bindsym $mod+p exec "notify-send Hello, i3" +------------------------------ + +If however a command with a comma and/or semicolon itself requires quotes, you +must escape the internal quotation marks with double backslashes, like this: + +*Example*: +------------------------------ +# Execute a command with a comma, semicolon and internal quotes +bindsym $mod+p exec "notify-send \\"Hello, i3; from $USER\\"" +------------------------------ + === Splitting containers The split command makes the current window a split container. Split containers @@ -1713,20 +1827,25 @@ 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). Use -+layout toggle split+ to change the layout of any split container from splitv -to splith or vice-versa. +orientation will be changed (if it does not have more than one window). +The +toggle+ option will toggle the orientation of the split container if it +contains a single window. Otherwise it makes the current window a split +container with opposite orientation compared to the parent container. +Use +layout toggle split+ to change the layout of any split container from +splitv to splith or vice-versa. You can also define a custom sequence of layouts +to cycle through with +layout toggle+, see <>. *Syntax*: -------------------------- -split vertical|horizontal -------------------------- +-------------------------------- +split vertical|horizontal|toggle +-------------------------------- *Example*: ------------------------------- +------------------------------- bindsym $mod+v split vertical bindsym $mod+h split horizontal ------------------------------- +bindsym $mod+t split toggle +------------------------------- === Manipulating layout @@ -1734,6 +1853,11 @@ Use +layout toggle split+, +layout stacking+, +layout tabbed+, +layout splitv+ or +layout splith+ to change the current container layout to splith/splitv, stacking, tabbed layout, splitv or splith, respectively. +Specify up to four layouts after +layout toggle+ to cycle through them. Every +time the command is executed, the layout specified after the currently active +one will be applied. If the currently active layout is not in the list, the +first layout in the list will be activated. + To make the current window (!) fullscreen, use +fullscreen enable+ (or +fullscreen enable global+ for the global mode), to leave either fullscreen mode use +fullscreen disable+, and to toggle between these two states use @@ -1746,6 +1870,7 @@ enable+ respectively +floating disable+ (or +floating toggle+): -------------------------------------------- layout default|tabbed|stacking|splitv|splith layout toggle [split|all] +layout toggle [split|tabbed|stacking|splitv|splith] [split|tabbed|stacking|splitv|splith]… -------------------------------------------- *Examples*: @@ -1760,6 +1885,15 @@ bindsym $mod+x layout toggle # Toggle between stacking/tabbed/splith/splitv: bindsym $mod+x layout toggle all +# Toggle between stacking/tabbed/splith: +bindsym $mod+x layout toggle stacking tabbed splith + +# Toggle between splitv/tabbed +bindsym $mod+x layout toggle splitv tabbed + +# Toggle between last split layout/tabbed/stacking +bindsym $mod+x layout toggle split tabbed stacking + # Toggle fullscreen bindsym $mod+f fullscreen toggle @@ -1794,7 +1928,7 @@ output:: ---------------------------------------------- focus left|right|down|up focus parent|child|floating|tiling|mode_toggle -focus output left|right|up|down| +focus output left|right|up|down|primary| ---------------------------------------------- *Examples*: @@ -1816,8 +1950,17 @@ bindsym $mod+x focus output right # Focus the big output bindsym $mod+x focus output HDMI-2 + +# Focus the primary output +bindsym $mod+x focus output primary ------------------------------------------------- +------------------------------- +Note that you might not have a primary output configured yet. To do so, run: +------------------------- +xrandr --output --primary +------------------------- + === Moving containers Use the +move+ command to move a container. @@ -1833,7 +1976,8 @@ 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] +move [absolute] position [px] [px] +move [absolute] position center # Moves the container to the current position of the # mouse cursor. Only affects floating containers. @@ -1859,6 +2003,39 @@ bindsym $mod+c move absolute position center bindsym $mod+m move position mouse ------------------------------------------------------- +=== Swapping containers + +Two containers can be swapped (i.e., move to each other's position) by using +the +swap+ command. They will assume the position and geometry of the container +they are swapped with. + +The first container to participate in the swapping can be selected through the +normal command criteria process with the focused window being the usual +fallback if no criteria are specified. The second container can be selected +using one of the following methods: + ++id+:: The X11 window ID of a client window. ++con_id+:: The i3 container ID of a container. ++mark+:: A container with the specified mark, see <>. + +Note that swapping does not work with all containers. Most notably, swapping +floating containers or containers that have a parent-child relationship to one +another does not work. + +*Syntax*: +---------------------------------------- +swap container with id|con_id|mark +---------------------------------------- + +*Examples*: +----------------------------------------------------------------- +# Swaps the focused container with the container marked »swapee«. +swap container with mark swapee + +# Swaps container marked »A« and »B« +[con_mark="^A$"] swap container with mark B +----------------------------------------------------------------- + === Sticky floating windows If you want a window to stick to the glass, i.e., have it stay on screen even @@ -1883,8 +2060,11 @@ 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 @@ -1912,16 +2092,16 @@ back_and_forth+; likewise, you can move containers to the previously focused workspace using +move container to workspace back_and_forth+. *Syntax*: ------------------------------------ +-------------------------------------------------------------------------------- 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 +move [--no-auto-back-and-forth] [window|container] [to] workspace +move [--no-auto-back-and-forth] [window|container] [to] workspace number move [window|container] [to] workspace prev|next|current ------------------------------------ +-------------------------------------------------------------------------------- *Examples*: ------------------------- @@ -1998,12 +2178,30 @@ i3-msg 'rename workspace to "2: mail"' bindsym $mod+r exec i3-input -F 'rename workspace to "%s"' -P 'New name: ' -------------------------------------------------------------------------- +If you want to rename workspaces on demand while keeping the navigation stable, +you can use a setup like this: + +*Example*: +------------------------- +bindsym $mod+1 workspace number "1: www" +bindsym $mod+2 workspace number "2: mail" +... +------------------------- + +If a workspace does not exist, the command +workspace number "1: mail"+ will +create workspace "1: mail". + +If a workspace with number 1 does already exist, the command will switch to this +workspace and ignore the text part. So even when the workspace has been renamed +to "1: web", the above command will still switch to it. + === Moving workspaces to a different screen See <> for how to move a container/workspace to a different RandR output. [[move_to_outputs]] +[[_moving_containers_workspaces_to_randr_outputs]] === Moving containers/workspaces to RandR outputs To move a container to another RandR output (addressed by names like +LVDS1+ or @@ -2011,10 +2209,10 @@ To move a container to another RandR output (addressed by names like +LVDS1+ or +right+, +up+ or +down+), there are two commands: *Syntax*: ----------------------------------------------------- -move container to output left|right|down|up| -move workspace to output left|right|down|up| ----------------------------------------------------- +------------------------------------------------------------ +move container to output left|right|down|up|current|primary| +move workspace to output left|right|down|up|current|primary| +------------------------------------------------------------ *Examples*: -------------------------------------------------------- @@ -2024,8 +2222,17 @@ bindsym $mod+x move workspace to output right # Put this window on the presentation output. bindsym $mod+x move container to output VGA1 + +# Put this window on the primary output. +bindsym $mod+x move container to output primary -------------------------------------------------------- +------------------------------- +Note that you might not have a primary output configured yet. To do so, run: +------------------------- +xrandr --output --primary +------------------------- + === Moving containers/windows to marks To move a container to another container with a specific mark (see <>), @@ -2069,7 +2276,7 @@ floating containers. 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 +https://github.com/i3/i3/blob/next/etc/config.keycodes[default config] for more context. *Example*: @@ -2132,11 +2339,19 @@ 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 @@ -2150,7 +2365,7 @@ 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 -seperate bindings for a specific set of labels and then only use those labels. +separate bindings for a specific set of labels and then only use those labels. /////////////////////////////////////////////////////////////////// [[pango_markup]] @@ -2163,7 +2378,10 @@ https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup] and the following placeholders which will be replaced: +%title+:: - The X11 window title (_NET_WM_NAME or WM_NAME as fallback). + For normal windows, this is the X11 window title (_NET_WM_NAME or WM_NAME + as fallback). When used on containers without a window (e.g., a split + container inside a tabbed/stacked layout), this will be the tree + representation of the container (e.g., "H[xterm xterm]"). +%class+:: The X11 window class (second part of WM_CLASS). This corresponds to the +class+ criterion, see <>. @@ -2199,6 +2417,10 @@ and +border none+ to make the client borderless. There is also +border toggle+ which will toggle the different border styles. +Note that "pixel" refers to logical pixel. On HiDPI displays, a logical pixel +may be represented by multiple physical pixels, so +pixel 1+ might not +necessarily translate into a single pixel row wide border. + *Syntax*: ----------------------------------------------- border normal|pixel [] @@ -2473,7 +2695,7 @@ have more than one monitor: track of which window you put where. Thus, you can use vim-like marks to quickly switch between windows. See <>. 4. For information on how to move existing workspaces between monitors, - see <<_moving_containers_workspaces_to_randr_outputs>>. + see <>. == i3 and the rest of your software world