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
*Syntax*:
----------------------------------
-bindsym [--release] [<Modifiers>+]<keysym> command
-bindcode [--release] [<Modifiers>+]<keycode> command
+bindsym [--release] [<Group>+][<Modifiers>+]<keysym> command
+bindcode [--release] [<Group>+][<Modifiers>+]<keycode> command
----------------------------------
*Examples*:
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]]
[[no_focus]]
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 <<command_criteria>>.
+this from happening and must be used in combination with <<command_criteria>>.
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
<<focus_on_window_activation>>.
++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 <criteria>
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 <color>
--------------------------
-
-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:
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
force_display_urgency_hint 500 ms
---------------------------------
-=== Delaying exiting on zero displays
-
-Outputs may disappear momentarily and come back later. For example,
-using a docking station that does not announce the undock (e.g. ACPI Undock
-event triggered through manually pushing a button before actually ejecting
-the notebook). During the removal of the notebook from the docking station,
-all outputs disappear momentarily.
-
-To prevent i3 from exiting when no output is available momentarily, you can
-tell i3 to delay a certain time first and check available outputs again using
-the +delay_exit_on_zero_displays+ directive. Setting the value to 0 disables
-this feature.
-
-The default is 500ms.
-
-*Syntax*:
-----------------------------------------
-delay_exit_on_zero_displays <timeout> ms
-----------------------------------------
-
-*Example*:
-----------------------------------
-delay_exit_on_zero_displays 500 ms
-----------------------------------
-
=== Focus on window activation
[[focus_on_window_activation]]
=== Line continuation
-Config files support line continuation, which is indicated by \ before the
-new line character.
+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*:
-------------------
}
# show tray icons on the primary monitor
-tray_output primary
+bar {
+ tray_output primary
+}
# show tray icons on the big monitor
bar {
xrandr --output <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
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).
+ 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.
+ 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 <<vim_like_marks>>.
con_id::
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
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 <<move_to_outputs>> for how to move a container/workspace to a different
RandR output.
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: '
--------------------------------------------------------------------------
*Syntax*:
-------------------------------------------------------
resize grow|shrink <direction> [<px> px [or <ppt> ppt]]
+resize set <width> [px] <height> [px]
-------------------------------------------------------
Direction can either be one of +up+, +down+, +left+ or +right+. Or you can be
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).
+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+:
bindsym $mod+r mode "resize"
----------------------------------------------------------------------
+*Example 2 - setting urxvt size to 640x480:*
+------------------------------------------------
+for_window [class="urxvt"] resize set 640 480
+------------------------------------------------
+
=== Jumping to specific windows
Often when in a multi-monitor environment, you want to quickly jump to a
+%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 <<command_criteria>>.
++%instance+::
+ The X11 window instance (first part of WM_CLASS). This corresponds to the
+ +instance+ criterion, see <<command_criteria>>.
Using the <<for_window>> directive, you can set the title format for any window
based on <<command_criteria>>.