diff --git a/docs/modes.png b/docs/modes.png new file mode 100644 index 000000000..656a6dbb9 Binary files /dev/null and b/docs/modes.png differ diff --git a/docs/stacklimit.png b/docs/stacklimit.png new file mode 100644 index 000000000..ab5bed7a6 Binary files /dev/null and b/docs/stacklimit.png differ diff --git a/docs/userguide b/docs/userguide index 0789f56d1..bc73c5b9f 100644 --- a/docs/userguide +++ b/docs/userguide @@ -46,13 +46,22 @@ image:two_columns.png[Two columns] === Changing mode of containers -A container can be in two modes at the moment (more to be implemented later): -+default+ or +stacking+. In default mode, clients are sized so that every client -gets an equal amount of space of the container. In stacking mode, only one -focused client of the container is displayed and you get a list of windows -at the top of the container. +A container can be in different modes: -To switch the mode, press +Mod1+h+ for stacking and +Mod1+e+ for default. +default:: +Windows are sized so that every window gets an equal amount of space of the +container. +stacking:: +Only the focused client of the container is displayed and you get a list of +windows at the top of the container. +tabbed:: +The same principle as +stacking+, but the list of windows at the top is only +a single line which will be vertically split. + +To switch the mode, press +Mod1+e+ for default, +Mod1+h+ for stacking and ++Mod1+w+ for tabbed. + +image:modes.png[Container modes] === Toggling fullscreen mode for a window @@ -102,12 +111,14 @@ To move a window to another workspace, simply press +Mod1+Shift+num+ where Similarly to switching workspaces, the target workspace will be created if it does not yet exist. -=== Resizing columns +=== Resizing columns/rows -To resize columns just grab the border between the two columns and move it to -the wanted size. +To resize columns or rows just grab the border between the two columns/rows +and move it to the wanted size. Please keep in mind that each cell of the table +holds a +container+ and thus you cannot horizontally resize single windows. -A command for doing this via keyboard will be implemented soon. +See <> for how to configure i3 to be able to resize +columns/rows with your keyboard. === Restarting i3 inplace @@ -246,6 +257,22 @@ floating_modifier floating_modifier Mod1 -------------------------------- +=== Layout mode for new containers + +This option is only available when using the new lexer/parser (pass +-l+ to i3 +when starting). It determines in which mode new containers will start. See also +<>. + +*Syntax*: +--------------------------------------------- +new_container +new_container stack-limit +--------------------------------------------- + +*Examples*: +--------------------- +new_container tabbed +--------------------- === Variables @@ -420,20 +447,21 @@ section. === Manipulating layout -To change the layout of the current container to stacking or back to default -layout, use +s+ or +d+. To make the current client (!) fullscreen, use +f+, to -make it floating (or tiling again) use +t+: +To change the layout of the current container to stacking, use +s+, for default +use +d+ and for tabbed, use +T+. To make the current client (!) fullscreen, +use +f+, to make it floating (or tiling again) use +t+: *Examples*: -------------- -bind Mod1+s s -bind Mod1+l d +bindsym Mod1+s s +bindsym Mod1+l d +bindsym Mod1+w T # Toggle fullscreen -bind Mod1+f f +bindsym Mod1+f f # Toggle floating/tiling -bind Mod1+t t +bindsym Mod1+t t -------------- === Focussing/Moving/Snapping clients/containers/screens @@ -494,6 +522,39 @@ bindsym Mod1+o nw bindsym Mod1+p pw ------------------------- +[[resizingconfig]] + +=== Resizing columns/rows + +If you want to resize columns/rows using your keyboard, you can use the ++resize+ command, I recommend using it a +mode+ (you need to use the new +lexer/parser for that, so pass +-l+ to i3 when starting): + +.Example: Configuration file, defining a mode for resizing +---------------------------------------------------------------------- +mode "resize" { + # These bindings trigger as soon as you enter the resize mode + + # They resize the border in the direction you pressed, e.g. + # when pressing left, the window is resized so that it has + # more space on its left + + bindsym n resize left -10 + bindsym Shift+n resize left +10 + + bindsym r resize bottom +10 + bindsym Shift+r resize bottom -10 + + bindsym t resize top -10 + bindsym Shift+t resize top +10 + + bindsym d resize right +10 + bindsym Shift+d resize right -10 + + bind 36 mode default +} +---------------------------------------------------------------------- + === Jumping to specific windows Especially when in a multi-monitor environment, you want to quickly jump to a specific @@ -517,6 +578,37 @@ or you can specify the position of the client if you always use the same layout. bindsym Mod1+a jump "urxvt/VIM" -------------------------------------- +=== 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 +focus to the windows). However, you can directly mark a specific window with +an arbitrary label and use it afterwards, that is, you do not need to ensure +that your windows have unique classes or titles and you do not need to change +your configuration file. + +As the command needs to include the label with which you want to mark the +window, you cannot simply bind it to a key (or, you could bind it to a key and +only use the set of labels for which you created bindings). +i3-input+ is a +tool created 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. + +*Syntax*: +----------------- +mark +goto +----------------- + +*Examples*: +--------------------------------------- +# Read 1 character and mark the current window with this character +bindsym Mod1+m exec i3-input -p 'mark ' -l 1 -P 'Mark: ' + +# Read 1 character and go to the window with the character +bindsym Mod1+g exec i3-input -p 'goto ' -l 1 -P 'Goto: ' +--------------------------------------- + === Traveling the focus stack This mechanism can be thought of as the opposite of the +jump+ command. It travels @@ -544,7 +636,8 @@ ft:: To change the border of the current client, you can use +bn+ to use the normal border (including window title), +bp+ to use a 1-pixel border (no window title) -and +bb+ to make the client borderless. +and +bb+ to make the client borderless. There also is +bt+ which will toggle +the different border styles. *Examples*: ------------------ @@ -553,6 +646,35 @@ bindsym Mod1+y bp bindsym Mod1+u bb ------------------ +[[stack-limit]] + +=== Changing the stack-limit of a container + +If you have a single container with a lot of windows inside (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 only using half of the +titlebars of each window in the container. + +Using the +stack-limit+ command, you can limit the amount of rows or columns +in a stacking container. i3 will create columns or rows (depending on what +you limited) automatically as needed. + +*Syntax*: +-------------------------------- +stack-limit +-------------------------------- + +*Examples*: +------------------- +# I always want to have two window titles in one line +stack-limit cols 2 + +# Not more than 5 rows in this stacking container +stack-limit rows 5 +------------------- + +image:stacklimit.png[Container limited to two columns] + === Reloading/Restarting/Exiting You can make i3 reload its configuration file with +reload+. You can also