From 52d306db2418b7ea3b09f450d75bf71886b4be19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ingo=20B=C3=BCrk?= Date: Sat, 17 Oct 2015 19:59:45 +0200 Subject: [PATCH] Add proper documentation for binding modes. fixes #1996 --- docs/userguide | 106 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 70 insertions(+), 36 deletions(-) diff --git a/docs/userguide b/docs/userguide index c98c25f9..92348fb5 100644 --- a/docs/userguide +++ b/docs/userguide @@ -149,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 @@ -177,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. @@ -441,6 +444,59 @@ bindsym button9 move left bindsym button8 move right -------------------------------- +[[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 @@ -624,6 +680,8 @@ no_focus no_focus [window_role="pop-up"] ------------------------------- +[[variables]] + === Variables As you learned in the section about keyboard bindings, you will have @@ -1455,8 +1513,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. @@ -2023,38 +2081,12 @@ many percentage points a *tiling container* should be grown or shrunk (the default is 10 percentage points). Note that +resize set+ will only work for floating containers. -I recommend using the resize command inside a so called +mode+: +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: 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" -} - -# Enter resize mode -bindsym $mod+r mode "resize" ----------------------------------------------------------------------- - -*Example 2 - setting urxvt size to 640x480:* +*Example*: ------------------------------------------------ for_window [class="urxvt"] resize set 640 480 ------------------------------------------------ @@ -2132,6 +2164,8 @@ 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. /////////////////////////////////////////////////////////////////// +[[pango_markup]] + === Window title format By default, i3 will simply print the X11 window title. Using +title_format+,