X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fuserguide;h=bfb3da661fc9e69eb3ce13cbb257a8eebf4792a8;hb=50edf495aa3971bfb67471c3aaf2eb72e7abd443;hp=e1e65c24906aabfcee07777ff5c25be306f1a1ed;hpb=d7dcef61d70bea4d3f0b6de5b59435c26aea9b50;p=i3%2Fi3 diff --git a/docs/userguide b/docs/userguide index e1e65c24..bfb3da66 100644 --- a/docs/userguide +++ b/docs/userguide @@ -297,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 @@ -412,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 @@ -424,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 @@ -479,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" @@ -488,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" } ------------------------------------------------------------------------ @@ -754,7 +766,7 @@ considered. *Syntax*: ------------------------------------------------------------ -assign [→] [workspace] +assign [→] [workspace] [number] ------------------------------------------------------------ *Examples*: @@ -771,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 ---------------------- @@ -857,6 +875,18 @@ The 'output' is the name of the RandR output you attach your screen to. On a laptop, you might have VGA1 and LVDS1 as output names. You can see the available outputs by running +xrandr --current+. +If your X server supports RandR 1.5 or newer, i3 will use RandR monitor objects +instead of output objects. Run +xrandr --listmonitors+ to see a list. Usually, +a monitor object contains exactly one output, and has the same name as the +output; but should that not be the case, you may specify the name of either the +monitor or the output in i3's configuration. For example, the Dell UP2414Q uses +two scalers internally, so its output names might be “DP1” and “DP2”, but the +monitor name is “Dell UP2414Q”. + +(Note that even if you specify the name of an output which doesn't span the +entire monitor, i3 will still use the entire area of the containing monitor +rather than that of just the output's.) + If you use named workspaces, they must be quoted: *Examples*: @@ -946,12 +976,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*: -------------------------- @@ -1009,26 +1039,39 @@ popup_during_fullscreen smart === Focus wrapping -When being in a tabbed or stacked container, the first container will be -focused when you use +focus down+ on the last container -- the focus wraps. If -however there is another stacked/tabbed container in that direction, focus will -be set on that container. This is the default behavior so you can navigate to -all your windows without having to use +focus parent+. +By default, when in a container with several windows or child containers, the +opposite window will be focused when trying to move the focus over the edge of +a container (and there are no other containers in that direction) -- the focus +wraps. + +If desired, you can disable this behavior by setting the +focus_wrapping+ +configuration directive to the value +no+. + +When enabled, focus wrapping does not occur by default if there is another +window or container in the specified direction, and focus will instead be set +on that window or container. This is the default behavior so you can navigate +to all your windows without having to use +focus parent+. If you want the focus to *always* wrap and you are aware of using +focus -parent+ to switch to different containers, you can use the -+force_focus_wrapping+ configuration directive. After enabling it, the focus -will always wrap. +parent+ to switch to different containers, you can instead set +focus_wrapping+ +to the value +force+. *Syntax*: --------------------------- -force_focus_wrapping yes|no ---------------------------- +focus_wrapping yes|no|force -*Example*: ------------------------- +# Legacy syntax, equivalent to "focus_wrapping force" force_focus_wrapping yes ------------------------- +--------------------------- + +*Examples*: +----------------- +# Disable focus wrapping +focus_wrapping no + +# Force focus wrapping +focus_wrapping force +----------------- === Forcing Xinerama @@ -1127,9 +1170,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+. @@ -1378,7 +1421,7 @@ directive multiple times. *Syntax*: --------------- -output +output primary| --------------- *Example*: @@ -1400,7 +1443,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 @@ -1802,7 +1857,8 @@ 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. +splitv to splith or vice-versa. You can also define a custom sequence of layouts +to cycle through with +layout toggle+, see <>. *Syntax*: -------------------------------- @@ -1822,6 +1878,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 @@ -1834,6 +1895,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*: @@ -1848,6 +1910,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 @@ -1882,7 +1953,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*: @@ -1904,8 +1975,16 @@ 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. @@ -1948,6 +2027,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 @@ -2090,6 +2202,23 @@ 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 @@ -2105,8 +2234,8 @@ To move a container to another RandR output (addressed by names like +LVDS1+ or *Syntax*: ------------------------------------------------------------ -move container to output left|right|down|up|current| -move workspace to output left|right|down|up|current| +move container to output left|right|down|up|current|primary| +move workspace to output left|right|down|up|current|primary| ------------------------------------------------------------ *Examples*: @@ -2117,8 +2246,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 <>),