<head>\r
<link rel="icon" type="image/x-icon" href="/favicon.ico">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.9" />\r
+<meta name="generator" content="AsciiDoc 8.6.10" />\r
<title>i3: i3 User’s Guide</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
you open a new terminal, it will open below the current one.</p></div>\r
<div class="paragraph"><p>So, how can you open a new terminal window to the <strong>right</strong> of the current one?\r
The solution is to use <tt>focus parent</tt>, which will focus the <tt>Parent Container</tt> of\r
-the current <tt>Container</tt>. In this case, you would focus the <tt>Vertical Split\r
-Container</tt> which is <strong>inside</strong> the horizontally oriented workspace. Thus, now new\r
-windows will be opened to the right of the <tt>Vertical Split Container</tt>:</p></div>\r
+the current <tt>Container</tt>. In default configuration, use <tt>$mod+a</tt> to navigate one\r
+<tt>Container</tt> up the tree (you can repeat this multiple times until you get to the\r
+<tt>Workspace Container</tt>). In this case, you would focus the <tt>Vertical Split Container</tt>\r
+which is <strong>inside</strong> the horizontally oriented workspace. Thus, now new windows will be\r
+opened to the right of the <tt>Vertical Split Container</tt>:</p></div>\r
<div class="imageblock">\r
<div class="content">\r
<img src="tree-shot3.png" alt="shot3" />\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_default_border_style_for_new_windows">4.10. Default border style for new windows</h3>\r
+<h3 id="_window_title_alignment">4.10. Window title alignment</h3>\r
+<div class="paragraph"><p>This option determines the window title’s text alignment.\r
+Default is <tt>left</tt></p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>title_align left|center|right</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_default_border_style_for_new_windows">4.11. Default border style for new windows</h3>\r
<div class="paragraph"><p>This option determines which border style new windows will have. The default is\r
<tt>normal</tt>. Note that default_floating_border applies only to windows which are starting out as\r
floating windows, e.g., dialog windows, but not windows that are floated later on.</p></div>\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_hiding_vertical_borders">4.11. Hiding borders adjacent to the screen edges</h3>\r
+<h3 id="_hiding_vertical_borders">4.12. Hiding borders adjacent to the screen edges</h3>\r
<div class="paragraph"><p>You can hide container borders adjacent to the screen edges using\r
<tt>hide_edge_borders</tt>. This is useful if you are using scrollbars, or do not want\r
to waste even two pixels in displayspace. The "smart" setting hides borders on\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="for_window">4.12. Arbitrary commands for specific windows (for_window)</h3>\r
+<h3 id="for_window">4.13. Arbitrary commands for specific windows (for_window)</h3>\r
<div class="paragraph"><p>With the <tt>for_window</tt> command, you can let i3 execute any command when it\r
encounters a specific window. This can be used to set windows to floating or to\r
change their border style, for example.</p></div>\r
<div class="paragraph"><p>The valid criteria are the same as those for commands, see <a href="#command_criteria">[command_criteria]</a>.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="no_focus">4.13. Don’t focus window upon opening</h3>\r
+<h3 id="no_focus">4.14. Don’t focus window upon opening</h3>\r
<div class="paragraph"><p>When a new window appears, it will be focused. The <tt>no_focus</tt> directive allows preventing\r
this from happening and must be used in combination with <a href="#command_criteria">[command_criteria]</a>.</p></div>\r
<div class="paragraph"><p>Note that this does not apply to all cases, e.g., when feeding data into a running application\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="variables">4.14. Variables</h3>\r
+<h3 id="variables">4.15. Variables</h3>\r
<div class="paragraph"><p>As you learned in the section about keyboard bindings, you will have\r
to configure lots of bindings containing modifier keys. If you want to save\r
yourself some typing and be able to change the modifier you use later,\r
loaded from the X resource database.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="xresources">4.15. X resources</h3>\r
+<h3 id="xresources">4.16. X resources</h3>\r
<div class="paragraph"><p><a href="#variables">[variables]</a> can also be created using a value configured in the X resource\r
database. This is useful, for example, to avoid configuring color values within\r
the i3 configuration. Instead, the values can be configured, once, in the X\r
resource database to achieve an easily maintainable, consistent color theme\r
across many X applications.</p></div>\r
<div class="paragraph"><p>Defining a resource will load this resource from the resource database and\r
-assign its value to the specified variable. A fallback must be specified in\r
+assign its value to the specified variable. This is done verbatim and the value\r
+must therefore be in the format that i3 uses. A fallback must be specified in\r
case the resource cannot be loaded from the database.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="assign_workspace">4.16. Automatically putting clients on specific workspaces</h3>\r
+<h3 id="assign_workspace">4.17. Automatically putting clients on specific workspaces</h3>\r
<div class="paragraph"><p>To automatically make a specific window show up on a specific workspace, you\r
can use an <strong>assignment</strong>. You can match windows by using any criteria,\r
-see <a href="#command_criteria">[command_criteria]</a>. It is recommended that you match on window classes\r
-(and instances, when appropriate) instead of window titles whenever possible\r
-because some applications first create their window, and then worry about\r
-setting the correct title. Firefox with Vimperator comes to mind. The window\r
-starts up being named Firefox, and only when Vimperator is loaded does the\r
-title change. As i3 will get the title as soon as the application maps the\r
-window (mapping means actually displaying it on the screen), you’d need to have\r
-to match on <em>Firefox</em> in this case.</p></div>\r
+see <a href="#command_criteria">[command_criteria]</a>. The difference between <tt>assign</tt> and\r
+<tt>for_window <criteria> move to workspace</tt> is that the former will only be\r
+executed when the application maps the window (mapping means actually displaying\r
+it on the screen) but the latter will be executed whenever a window changes its\r
+properties to something that matches the specified criteria.</p></div>\r
+<div class="paragraph"><p>Thus, it is recommended that you match on window classes (and instances, when\r
+appropriate) instead of window titles whenever possible because some\r
+applications first create their window, and then worry about setting the correct\r
+title. Firefox with Vimperator comes to mind. The window starts up being named\r
+Firefox, and only when Vimperator is loaded does the title change. As i3 will\r
+get the title as soon as the application maps the window, you’d need to have to\r
+match on <em>Firefox</em> in this case.\r
+Another known issue is with Spotify, which doesn’t set the class hints when\r
+mapping the window, meaning you’ll have to use a <tt>for_window</tt> rule to assign\r
+Spotify to a specific workspace.\r
+Finally, using <tt>assign [tiling]</tt> and <tt>assign [floating]</tt> is not supported.</p></div>\r
<div class="paragraph"><p>You can also assign a window to show up on a specific output. You can use RandR\r
names such as <tt>VGA1</tt> or names relative to the output with the currently focused\r
workspace such as <tt>left</tt> and <tt>down</tt>.</p></div>\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_automatically_starting_applications_on_i3_startup">4.17. Automatically starting applications on i3 startup</h3>\r
+<h3 id="_automatically_starting_applications_on_i3_startup">4.18. Automatically starting applications on i3 startup</h3>\r
<div class="paragraph"><p>By using the <tt>exec</tt> keyword outside a keybinding, you can configure\r
which commands will be performed by i3 on initial startup. <tt>exec</tt>\r
commands will not run when restarting i3, if you need a command to run\r
<div class="paragraph"><p>The flag --no-startup-id is explained in <a href="#exec">[exec]</a>.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="workspace_screen">4.18. Automatically putting workspaces on specific screens</h3>\r
+<h3 id="workspace_screen">4.19. Automatically putting workspaces on specific screens</h3>\r
<div class="paragraph"><p>If you assign clients to workspaces, it might be handy to put the\r
workspaces on specific screens. Also, the assignment of workspaces to screens\r
will determine which workspace i3 uses for a new screen when adding screens\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>workspace <workspace> output <output></tt></pre>\r
+<pre><tt>workspace <workspace> output <output1> [output2]…</tt></pre>\r
</div></div>\r
<div class="paragraph"><p>The <em>output</em> is the name of the RandR output you attach your screen to. On a\r
laptop, you might have VGA1 and LVDS1 as output names. You can see the\r
<div class="paragraph"><p>(Note that even if you specify the name of an output which doesn’t span the\r
entire monitor, i3 will still use the entire area of the containing monitor\r
rather than that of just the output’s.)</p></div>\r
+<div class="paragraph"><p>You can specify multiple outputs. The first available will be used.</p></div>\r
<div class="paragraph"><p>If you use named workspaces, they must be quoted:</p></div>\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>workspace 1 output LVDS1\r
-workspace 5 output VGA1\r
+workspace 2 output primary\r
+workspace 5 output VGA1 LVDS1\r
workspace "2: vim" output VGA1</tt></pre>\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_changing_colors">4.19. Changing colors</h3>\r
+<h3 id="_changing_colors">4.20. Changing colors</h3>\r
<div class="paragraph"><p>You can change all colors which i3 uses to draw the window decorations.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
from single windows outside of a split container.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_interprocess_communication">4.20. Interprocess communication</h3>\r
+<h3 id="_interprocess_communication">4.21. Interprocess communication</h3>\r
<div class="paragraph"><p>i3 uses Unix sockets to provide an IPC interface. This allows third-party\r
programs to get information from i3, such as the current workspaces\r
(to display a workspace bar), and to control i3.</p></div>\r
<pre><tt>ipc-socket ~/.i3/i3-ipc.sock</tt></pre>\r
</div></div>\r
<div class="paragraph"><p>You can then use the <tt>i3-msg</tt> application to perform any command listed in\r
-the next section.</p></div>\r
+<a href="#list_of_commands">[list_of_commands]</a>.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_focus_follows_mouse">4.21. Focus follows mouse</h3>\r
+<h3 id="_focus_follows_mouse">4.22. Focus follows mouse</h3>\r
<div class="paragraph"><p>By default, window focus follows your mouse movements as the mouse crosses\r
window borders. However, if you have a setup where your mouse usually is in your\r
way (like a touchpad on your laptop which you do not want to disable\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_mouse_warping">4.22. Mouse warping</h3>\r
+<h3 id="_mouse_warping">4.23. Mouse warping</h3>\r
<div class="paragraph"><p>By default, when switching focus to a window on a different output (e.g.\r
focusing a window on workspace 3 on output VGA-1, coming from workspace 2 on\r
LVDS-1), the mouse cursor is warped to the center of that window.</p></div>\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_popups_during_fullscreen_mode">4.23. Popups during fullscreen mode</h3>\r
+<h3 id="_popups_during_fullscreen_mode">4.24. Popups during fullscreen mode</h3>\r
<div class="paragraph"><p>When you are in fullscreen mode, some applications still open popup windows\r
(take Xpdf for example). This is because these applications may not be aware\r
that they are in fullscreen mode (they do not check the corresponding hint).\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_focus_wrapping">4.24. Focus wrapping</h3>\r
+<h3 id="_focus_wrapping">4.25. Focus wrapping</h3>\r
<div class="paragraph"><p>By default, when in a container with several windows or child containers, the\r
opposite window will be focused when trying to move the focus over the edge of\r
a container (and there are no other containers in that direction) — the focus\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_forcing_xinerama">4.25. Forcing Xinerama</h3>\r
+<h3 id="_forcing_xinerama">4.26. Forcing Xinerama</h3>\r
<div class="paragraph"><p>As explained in-depth in <a href="https://i3wm.org/docs/multi-monitor.html">https://i3wm.org/docs/multi-monitor.html</a>, some X11\r
video drivers (especially the nVidia binary driver) only provide support for\r
Xinerama instead of RandR. In such a situation, i3 must be told to use the\r
Xinerama, instead they are counted up, starting at 0: <tt>xinerama-0</tt>, <tt>xinerama-1</tt>, …</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_automatic_back_and_forth_when_switching_to_the_current_workspace">4.26. Automatic back-and-forth when switching to the current workspace</h3>\r
+<h3 id="workspace_auto_back_and_forth">4.27. Automatic back-and-forth when switching to the current workspace</h3>\r
<div class="paragraph"><p>This configuration directive enables automatic <tt>workspace back_and_forth</tt> (see\r
<a href="#back_and_forth">[back_and_forth]</a>) when switching to the workspace that is currently focused.</p></div>\r
<div class="paragraph"><p>For instance: Assume you are on workspace "1: www" and switch to "2: IM" using\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_delaying_urgency_hint_reset_on_workspace_change">4.27. Delaying urgency hint reset on workspace change</h3>\r
+<h3 id="_delaying_urgency_hint_reset_on_workspace_change">4.28. Delaying urgency hint reset on workspace change</h3>\r
<div class="paragraph"><p>If an application on another workspace sets an urgency hint, switching to this\r
workspace may lead to immediate focus of the application, which also means the\r
window decoration color would be immediately reset to <tt>client.focused</tt>. This\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="focus_on_window_activation">4.28. Focus on window activation</h3>\r
+<h3 id="focus_on_window_activation">4.29. Focus on window activation</h3>\r
<div class="paragraph"><p>If a window is activated, e.g., via <tt>google-chrome www.google.com</tt>, it may request\r
to take focus. Since this may not preferable, different reactions can be configured.</p></div>\r
<div class="paragraph"><p>Note that this may not affect windows that are being opened. To prevent new windows\r
</dl></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="show_marks">4.29. Drawing marks on window decoration</h3>\r
+<h3 id="show_marks">4.30. Drawing marks on window decoration</h3>\r
<div class="paragraph"><p>If activated, marks (see <a href="#vim_like_marks">[vim_like_marks]</a>) on windows are drawn in their window\r
decoration. However, any mark starting with an underscore in its name (<tt>_</tt>) will\r
not be drawn even if this option is activated.</p></div>\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="line_continuation">4.30. Line continuation</h3>\r
+<h3 id="line_continuation">4.31. Line continuation</h3>\r
<div class="paragraph"><p>Config files support line continuation, meaning when you end a line in a\r
backslash character (<tt>\</tt>), the line-break will be ignored by the parser. This\r
feature can be used to create more readable configuration files.\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_strip_workspace_numbers">5.13. Strip workspace numbers</h3>\r
+<h3 id="_strip_workspace_numbers_name">5.13. Strip workspace numbers/name</h3>\r
<div class="paragraph"><p>Specifies whether workspace numbers should be displayed within the workspace\r
buttons. This is useful if you want to have a named workspace that stays in\r
order on the bar according to its number without displaying the number prefix.</p></div>\r
the form "[n]:[NAME]" will display only the name. You could use this, for\r
instance, to display Roman numerals rather than digits by naming your\r
workspaces to "1:I", "2:II", "3:III", "4:IV", …</p></div>\r
+<div class="paragraph"><p>When <tt>strip_workspace_name</tt> is set to <tt>yes</tt>, any workspace that has a name of\r
+the form "[n]:[NAME]" will display only the number.</p></div>\r
<div class="paragraph"><p>The default is to display the full name within the workspace button.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>strip_workspace_numbers yes|no</tt></pre>\r
+<pre><tt>strip_workspace_numbers yes|no\r
+strip_workspace_name yes|no</tt></pre>\r
</div></div>\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
<div class="listingblock">\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_list_of_commands">6. List of commands</h2>\r
+<h2 id="list_of_commands">6. List of commands</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Commands are what you bind to specific keypresses. You can also issue commands\r
at runtime without pressing a key by using the IPC interface. An easy way to\r
# defaults to 10 pixels.\r
move <left|right|down|up> [<px> px]\r
\r
-# Moves the container either to a specific location\r
-# or to the center of the screen. If 'absolute' is\r
-# used, it is moved to the center of all outputs.\r
-move [absolute] position <pos_x> [px] <pos_y> [px]\r
+# Moves the container to the specified pos_x and pos_y\r
+# coordinates on the screen.\r
+move position <pos_x> [px] <pos_y> [px]\r
+\r
+# Moves the container to the center of the screen.\r
+# If 'absolute' is used, it is moved to the center of\r
+# all outputs.\r
move [absolute] position center\r
\r
# Moves the container to the current position of the\r
<h3 id="_changing_named_workspaces_moving_to_workspaces">6.8. Changing (named) workspaces/moving to workspaces</h3>\r
<div class="paragraph"><p>To change to a specific workspace, use the <tt>workspace</tt> command, followed by the\r
number or name of the workspace. Pass the optional flag\r
-<tt>--no-auto-back-and-forth</tt> to disable <a href="#back_and_forth">[back_and_forth]</a> for this specific call\r
-only.</p></div>\r
+<tt>--no-auto-back-and-forth</tt> to disable <a href="#workspace_auto_back_and_forth">[workspace_auto_back_and_forth]</a> for this\r
+specific call only.</p></div>\r
<div class="paragraph"><p>To move containers to specific workspaces, use <tt>move container to workspace</tt>.</p></div>\r
<div class="paragraph"><p>You can also switch to the next and previous workspace with the commands\r
<tt>workspace next</tt> and <tt>workspace prev</tt>, which is handy, for example, if you have\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>resize grow|shrink <direction> [<px> px [or <ppt> ppt]]\r
-resize set <width> [px | ppt] <height> [px | ppt]</tt></pre>\r
+resize set [width] <width> [px | ppt]\r
+resize set height <height> [px | ppt]\r
+resize set [width] <width> [px | ppt] [height] <height> [px | ppt]</tt></pre>\r
</div></div>\r
<div class="paragraph"><p>Direction can either be one of <tt>up</tt>, <tt>down</tt>, <tt>left</tt> or <tt>right</tt>. Or you can be\r
-less specific and use <tt>width</tt> or <tt>height</tt>, in which case i3 will take/give\r
-space from all the other containers. The optional pixel argument specifies by\r
-how many pixels a <strong>floating container</strong> should be grown or shrunk (the default\r
-is 10 pixels). The ppt argument means percentage points and specifies by how\r
-many percentage points a <strong>tiling container</strong> should be grown or shrunk (the\r
-default is 10 percentage points).</p></div>\r
-<div class="paragraph"><p>Notes about <tt>resize set</tt>: a value of 0 for <width> or <height> means "do\r
-not resize in this direction", and resizing a tiling container by <tt>px</tt> is not\r
-implemented.</p></div>\r
+less specific and use <tt>width</tt> or <tt>height</tt>, in which case i3 will take/give space\r
+from all the other containers. The optional pixel argument specifies by how many\r
+pixels a container should be grown or shrunk (the default is 10 pixels). The\r
+optional ppt argument means "percentage points", and if specified it indicates\r
+that a <strong>tiling container</strong> should be grown or shrunk by that many points, instead\r
+of by the <tt>px</tt> value.</p></div>\r
+<div class="paragraph"><p>Note about <tt>resize set</tt>: a value of 0 for <width> or <height> means "do not\r
+resize in this direction".</p></div>\r
<div class="paragraph"><p>It is recommended to define bindings for resizing in a dedicated binding mode.\r
See <a href="#binding_modes">[binding_modes]</a> and the example in the i3\r
<a href="https://github.com/i3/i3/blob/next/etc/config.keycodes">default config</a> for more\r
<div class="paragraph"><p>To change the border of the current client, you can use <tt>border normal</tt> to use the normal\r
border (including window title), <tt>border pixel 1</tt> to use a 1-pixel border (no window title)\r
and <tt>border none</tt> to make the client borderless.</p></div>\r
-<div class="paragraph"><p>There is also <tt>border toggle</tt> which will toggle the different border styles.</p></div>\r
+<div class="paragraph"><p>There is also <tt>border toggle</tt> which will toggle the different border styles. The\r
+optional pixel argument can be used to specify the border width when switching\r
+to the normal and pixel styles.</p></div>\r
<div class="paragraph"><p>Note that "pixel" refers to logical pixel. On HiDPI displays, a logical pixel\r
may be represented by multiple physical pixels, so <tt>pixel 1</tt> might not\r
necessarily translate into a single pixel row wide border.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>border normal|pixel [<n>]\r
-border none|toggle\r
+<pre><tt>border normal|pixel|toggle [<n>]\r
+border none\r
\r
# legacy syntax, equivalent to "border pixel 1"\r
border 1pixel</tt></pre>\r
projects / i3 / i3.github.io / blobdiff