something to us to get your bug fixed. If you have any questions about the
process and/or need further help, do not hesitate to contact us!
-== Verify you are using i3 ≥ 4.15
+== Verify you are using i3 ≥ 4.16
Only the latest major version of i3 is supported. To verify which version
you are running, use:
== Debugging i3bar
-To debug i3bar problems, add +verbose yes+ to all +bar {}+ blocks in your i3
+To debug i3bar problems, use the +--verbose+ commandline parameter,
+or add +verbose yes+ to all +bar {}+ blocks in your i3
config, reload your config and then restart all i3bar instances like this:
---------------------------------------------------------------------
processing.
The default value (if none is specified) is SIGSTOP.
cont_signal::
- Specify to i3bar the signal (as an integer)to send to continue your
+ Specify to i3bar the signal (as an integer) to send to continue your
processing.
The default value (if none is specified) is SIGCONT.
click_events::
full_text::
The +full_text+ will be displayed by i3bar on the status line. This is the
- only required key.
+ only required key. If +full_text+ is an empty string, the block will be
+ skipped.
short_text::
Where appropriate, the +short_text+ (string) entry should also be
provided. It will be used in case the status line needs to be shortened
of the block
width, height::
Width and height (in px) of the block
+modifiers::
+ An array of the modifiers active when the click occurred. The order in which
+ modifiers are listed is not guaranteed.
*Example*:
------------------------------------------
"name": "ethernet",
"instance": "eth0",
"button": 1,
+ "modifiers": ["Shift", "Mod1"],
"x": 1320,
"y": 1400,
"relative_x": 12,
| 8 | +GET_BINDING_MODES+ | <<_binding_modes_reply,BINDING_MODES>> | Gets the names of all currently configured binding modes.
| 9 | +GET_CONFIG+ | <<_config_reply,CONFIG>> | Returns the last loaded i3 config.
| 10 | +SEND_TICK+ | <<_tick_reply,TICK>> | Sends a tick event with the specified payload.
+| 11 | +SYNC+ | <<_sync_reply,SYNC>> | Sends an i3 sync event with the specified random value to the specified window.
|======================================================
So, a typical message could look like this:
This field is set to null for split containers or otherwise empty
containers. This ID corresponds to what xwininfo(1) and other
X11-related tools display (usually in hex).
+window_properties (map)::
+ X11 window properties title, instance, class, window_role and transient_for.
urgent (bool)::
Whether this container (window, split container, floating container or
workspace) has the urgency hint set, directly or indirectly. All parent
"width": 1280,
"height": 782
},
+ "window_properties": {
+ "class": "Evince",
+ "instance": "evince",
+ "title": "Properties",
+ "transient_for": 52428808
+ },
"floating_nodes": [],
"nodes": [
{ "success": true }
-------------------
+[[_sync_reply]]
+=== SYNC reply
+
+The reply is a map containing the "success" member. After the reply was
+received, the https://i3wm.org/docs/testsuite.html#i3_sync[i3 sync message] was
+responded to.
+
+*Example:*
+-------------------
+{ "success": true }
+-------------------
+
== Events
[[events]]
event based library may not have a problem here), I suggest you create a
separate connection to receive events.
+If an event message needs to be sent and the socket is not writeable (write
+returns EAGAIN, happens when the socket doesn't have enough buffer space for
+writing new data) then i3 uses a queue system to store outgoing messages for
+each client. This is combined with a timer: if the message queue for a client is
+not empty and no data where successfully written in the past 10 seconds, the
+connection is killed. Practically, this means that your client should try to
+always read events from the socket to avoid having its connection closed.
+
=== Subscribing to events
By sending a message of type SUBSCRIBE with a JSON-encoded array as payload
A layout file as generated by +i3-save-tree(1)+ is not strictly valid JSON:
-1. Layout files contain multiple “JSON documents” on the top level, whereas the
- JSON standard only allows precisely one “document” (array or hash).
+1. Layout files contain multiple “JSON texts” at the top level. The JSON
+ standard doesn't prohibit this, but in practice most JSON parsers only
+ allow precisely one “text” per document/file, and will mark multiple texts
+ as invalid JSON.
-2. Layout files contain comments which are not standardized, but understood by
- many parsers.
+2. Layout files contain comments which are not allowed by the JSON standard,
+ but are understood by many parsers.
-Both deviations from the JSON standard are to make manual editing by humans
+Both of these deviations from the norm are to make manual editing by humans
easier. In case you are writing a more elaborate tool for manipulating these
layouts, you can either use a JSON parser that supports these deviations (for
example libyajl), transform the layout file to a JSON-conforming file, or
So, how can you open a new terminal window to the *right* of the current one?
The solution is to use +focus parent+, which will focus the +Parent Container+ of
-the current +Container+. In this case, you would focus the +Vertical Split
-Container+ which is *inside* the horizontally oriented workspace. Thus, now new
-windows will be opened to the right of the +Vertical Split Container+:
+the current +Container+. In default configuration, use +$mod+a+ to navigate one
++Container+ up the tree (you can repeat this multiple times until you get to the
++Workspace Container+). In this case, you would focus the +Vertical Split Container+
+which is *inside* the horizontally oriented workspace. Thus, now new windows will be
+opened to the right of the +Vertical Split Container+:
image::tree-shot3.png["shot3",title="Focus parent, then open new terminal"]
workspace_layout tabbed
---------------------
+=== Window title alignment
+
+This option determines the window title's text alignment.
+Default is +left+
+
+*Syntax*:
+---------------------------------------------
+title_align left|center|right
+---------------------------------------------
+
=== Default border style for new windows
This option determines which border style new windows will have. The default is
across many X applications.
Defining a resource will load this resource from the resource database and
-assign its value to the specified variable. A fallback must be specified in
+assign its value to the specified variable. This is done verbatim and the value
+must therefore be in the format that i3 uses. A fallback must be specified in
case the resource cannot be loaded from the database.
*Syntax*:
To automatically make a specific window show up on a specific workspace, you
can use an *assignment*. You can match windows by using any criteria,
-see <<command_criteria>>. It is recommended that you match on window classes
-(and instances, when appropriate) instead of window titles whenever possible
-because some applications first create their window, and then worry about
-setting the correct title. Firefox with Vimperator comes to mind. The window
-starts up being named Firefox, and only when Vimperator is loaded does the
-title change. As i3 will get the title as soon as the application maps the
-window (mapping means actually displaying it on the screen), you’d need to have
-to match on 'Firefox' in this case.
+see <<command_criteria>>. The difference between +assign+ and
++for_window <criteria> move to workspace+ is that the former will only be
+executed when the application maps the window (mapping means actually displaying
+it on the screen) but the latter will be executed whenever a window changes its
+properties to something that matches the specified criteria.
+
+Thus, it is recommended that you match on window classes (and instances, when
+appropriate) instead of window titles whenever possible because some
+applications first create their window, and then worry about setting the correct
+title. Firefox with Vimperator comes to mind. The window starts up being named
+Firefox, and only when Vimperator is loaded does the title change. As i3 will
+get the title as soon as the application maps the window, you’d need to have to
+match on 'Firefox' in this case.
+Another known issue is with Spotify, which doesn't set the class hints when
+mapping the window, meaning you'll have to use a +for_window+ rule to assign
+Spotify to a specific workspace.
+Finally, using +assign [tiling]+ and +assign [floating]+ is not supported.
You can also assign a window to show up on a specific output. You can use RandR
names such as +VGA1+ or names relative to the output with the currently focused
*Syntax*:
-------------------------------------
-workspace <workspace> output <output>
+workspace <workspace> output <output1> [output2]…
-------------------------------------
The 'output' is the name of the RandR output you attach your screen to. On a
entire monitor, i3 will still use the entire area of the containing monitor
rather than that of just the output's.)
+You can specify multiple outputs. The first available will be used.
+
If you use named workspaces, they must be quoted:
*Examples*:
---------------------------
workspace 1 output LVDS1
-workspace 5 output VGA1
+workspace 2 output primary
+workspace 5 output VGA1 LVDS1
workspace "2: vim" output VGA1
---------------------------
----------------------------
You can then use the +i3-msg+ application to perform any command listed in
-the next section.
+<<list_of_commands>>.
=== Focus follows mouse
Also note that your output names are not descriptive (like +HDMI1+) when using
Xinerama, instead they are counted up, starting at 0: +xinerama-0+, +xinerama-1+, …
+[[workspace_auto_back_and_forth]]
=== Automatic back-and-forth when switching to the current workspace
This configuration directive enables automatic +workspace back_and_forth+ (see
}
------------------------
-=== Strip workspace numbers
+=== Strip workspace numbers/name
Specifies whether workspace numbers should be displayed within the workspace
buttons. This is useful if you want to have a named workspace that stays in
instance, to display Roman numerals rather than digits by naming your
workspaces to "1:I", "2:II", "3:III", "4:IV", ...
+When +strip_workspace_name+ is set to +yes+, any workspace that has a name of
+the form "[n]:[NAME]" will display only the number.
+
The default is to display the full name within the workspace button.
*Syntax*:
------------------------------
strip_workspace_numbers yes|no
+strip_workspace_name yes|no
------------------------------
*Example*:
}
--------------------------------------
+[[list_of_commands]]
== List of commands
Commands are what you bind to specific keypresses. You can also issue commands
# defaults to 10 pixels.
move <left|right|down|up> [<px> px]
-# Moves the container either to a specific location
-# or to the center of the screen. If 'absolute' is
-# used, it is moved to the center of all outputs.
-move [absolute] position <pos_x> [px] <pos_y> [px]
+# Moves the container to the specified pos_x and pos_y
+# coordinates on the screen.
+move position <pos_x> [px] <pos_y> [px]
+
+# Moves the container to the center of the screen.
+# If 'absolute' is used, it is moved to the center of
+# all outputs.
move [absolute] position center
# Moves the container to the current position of the
To change to a specific workspace, use the +workspace+ command, followed by the
number or name of the workspace. Pass the optional flag
-+--no-auto-back-and-forth+ to disable <<back_and_forth>> for this specific call
-only.
++--no-auto-back-and-forth+ to disable <<workspace_auto_back_and_forth>> for this
+specific call only.
To move containers to specific workspaces, use +move container to workspace+.
*Syntax*:
-------------------------------------------------------
resize grow|shrink <direction> [<px> px [or <ppt> ppt]]
-resize set <width> [px | ppt] <height> [px | ppt]
+resize set [width] <width> [px | ppt]
+resize set height <height> [px | ppt]
+resize set [width] <width> [px | ppt] [height] <height> [px | ppt]
-------------------------------------------------------
Direction can either be one of +up+, +down+, +left+ or +right+. Or you can be
-less specific and use +width+ or +height+, in which case i3 will take/give
-space from all the other containers. The optional pixel argument specifies by
-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).
+less specific and use +width+ or +height+, in which case i3 will take/give space
+from all the other containers. The optional pixel argument specifies by how many
+pixels a container should be grown or shrunk (the default is 10 pixels). The
+optional ppt argument means "percentage points", and if specified it indicates
+that a *tiling container* should be grown or shrunk by that many points, instead
+of by the +px+ value.
-Notes about +resize set+: a value of 0 for <width> or <height> means "do
-not resize in this direction", and resizing a tiling container by +px+ is not
-implemented.
+Note about +resize set+: a value of 0 for <width> or <height> means "do not
+resize in this direction".
It is recommended to define bindings for resizing in a dedicated binding mode.
See <<binding_modes>> and the example in the i3
border (including window title), +border pixel 1+ to use a 1-pixel border (no window title)
and +border none+ to make the client borderless.
-There is also +border toggle+ which will toggle the different border styles.
+There is also +border toggle+ which will toggle the different border styles. The
+optional pixel argument can be used to specify the border width when switching
+to the normal and pixel styles.
Note that "pixel" refers to logical pixel. On HiDPI displays, a logical pixel
may be represented by multiple physical pixels, so +pixel 1+ might not
*Syntax*:
-----------------------------------------------
-border normal|pixel [<n>]
-border none|toggle
+border normal|pixel|toggle [<n>]
+border none
# legacy syntax, equivalent to "border pixel 1"
border 1pixel
<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: Debugging i3: How To</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_verify_you_are_using_i3_4_15">1. Verify you are using i3 ≥ 4.15</h2>\r
+<h2 id="_verify_you_are_using_i3_4_16">1. Verify you are using i3 ≥ 4.16</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Only the latest major version of i3 is supported. To verify which version\r
you are running, use:</p></div>\r
<div class="sect1">\r
<h2 id="_debugging_i3bar">7. Debugging i3bar</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>To debug i3bar problems, add <tt>verbose yes</tt> to all <tt>bar {}</tt> blocks in your i3\r
+<div class="paragraph"><p>To debug i3bar problems, use the <tt>--verbose</tt> commandline parameter,\r
+or add <tt>verbose yes</tt> to all <tt>bar {}</tt> blocks in your i3\r
config, reload your config and then restart all i3bar instances like this:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
<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: Hacking i3: How To</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<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: i3bar input protocol</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
</dt>\r
<dd>\r
<p>\r
- Specify to i3bar the signal (as an integer)to send to continue your\r
+ Specify to i3bar the signal (as an integer) to send to continue your\r
processing.\r
The default value (if none is specified) is SIGCONT.\r
</p>\r
<dd>\r
<p>\r
The <tt>full_text</tt> will be displayed by i3bar on the status line. This is the\r
- only required key.\r
+ only required key. If <tt>full_text</tt> is an empty string, the block will be\r
+ skipped.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
Width and height (in px) of the block\r
</p>\r
</dd>\r
+<dt class="hdlist1">\r
+modifiers\r
+</dt>\r
+<dd>\r
+<p>\r
+ An array of the modifiers active when the click occurred. The order in which\r
+ modifiers are listed is not guaranteed.\r
+</p>\r
+</dd>\r
</dl></div>\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
<div class="listingblock">\r
"name": "ethernet",\r
"instance": "eth0",\r
"button": 1,\r
+ "modifiers": ["Shift", "Mod1"],\r
"x": 1320,\r
"y": 1400,\r
"relative_x": 12,\r
<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: IPC interface (interprocess communication)</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<td align="center" valign="top"><p class="table"><a href="#_tick_reply">TICK</a></p></td>\r
<td align="center" valign="top"><p class="table">Sends a tick event with the specified payload.</p></td>\r
</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">11</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>SYNC</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_sync_reply">SYNC</a></p></td>\r
+<td align="center" valign="top"><p class="table">Sends an i3 sync event with the specified random value to the specified window.</p></td>\r
+</tr>\r
</tbody>\r
</table>\r
</div>\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+window_properties (map)\r
+</dt>\r
+<dd>\r
+<p>\r
+ X11 window properties title, instance, class, window_role and transient_for.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
urgent (bool)\r
</dt>\r
<dd>\r
"width": 1280,\r
"height": 782\r
},\r
+ "window_properties": {\r
+ "class": "Evince",\r
+ "instance": "evince",\r
+ "title": "Properties",\r
+ "transient_for": 52428808\r
+ },\r
"floating_nodes": [],\r
"nodes": [\r
\r
<pre><tt>{ "success": true }</tt></pre>\r
</div></div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_sync_reply">3.13. SYNC reply</h3>\r
+<div class="paragraph"><p>The reply is a map containing the "success" member. After the reply was\r
+received, the <a href="https://i3wm.org/docs/testsuite.html#i3_sync">i3 sync message</a> was\r
+responded to.</p></div>\r
+<div class="paragraph"><p><strong>Example:</strong></p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{ "success": true }</tt></pre>\r
+</div></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
program does not want to cope which such kinds of race conditions (an\r
event based library may not have a problem here), I suggest you create a\r
separate connection to receive events.</p></div>\r
+<div class="paragraph"><p>If an event message needs to be sent and the socket is not writeable (write\r
+returns EAGAIN, happens when the socket doesn’t have enough buffer space for\r
+writing new data) then i3 uses a queue system to store outgoing messages for\r
+each client. This is combined with a timer: if the message queue for a client is\r
+not empty and no data where successfully written in the past 10 seconds, the\r
+connection is killed. Practically, this means that your client should try to\r
+always read events from the socket to avoid having its connection closed.</p></div>\r
<div class="sect2">\r
<h3 id="_subscribing_to_events">4.1. Subscribing to events</h3>\r
<div class="paragraph"><p>By sending a message of type SUBSCRIBE with a JSON-encoded array as payload\r
<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: Layout saving in i3</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<div class="olist arabic"><ol class="arabic">\r
<li>\r
<p>\r
-Layout files contain multiple “JSON documents” on the top level, whereas the\r
- JSON standard only allows precisely one “document” (array or hash).\r
+Layout files contain multiple “JSON texts” at the top level. The JSON\r
+ standard doesn’t prohibit this, but in practice most JSON parsers only\r
+ allow precisely one “text” per document/file, and will mark multiple texts\r
+ as invalid JSON.\r
</p>\r
</li>\r
<li>\r
<p>\r
-Layout files contain comments which are not standardized, but understood by\r
- many parsers.\r
+Layout files contain comments which are not allowed by the JSON standard,\r
+ but are understood by many parsers.\r
</p>\r
</li>\r
</ol></div>\r
-<div class="paragraph"><p>Both deviations from the JSON standard are to make manual editing by humans\r
+<div class="paragraph"><p>Both of these deviations from the norm are to make manual editing by humans\r
easier. In case you are writing a more elaborate tool for manipulating these\r
layouts, you can either use a JSON parser that supports these deviations (for\r
example libyajl), transform the layout file to a JSON-conforming file, or\r
<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: The multi-monitor situation</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<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 testsuite</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<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
<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: External workspace bars</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
projects / i3 / i3.github.io / commitdiff