<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
<h1>i3 User’s Guide</h1>\r
<span id="author">Michael Stapelberg</span><br />\r
<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
-<span id="revdate">March 2013</span>\r
-<div id="toc">
- <div id="toctitle">Table of Contents</div>
- <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
+<div id="toc">\r
+ <div id="toctitle">Table of Contents</div>\r
+ <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>\r
</div>\r
</div>\r
<div id="preamble">\r
<h2 id="_default_keybindings">1. Default keybindings</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>For the "too long; didn’t read" people, here is an overview of the default\r
-keybindings (click to see the full size image):</p></div>\r
+keybindings (click to see the full-size image):</p></div>\r
<div class="paragraph"><p><strong>Keys to use with $mod (Alt):</strong></p></div>\r
<div class="paragraph"><p><span class="image">\r
<a class="image" href="keyboard-layer1.png">\r
<div class="sectionbody">\r
<div class="paragraph"><p>Throughout this guide, the keyword <tt>$mod</tt> will be used to refer to the\r
configured modifier. This is the Alt key (<tt>Mod1</tt>) by default, with the Windows\r
-key (<tt>Mod4</tt>) being a popular alternative.</p></div>\r
+key (<tt>Mod4</tt>) being a popular alternative that largely prevents conflicts with\r
+application-defined shortcuts.</p></div>\r
<div class="sect2">\r
<h3 id="_opening_terminals_and_moving_around">2.1. Opening terminals and moving around</h3>\r
<div class="paragraph"><p>One very basic operation is opening a new terminal. By default, the keybinding\r
out to be complicated to use (snapping), understand and implement.</p></div>\r
<div class="sect2">\r
<h3 id="_the_tree_consists_of_containers">3.1. The tree consists of Containers</h3>\r
-<div class="paragraph"><p>The building blocks of our tree are so called <tt>Containers</tt>. A <tt>Container</tt> can\r
+<div class="paragraph"><p>The building blocks of our tree are so-called <tt>Containers</tt>. A <tt>Container</tt> can\r
host a window (meaning an X11 window, one that you can actually see and use,\r
like a browser). Alternatively, it could contain one or more <tt>Containers</tt>. A\r
simple example is the workspace: When you start i3 with a single monitor, a\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 class="sect2">\r
<h3 id="floating_modifier">4.6. The floating modifier</h3>\r
<div class="paragraph"><p>To move floating windows with your mouse, you can either grab their titlebar\r
-or configure the so called floating modifier which you can then press and\r
+or configure the so-called floating modifier which you can then press and\r
click anywhere in the window itself to move it. The most common setup is to\r
use the same key you use for managing windows (Mod1 for example). Then\r
you can press Mod1, click into a window using your left mouse button, and drag\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_border_style_for_new_windows">4.10. 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 new_float applies only to windows which are starting out as\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 class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>new_window normal|none|pixel\r
-new_window normal|pixel <px>\r
-new_float normal|none|pixel\r
-new_float normal|pixel <px></tt></pre>\r
+<pre><tt>default_border normal|none|pixel\r
+default_border normal|pixel <px>\r
+default_floating_border normal|none|pixel\r
+default_floating_border normal|pixel <px></tt></pre>\r
</div></div>\r
+<div class="paragraph"><p>Please note that <tt>new_window</tt> and <tt>new_float</tt> have been deprecated in favor of the above options\r
+and will be removed in a future release. We strongly recommend using the new options instead.</p></div>\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>new_window pixel</tt></pre>\r
+<pre><tt>default_border pixel</tt></pre>\r
</div></div>\r
<div class="paragraph"><p>The "normal" and "pixel" border styles support an optional border width in\r
pixels:</p></div>\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt># The same as new_window none\r
-new_window pixel 0\r
+<pre><tt># The same as default_border none\r
+default_border pixel 0\r
\r
# A 3 px border\r
-new_window pixel 3</tt></pre>\r
+default_border pixel 3</tt></pre>\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 class="paragraph"><p>Assignments are processed by i3 in the order in which they appear in the config\r
file. The first one which matches the window wins and later assignments are not\r
considered.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>assign <criteria> [→] [workspace] <workspace></tt></pre>\r
+<pre><tt>assign <criteria> [→] [workspace] [number] <workspace>\r
+assign <criteria> [→] output left|right|up|down|primary|<output></tt></pre>\r
</div></div>\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
# Assignment to a named workspace\r
assign [class="^URxvt$"] → work\r
\r
+# Assign to the workspace with number 2, regardless of name\r
+assign [class="^URxvt$"] → number 2\r
+\r
+# You can also specify a number + name. If the workspace with number 2 exists, assign will skip the text part.\r
+assign [class="^URxvt$"] → number "2: work"\r
+\r
# Start urxvt -name irssi\r
-assign [class="^URxvt$" instance="^irssi$"] → 3</tt></pre>\r
+assign [class="^URxvt$" instance="^irssi$"] → 3\r
+\r
+# Assign urxvt to the output right of the current one\r
+assign [class="^URxvt$"] → output right\r
+\r
+# Assign urxvt to the primary output\r
+assign [class="^URxvt$"] → output primary</tt></pre>\r
</div></div>\r
-<div class="paragraph"><p>Note that the arrow is not required, it just looks good :-). If you decide to\r
+<div class="paragraph"><p>Note that you might not have a primary output configured yet. To do so, run:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>xrandr --output <output> --primary</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Also, the arrow is not required, it just looks good :-). If you decide to\r
use it, it has to be a UTF-8 encoded arrow, not <tt>-></tt> or something like that.</p></div>\r
<div class="paragraph"><p>To get the class and instance, you can use <tt>xprop</tt>. After clicking on the\r
window, you will see the following output:</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
-<div class="paragraph"><p>When being in a tabbed or stacked container, the first container will be\r
-focused when you use <tt>focus down</tt> on the last container — the focus wraps. If\r
-however there is another stacked/tabbed container in that direction, focus will\r
-be set on that container. This is the default behavior so you can navigate to\r
-all your windows without having to use <tt>focus parent</tt>.</p></div>\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
+wraps.</p></div>\r
+<div class="paragraph"><p>If desired, you can disable this behavior by setting the <tt>focus_wrapping</tt>\r
+configuration directive to the value <tt>no</tt>.</p></div>\r
+<div class="paragraph"><p>When enabled, focus wrapping does not occur by default if there is another\r
+window or container in the specified direction, and focus will instead be set\r
+on that window or container. This is the default behavior so you can navigate\r
+to all your windows without having to use <tt>focus parent</tt>.</p></div>\r
<div class="paragraph"><p>If you want the focus to <strong>always</strong> wrap and you are aware of using <tt>focus\r
-parent</tt> to switch to different containers, you can use the\r
-<tt>force_focus_wrapping</tt> configuration directive. After enabling it, the focus\r
-will always wrap.</p></div>\r
+parent</tt> to switch to different containers, you can instead set <tt>focus_wrapping</tt>\r
+to the value <tt>force</tt>.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>force_focus_wrapping yes|no</tt></pre>\r
+<pre><tt>focus_wrapping yes|no|force\r
+\r
+# Legacy syntax, equivalent to "focus_wrapping force"\r
+force_focus_wrapping yes</tt></pre>\r
</div></div>\r
-<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>force_focus_wrapping yes</tt></pre>\r
+<pre><tt># Disable focus wrapping\r
+focus_wrapping no\r
+\r
+# Force focus wrapping\r
+focus_wrapping force</tt></pre>\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 class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>bindsym button<n> <command></tt></pre>\r
+<pre><tt>bindsym [--release] button<n> <command></tt></pre>\r
</div></div>\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
<div class="listingblock">\r
<pre><tt>bar {\r
# disable clicking on workspace buttons\r
bindsym button1 nop\r
+ # Take a screenshot by right clicking on the bar\r
+ bindsym --release button3 exec --no-startup-id import /tmp/latest-screenshot.png\r
# execute custom script when scrolling downwards\r
bindsym button5 exec ~/.i3/scripts/custom_wheel_down\r
}</tt></pre>\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
available:</p></div>\r
<div class="dlist"><dl>\r
<dt class="hdlist1">\r
+<criteria>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Sets focus to the container that matches the specified criteria.\r
+ See <a href="#command_criteria">[command_criteria]</a>.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
left|right|up|down\r
</dt>\r
<dd>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>focus left|right|down|up\r
+<pre><tt><criteria> focus\r
+focus left|right|down|up\r
focus parent|child|floating|tiling|mode_toggle\r
focus output left|right|up|down|primary|<output></tt></pre>\r
</div></div>\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt># Focus container on the left, bottom, top, right\r
+<pre><tt># Focus firefox\r
+bindsym $mod+F1 [class="Firefox"] focus\r
+\r
+# Focus container on the left, bottom, top, right\r
bindsym $mod+j focus left\r
bindsym $mod+k focus down\r
bindsym $mod+l focus up\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
RandR output.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_moving_containers_workspaces_to_randr_outputs">6.10. Moving containers/workspaces to RandR outputs</h3>\r
+<h3 id="move_to_outputs">6.10. <a id="_moving_containers_workspaces_to_randr_outputs"></a>Moving containers/workspaces to RandR outputs</h3>\r
<div class="paragraph"><p>To move a container to another RandR output (addressed by names like <tt>LVDS1</tt> or\r
<tt>VGA1</tt>) or to a RandR output identified by a specific direction (like <tt>left</tt>,\r
<tt>right</tt>, <tt>up</tt> or <tt>down</tt>), there are two commands:</p></div>\r
# Put this window on the primary output.\r
bindsym $mod+x move container to output primary</tt></pre>\r
</div></div>\r
+<div class="paragraph"><p>Note that you might not have a primary output configured yet. To do so, run:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>Note that you might not have a primary output configured yet. To do so, run:</tt></pre>\r
+<pre><tt>xrandr --output <output> --primary</tt></pre>\r
</div></div>\r
-<div class="paragraph"><p>xrandr --output <output> --primary</p></div>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>=== Moving containers/windows to marks\r
-\r
-To move a container to another container with a specific mark (see <<vim_like_marks>>),\r
-you can use the following command.\r
-\r
-The window will be moved right after the marked container in the tree, i.e., it ends up\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_moving_containers_windows_to_marks">6.11. Moving containers/windows to marks</h3>\r
+<div class="paragraph"><p>To move a container to another container with a specific mark (see <a href="#vim_like_marks">[vim_like_marks]</a>),\r
+you can use the following command.</p></div>\r
+<div class="paragraph"><p>The window will be moved right after the marked container in the tree, i.e., it ends up\r
in the same position as if you had opened a new window when the marked container was\r
focused. If the mark is on a split container, the window will appear as a new child\r
-after the currently focused child within that container.\r
-\r
-*Syntax*:</tt></pre>\r
+after the currently focused child within that container.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>move window|container to mark <mark></tt></pre>\r
</div></div>\r
-</div>\r
-</div>\r
-</div>\r
-<div class="sect1">\r
-<h2 id="_move_window_container_to_mark_lt_mark_gt">7. move window|container to mark <mark></h2>\r
-<div class="sectionbody">\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>for_window [instance="tabme"] move window to mark target</tt></pre>\r
</div></div>\r
+</div>\r
<div class="sect2">\r
-<h3 id="resizingconfig">7.1. Resizing containers/windows</h3>\r
+<h3 id="resizingconfig">6.12. Resizing containers/windows</h3>\r
<div class="paragraph"><p>If you want to resize containers/windows using your keyboard, you can use the\r
<tt>resize</tt> command:</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\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] <height> [px]</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). Note that <tt>resize set</tt> will only work for\r
-floating containers.</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></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_jumping_to_specific_windows">7.2. Jumping to specific windows</h3>\r
+<h3 id="_jumping_to_specific_windows">6.13. Jumping to specific windows</h3>\r
<div class="paragraph"><p>Often when in a multi-monitor environment, you want to quickly jump to a\r
specific window. For example, while working on workspace 3 you may want to\r
jump to your mail client to email your boss that you’ve achieved some\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="vim_like_marks">7.3. VIM-like marks (mark/goto)</h3>\r
+<h3 id="vim_like_marks">6.14. VIM-like marks (mark/goto)</h3>\r
<div class="paragraph"><p>This feature is like the jump feature: It allows you to directly jump to a\r
specific window (this means switching to the appropriate workspace and setting\r
focus to the windows). However, you can directly mark a specific window with\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="pango_markup">7.4. Window title format</h3>\r
+<h3 id="pango_markup">6.15. Window title format</h3>\r
<div class="paragraph"><p>By default, i3 will simply print the X11 window title. Using <tt>title_format</tt>,\r
this can be customized by setting the format to the desired output. This\r
directive supports\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_changing_border_style">7.5. Changing border style</h3>\r
+<h3 id="_changing_border_style">6.16. Changing border style</h3>\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
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="shmlog">7.6. Enabling shared memory logging</h3>\r
+<h3 id="shmlog">6.17. Enabling shared memory logging</h3>\r
<div class="paragraph"><p>As described in <a href="https://i3wm.org/docs/debugging.html">https://i3wm.org/docs/debugging.html</a>, i3 can log to a shared\r
memory buffer, which you can dump using <tt>i3-dump-log</tt>. The <tt>shmlog</tt> command\r
allows you to enable or disable the shared memory logging at runtime.</p></div>\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_enabling_debug_logging">7.7. Enabling debug logging</h3>\r
+<h3 id="_enabling_debug_logging">6.18. Enabling debug logging</h3>\r
<div class="paragraph"><p>The <tt>debuglog</tt> command allows you to enable or disable debug logging at\r
runtime. Debug logging is much more verbose than non-debug logging. This\r
command does not activate shared memory logging (shmlog), and as such is most\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_reloading_restarting_exiting">7.8. Reloading/Restarting/Exiting</h3>\r
+<h3 id="_reloading_restarting_exiting">6.19. Reloading/Restarting/Exiting</h3>\r
<div class="paragraph"><p>You can make i3 reload its configuration file with <tt>reload</tt>. You can also\r
restart i3 inplace with the <tt>restart</tt> command to get it out of some weird state\r
(if that should ever happen) or to perform an upgrade without having to restart\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_scratchpad">7.9. Scratchpad</h3>\r
+<h3 id="_scratchpad">6.20. Scratchpad</h3>\r
<div class="paragraph"><p>There are two commands to use any existing window as scratchpad window. <tt>move\r
scratchpad</tt> will move a window to the scratchpad workspace. This will make it\r
invisible until you show it again. There is no way to open that workspace.\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_nop">7.10. Nop</h3>\r
+<h3 id="_nop">6.21. Nop</h3>\r
<div class="paragraph"><p>There is a no operation command <tt>nop</tt> which allows you to override default\r
behavior. This can be useful for, e.g., disabling a focus change on clicks with\r
the middle mouse button.</p></div>\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_i3bar_control">7.11. i3bar control</h3>\r
+<h3 id="_i3bar_control">6.22. i3bar control</h3>\r
<div class="paragraph"><p>There are two options in the configuration of each i3bar instance that can be\r
changed during runtime by invoking a command through i3. The commands <tt>bar\r
hidden_state</tt> and <tt>bar mode</tt> allow setting the current hidden_state\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="multi_monitor">8. Multiple monitors</h2>\r
+<h2 id="multi_monitor">7. Multiple monitors</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>As you can see in the goal list on the website, i3 was specifically developed\r
with support for multiple monitors in mind. This section will explain how to\r
screens, you can have the "traditional" approach of having X workspaces per\r
screen by changing your configuration (using modes, for example).</p></div>\r
<div class="sect2">\r
-<h3 id="_configuring_your_monitors">8.1. Configuring your monitors</h3>\r
+<h3 id="_configuring_your_monitors">7.1. Configuring your monitors</h3>\r
<div class="paragraph"><p>To help you get going if you have never used multiple monitors before, here is\r
a short overview of the xrandr options which will probably be of interest to\r
you. It is always useful to get an overview of the current screen configuration.\r
<div class="paragraph"><p>See also <a href="#presentations">[presentations]</a> for more examples of multi-monitor setups.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_interesting_configuration_for_multi_monitor_environments">8.2. Interesting configuration for multi-monitor environments</h3>\r
+<h3 id="_interesting_configuration_for_multi_monitor_environments">7.2. Interesting configuration for multi-monitor environments</h3>\r
<div class="paragraph"><p>There are several things to configure in i3 which may be interesting if you\r
have more than one monitor:</p></div>\r
<div class="olist arabic"><ol class="arabic">\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_i3_and_the_rest_of_your_software_world">9. i3 and the rest of your software world</h2>\r
+<h2 id="_i3_and_the_rest_of_your_software_world">8. i3 and the rest of your software world</h2>\r
<div class="sectionbody">\r
<div class="sect2">\r
-<h3 id="_displaying_a_status_line">9.1. Displaying a status line</h3>\r
+<h3 id="_displaying_a_status_line">8.1. Displaying a status line</h3>\r
<div class="paragraph"><p>A very common thing amongst users of exotic window managers is a status line at\r
some corner of the screen. It is an often superior replacement to the widget\r
approach you have in the task bar of a traditional desktop environment.</p></div>\r
see <a href="#i3bar_position">[i3bar_position]</a>.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="presentations">9.2. Giving presentations (multi-monitor)</h3>\r
+<h3 id="presentations">8.2. Giving presentations (multi-monitor)</h3>\r
<div class="paragraph"><p>When giving a presentation, you typically want the audience to see what you see\r
on your screen and then go through a series of slides (if the presentation is\r
simple). For more complex presentations, you might want to have some notes\r
which only you can see on your screen, while the audience can only see the\r
slides.</p></div>\r
<div class="sect3">\r
-<h4 id="_case_1_everybody_gets_the_same_output">9.2.1. Case 1: everybody gets the same output</h4>\r
+<h4 id="_case_1_everybody_gets_the_same_output">8.2.1. Case 1: everybody gets the same output</h4>\r
<div class="paragraph"><p>This is the simple case. You connect your computer to the video projector,\r
turn on both (computer and video projector) and configure your X server to\r
clone the internal flat panel of your computer to the video output:</p></div>\r
our example, this would be 1024x768 (my notebook has 1280x800).</p></div>\r
</div>\r
<div class="sect3">\r
-<h4 id="_case_2_you_can_see_more_than_your_audience">9.2.2. Case 2: you can see more than your audience</h4>\r
+<h4 id="_case_2_you_can_see_more_than_your_audience">8.2.2. Case 2: you can see more than your audience</h4>\r
<div class="paragraph"><p>This case is a bit harder. First of all, you should configure the VGA output\r
somewhere near your internal flat panel, say right of it:</p></div>\r
<div class="listingblock">\r
</div>\r
<div id="footnotes"><hr /></div>\r
<div id="footer" lang="de">\r
-© 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>\r
+ © 2009-present Michael Stapelberg,\r
+ <a href="/impress.html">Impressum</a>,\r
+ <a href="https://github.com/i3/i3.github.io">Source</a>\r
</div>\r
</body>\r
</html>\r
projects / i3 / i3.github.io / blobdiff