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.14.1
+== Verify you are using i3 ≥ 4.15
Only the latest major version of i3 is supported. To verify which version
you are running, use:
you found the section which clearly highlights the problem, additional
information might be necessary to completely diagnose the problem.
-When debugging with us in IRC, be prepared to use a so called nopaste service
+When debugging with us in IRC, be prepared to use a so-called nopaste service
such as https://pastebin.com because pasting large amounts of text in IRC
sometimes leads to incomplete lines (servers have line length limitations) or
flood kicks.
markup::
A string that indicates how the text of the block should be parsed. Set to
+"pango"+ to use https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup].
- Set to +"none"+ to not use any markup (default).
+ Set to +"none"+ to not use any markup (default). Pango markup only works
+ if you use a pango font.
If you want to put in your own entries into a block, prefix the key with an
underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing
X11 root window coordinates where the click occurred
button::
X11 button ID (for example 1 to 3 for left/middle/right mouse button)
+relative_x, relative_y::
+ Coordinates where the click occurred, with respect to the top left corner
+ of the block
+width, height::
+ Width and height (in px) of the block
*Example*:
------------------------------------------
"instance": "eth0",
"button": 1,
"x": 1320,
- "y": 1400
+ "y": 1400,
+ "relative_x": 12,
+ "relative_y": 8,
+ "width": 50,
+ "height": 22
}
------------------------------------------
== DESCRIPTION
-i3status is a small program (about 1500 SLOC) for generating a status bar for
-i3bar, dzen2, xmobar, lemonbar or similar programs. It is designed to be very
-efficient by issuing a very small number of system calls, as one generally
-wants to update such a status line every second. This ensures that even under
-high load, your status bar is updated correctly. Also, it saves a bit of energy
-by not hogging your CPU as much as spawning the corresponding amount of shell
-commands would.
+i3status is a small program for generating a status bar for i3bar, dzen2,
+xmobar, lemonbar or similar programs. It is designed to be very efficient by
+issuing a very small number of system calls, as one generally wants to update
+such a status line every second. This ensures that even under high load, your
+status bar is updated correctly. Also, it saves a bit of energy by not hogging
+your CPU as much as spawning the corresponding amount of shell commands would.
== CONFIGURATION
| 7 | +GET_VERSION+ | <<_version_reply,VERSION>> | Gets the i3 version.
| 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.
|======================================================
So, a typical message could look like this:
Reply to the GET_BINDING_MODES message.
GET_CONFIG (9)::
Reply to the GET_CONFIG message.
+TICK (10)::
+ Reply to the SEND_TICK message.
[[_command_reply]]
=== COMMAND reply
{ "config": "font pango:monospace 8\nbindsym Mod4+q exit\n" }
-------------------
+[[_tick_reply]]
+=== TICK reply
+
+The reply is a map containing the "success" member. After the reply was
+received, the tick event has been written to all IPC connections which subscribe
+to tick events. UNIX sockets are usually buffered, but you can be certain that
+once you receive the tick event you just triggered, you must have received all
+events generated prior to the +SEND_TICK+ message (happened-before relation).
+
+*Example:*
+-------------------
+{ "success": true }
+-------------------
== Events
mouse
shutdown (6)::
Sent when the ipc shuts down because of a restart or exit by user command
+tick (7)::
+ Sent when the ipc client subscribes to the tick event (with +"first":
+ true+) or when any ipc client sends a SEND_TICK message (with +"first":
+ false+).
*Example:*
--------------------------------------------------------------------
}
---------------------------
+=== tick event
+
+This event is triggered by a subscription to tick events or by a +SEND_TICK+
+message.
+
+*Example (upon subscription):*
+--------------------------------------------------------------------------------
+{
+ "first": true,
+ "payload": ""
+}
+--------------------------------------------------------------------------------
+
+*Example (upon +SEND_TICK+ with a payload of +arbitrary string+):*
+--------------------------------------------------------------------------------
+{
+ "first": false,
+ "payload": "arbitrary string"
+}
+--------------------------------------------------------------------------------
+
== See also (existing libraries)
[[libraries]]
* https://github.com/drmgc/i3ipcpp
Go::
* https://github.com/mdirkse/i3ipc-go
+ * https://github.com/i3/go-i3
JavaScript::
* https://github.com/acrisci/i3ipc-gjs
Lua::
* https://metacpan.org/module/AnyEvent::I3
Python::
* https://github.com/acrisci/i3ipc-python
- * https://github.com/Ceryn/i3msg-python
* https://github.com/whitelynx/i3ipc (not maintained)
* https://github.com/ziberna/i3-py (not maintained)
Ruby::
payload. Then, receive the pending +COMMAND+ message reply in big endian.
5. From here on out, send/receive all messages using the detected byte order.
+
+Find an example implementation of this technique in
+https://github.com/i3/go-i3/blob/master/byteorder.go
////////////////////////////////////////////////////////////////////////////////
---------------------------------------------------------------------------------
-$ /usr/lib/apt/apt-helper download-file http://debian.sur5r.net/i3/pool/main/s/sur5r-keyring/sur5r-keyring_2017.01.02_all.deb keyring.deb SHA256:4c3c6685b1181d83efe3a479c5ae38a2a44e23add55e16a328b8c8560bf05e5f
+$ /usr/lib/apt/apt-helper download-file http://debian.sur5r.net/i3/pool/main/s/sur5r-keyring/sur5r-keyring_2018.01.30_all.deb keyring.deb SHA256:baa43dbbd7232ea2b5444cae238d53bebb9d34601cc000e82f11111b1889078a
# dpkg -i ./keyring.deb
# echo "deb http://debian.sur5r.net/i3/ $(grep '^DISTRIB_CODENAME=' /etc/lsb-release | cut -f2 -d=) universe" >> /etc/apt/sources.list.d/sur5r-i3.list
# apt update
always be found under the symlink +latest/+. Unless told differently, it will
run the tests on a separate X server instance (using Xephyr).
-Xephyr will open a window where you can inspect the running test. You can run
-the tests without an X session with Xvfb, such as with +xvfb-run
-./complete-run+. This will also speed up the tests significantly especially on
-machines without a powerful video card.
+Xephyr will open a window where you can inspect the running test. By default,
+tests are run under Xvfb.
.Example invocation of +complete-run.pl+
---------------------------------------
i3 User’s Guide
===============
Michael Stapelberg <michael@i3wm.org>
-March 2013
This document contains all the information you need to configure and use the i3
window manager. If it does not, please check https://www.reddit.com/r/i3wm/
== Default keybindings
For the "too long; didn’t read" people, here is an overview of the default
-keybindings (click to see the full size image):
+keybindings (click to see the full-size image):
*Keys to use with $mod (Alt):*
Throughout this guide, the keyword +$mod+ will be used to refer to the
configured modifier. This is the Alt key (+Mod1+) by default, with the Windows
-key (+Mod4+) being a popular alternative.
+key (+Mod4+) being a popular alternative that largely prevents conflicts with
+application-defined shortcuts.
=== Opening terminals and moving around
=== The tree consists of Containers
-The building blocks of our tree are so called +Containers+. A +Container+ can
+The building blocks of our tree are so-called +Containers+. A +Container+ can
host a window (meaning an X11 window, one that you can actually see and use,
like a browser). Alternatively, it could contain one or more +Containers+. A
simple example is the workspace: When you start i3 with a single monitor, a
you open a new terminal, it will open below the current one.
So, how can you open a new terminal window to the *right* of the current one?
-The solution is to use +focus parent+ (+$mod+a+ by default), which will focus the +Parent Container+ of
+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 floating modifier
To move floating windows with your mouse, you can either grab their titlebar
-or configure the so called floating modifier which you can then press and
+or configure the so-called floating modifier which you can then press and
click anywhere in the window itself to move it. The most common setup is to
use the same key you use for managing windows (Mod1 for example). Then
you can press Mod1, click into a window using your left mouse button, and drag
workspace_layout tabbed
---------------------
-=== Border style for new windows
+=== Default border style for new windows
This option determines which border style new windows will have. The default is
-+normal+. Note that new_float applies only to windows which are starting out as
++normal+. Note that default_floating_border applies only to windows which are starting out as
floating windows, e.g., dialog windows, but not windows that are floated later on.
*Syntax*:
---------------------------------------------
-new_window normal|none|pixel
-
new_window normal|pixel <px>
-new_float normal|none|pixel
-
new_float normal|pixel <px>
+default_border normal|none|pixel
+
default_border normal|pixel <px>
+default_floating_border normal|none|pixel
+
default_floating_border normal|pixel <px>
---------------------------------------------
+Please note that +new_window+ and +new_float+ have been deprecated in favor of the above options
+and will be removed in a future release. We strongly recommend using the new options instead.
+
*Example*:
---------------------
-new_window pixel
+default_border pixel
---------------------
The "normal" and "pixel" border styles support an optional border width in
*Example*:
---------------------
-# The same as new_window none
-new_window pixel 0
+# The same as default_border none
+default_border pixel 0
# A 3 px border
-new_window pixel 3
+default_border pixel 3
---------------------
window (mapping means actually displaying it on the screen), you’d need to have
to match on 'Firefox' in this case.
+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
+workspace such as +left+ and +down+.
+
Assignments are processed by i3 in the order in which they appear in the config
file. The first one which matches the window wins and later assignments are not
considered.
*Syntax*:
------------------------------------------------------------
-assign <criteria> [→] [workspace] <workspace>
+assign <criteria> [→] [workspace] [number] <workspace>
+assign <criteria> [→] output left|right|up|down|primary|<output>
------------------------------------------------------------
*Examples*:
# Assignment to a named workspace
assign [class="^URxvt$"] → work
+# Assign to the workspace with number 2, regardless of name
+assign [class="^URxvt$"] → number 2
+
+# You can also specify a number + name. If the workspace with number 2 exists, assign will skip the text part.
+assign [class="^URxvt$"] → number "2: work"
+
# Start urxvt -name irssi
assign [class="^URxvt$" instance="^irssi$"] → 3
+
+# Assign urxvt to the output right of the current one
+assign [class="^URxvt$"] → output right
+
+# Assign urxvt to the primary output
+assign [class="^URxvt$"] → output primary
----------------------
-Note that the arrow is not required, it just looks good :-). If you decide to
+Note that you might not have a primary output configured yet. To do so, run:
+-------------------------
+xrandr --output <output> --primary
+-------------------------
+
+Also, the arrow is not required, it just looks good :-). If you decide to
use it, it has to be a UTF-8 encoded arrow, not `->` or something like that.
To get the class and instance, you can use +xprop+. After clicking on the
=== Focus wrapping
-When being in a tabbed or stacked container, the first container will be
-focused when you use +focus down+ on the last container -- the focus wraps. If
-however there is another stacked/tabbed container in that direction, focus will
-be set on that container. This is the default behavior so you can navigate to
-all your windows without having to use +focus parent+.
+By default, when in a container with several windows or child containers, the
+opposite window will be focused when trying to move the focus over the edge of
+a container (and there are no other containers in that direction) -- the focus
+wraps.
+
+If desired, you can disable this behavior by setting the +focus_wrapping+
+configuration directive to the value +no+.
+
+When enabled, focus wrapping does not occur by default if there is another
+window or container in the specified direction, and focus will instead be set
+on that window or container. This is the default behavior so you can navigate
+to all your windows without having to use +focus parent+.
If you want the focus to *always* wrap and you are aware of using +focus
-parent+ to switch to different containers, you can use the
-+force_focus_wrapping+ configuration directive. After enabling it, the focus
-will always wrap.
+parent+ to switch to different containers, you can instead set +focus_wrapping+
+to the value +force+.
*Syntax*:
---------------------------
-force_focus_wrapping yes|no
----------------------------
+focus_wrapping yes|no|force
-*Example*:
-------------------------
+# Legacy syntax, equivalent to "focus_wrapping force"
force_focus_wrapping yes
-------------------------
+---------------------------
+
+*Examples*:
+-----------------
+# Disable focus wrapping
+focus_wrapping no
+
+# Force focus wrapping
+focus_wrapping force
+-----------------
=== Forcing Xinerama
*Syntax*:
----------------------------
-bindsym button<n> <command>
+bindsym [--release] button<n> <command>
----------------------------
*Example*:
bar {
# disable clicking on workspace buttons
bindsym button1 nop
+ # Take a screenshot by right clicking on the bar
+ bindsym --release button3 exec --no-startup-id import /tmp/latest-screenshot.png
# execute custom script when scrolling downwards
bindsym button5 exec ~/.i3/scripts/custom_wheel_down
}
To change focus, you can use the +focus+ command. The following options are
available:
+<criteria>::
+ Sets focus to the container that matches the specified criteria.
+ See <<command_criteria>>.
left|right|up|down::
Sets focus to the nearest container in the given direction.
parent::
*Syntax*:
----------------------------------------------
+<criteria> focus
focus left|right|down|up
focus parent|child|floating|tiling|mode_toggle
focus output left|right|up|down|primary|<output>
*Examples*:
-------------------------------------------------
+# Focus firefox
+bindsym $mod+F1 [class="Firefox"] focus
+
# Focus container on the left, bottom, top, right
bindsym $mod+j focus left
bindsym $mod+k focus down
*Syntax*:
-------------------------------------------------------
resize grow|shrink <direction> [<px> px [or <ppt> ppt]]
-resize set <width> [px] <height> [px]
+resize set <width> [px | ppt] <height> [px | ppt]
-------------------------------------------------------
Direction can either be one of +up+, +down+, +left+ or +right+. Or you can be
how many pixels a *floating container* should be grown or shrunk (the default
is 10 pixels). The ppt argument means percentage points and specifies by how
many percentage points a *tiling container* should be grown or shrunk (the
-default is 10 percentage points). Note that +resize set+ will only work for
-floating containers.
+default is 10 percentage points).
+
+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.
It is recommended to define bindings for resizing in a dedicated binding mode.
See <<binding_modes>> and the example in the i3
*Examples*:
---------------------------------------
# Read 1 character and mark the current window with this character
-bindsym $mod+m exec i3-input -p 'mark ' -l 1 -P 'Mark: '
+bindsym $mod+m exec i3-input -F 'mark %s' -l 1 -P 'Mark: '
# Read 1 character and go to the window with the character
-bindsym $mod+g exec i3-input -p 'goto ' -l 1 -P 'Goto: '
+bindsym $mod+g exec i3-input -F '[con_mark="%s"] focus' -l 1 -P 'Goto: '
---------------------------------------
Alternatively, if you do not want to mess with +i3-input+, you could create
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_verify_you_are_using_i3_4_14">1. Verify you are using i3 ≥ 4.14</h2>\r
+<h2 id="_verify_you_are_using_i3_4_14_1">1. Verify you are using i3 ≥ 4.14.1</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
<dd>\r
<p>\r
Your version is 85 commits newer than 4.7, and the git revision of your\r
-version is <tt>9c15b95</tt>. Go to <a href="http://code.i3wm.org/i3/commit/?h=next">http://code.i3wm.org/i3/commit/?h=next</a> and see if\r
-the line "commit" starts with the same revision. If so, you are using the\r
+version is <tt>9c15b95</tt>. Go to <a href="https://github.com/i3/i3/commits/next">https://github.com/i3/i3/commits/next</a> and see if\r
+the most recent commit starts with the same revision. If so, you are using the\r
latest version.\r
</p>\r
</dd>\r
<div class="paragraph"><p>To upload a compressed version of the logfile (for a bugreport), use:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>DISPLAY=:0 i3-dump-log | bzip2 -c | curl --data-binary @- http://logs.i3wm.org</tt></pre>\r
+<pre><tt>DISPLAY=:0 i3-dump-log | bzip2 -c | curl --data-binary @- https://logs.i3wm.org</tt></pre>\r
</div></div>\r
<div class="paragraph"><p>This command does not depend on i3 (it also works while i3 displays\r
the crash dialog), but it requires a working X11 connection.</p></div>\r
you found the section which clearly highlights the problem, additional\r
information might be necessary to completely diagnose the problem.</p></div>\r
<div class="paragraph"><p>When debugging with us in IRC, be prepared to use a so called nopaste service\r
-such as <a href="http://nopaste.info">http://nopaste.info</a> or <a href="http://pastebin.com">http://pastebin.com</a> because pasting large\r
-amounts of text in IRC sometimes leads to incomplete lines (servers have line\r
-length limitations) or flood kicks.</p></div>\r
+such as <a href="https://pastebin.com">https://pastebin.com</a> because pasting large amounts of text in IRC\r
+sometimes leads to incomplete lines (servers have line length limitations) or\r
+flood kicks.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_window_managers">1. Window Managers</h2>\r
+<h2 id="_building_i3">1. Building i3</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>You can build i3 like you build any other software package which uses autotools.\r
+Here’s a memory refresher:</p></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>$ autoreconf -fi\r
+$ mkdir -p build && cd build\r
+$ ../configure\r
+$ make -j8</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>(The autoreconf -fi step is unnecessary if you are building from a release tarball,\r
+ but shouldn’t hurt either.)</p></div>\r
+<div class="sect2">\r
+<h3 id="_build_system_features">1.1. Build system features</h3>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate\r
+ directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building\r
+ in a separate directory is common practice anyway. In case this causes any\r
+ trouble when packaging i3 for your distribution, please open an issue.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+“make check” runs the i3 testsuite. See docs/testsuite for details.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+“make distcheck” (runs testsuite on “make dist” result, tiny bit quicker\r
+ feedback cycle than waiting for the travis build to catch the issue).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+“make uninstall” (occasionally requested by users who compile from source)\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+“make” will build manpages/docs by default if the tools are installed.\r
+ Conversely, manpages/docs are not tried to be built for users who don’t want\r
+ to install all these dependencies to get started hacking on i3.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+non-release builds will enable address sanitizer by default. Use the\r
+ --disable-sanitizers configure option to turn off all sanitizers, and see\r
+ --help for available sanitizers.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Support for pre-compiled headers (PCH) has been dropped for now in the\r
+ interest of simplicity. If you need support for PCH, please open an issue.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Coverage reports are now generated using “make check-code-coverage”, which\r
+ requires specifying --enable-code-coverage when calling configure.\r
+</p>\r
+</li>\r
+</ul></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_using_git_sending_patches">2. Using git / sending patches</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>For a short introduction into using git, see\r
+<a href="https://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy">https://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy</a>\r
+or, for more documentation, see <a href="https://git-scm.com/documentation">https://git-scm.com/documentation</a></p></div>\r
+<div class="paragraph"><p>Please talk to us before working on new features to see whether they will be\r
+accepted. A good way for this is to open an issue and asking for opinions on it.\r
+Even for accepted features, this can be a good way to refine an idea upfront. However,\r
+we don’t want to see certain features in i3, e.g., switching window focus in an\r
+Alt+Tab like way.</p></div>\r
+<div class="paragraph"><p>When working on bugfixes, please make sure you mention that you are working on\r
+it in the corresponding bug report at <a href="https://github.com/i3/i3/issues">https://github.com/i3/i3/issues</a>. In case\r
+there is no bug report yet, please create one.</p></div>\r
+<div class="paragraph"><p>After you are done, please submit your work for review as a pull request at\r
+<a href="https://github.com/i3/i3">https://github.com/i3/i3</a>.</p></div>\r
+<div class="paragraph"><p>Do not send emails to the mailing list or any author directly, and don’t submit\r
+them in the bugtracker, since all reviews should be done in public at\r
+<a href="https://github.com/i3/i3">https://github.com/i3/i3</a>. In order to make your review go as fast as possible, you\r
+could have a look at previous reviews and see what the common mistakes are.</p></div>\r
+<div class="sect2">\r
+<h3 id="_which_branch_to_use">2.1. Which branch to use?</h3>\r
+<div class="paragraph"><p>Work on i3 generally happens in two branches: “master” and “next” (the latter\r
+being the default branch, the one that people get when they check out the git\r
+repository).</p></div>\r
+<div class="paragraph"><p>The contents of “master” are always stable. That is, it contains the source code\r
+of the latest release, plus any bugfixes that were applied since that release.</p></div>\r
+<div class="paragraph"><p>New features are only found in the “next” branch. Therefore, if you are working\r
+on a new feature, use the “next” branch. If you are working on a bugfix, use the\r
+“next” branch, too, but make sure your code also works on “master”.</p></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_window_managers">3. Window Managers</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>A window manager is not necessarily needed to run X, but it is usually used in\r
combination with X to facilitate some things. The window manager’s job is to\r
<div class="paragraph"><p>In the following chapters, each of these tasks and their implementation details\r
will be discussed.</p></div>\r
<div class="sect2">\r
-<h3 id="_tiling_window_managers">1.1. Tiling window managers</h3>\r
+<h3 id="_tiling_window_managers">3.1. Tiling window managers</h3>\r
<div class="paragraph"><p>Traditionally, there are two approaches to managing windows: The most common\r
one nowadays is floating, which means the user can freely move/resize the\r
windows. The other approach is called tiling, which means that your window\r
the layout you need at the moment.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_the_layout_tree">1.2. The layout tree</h3>\r
+<h3 id="_the_layout_tree">3.2. The layout tree</h3>\r
<div class="paragraph"><p>The data structure which i3 uses to keep track of your windows is a tree. Every\r
node in the tree is a container (type <tt>Con</tt>). Some containers represent actual\r
windows (every container with a <tt>window != NULL</tt>), some represent split\r
workspace, the split container we are talking about is the workspace.</p></div>\r
<div class="paragraph"><p>To get an impression of how different layouts are represented, just play around\r
and look at the data structures — they are exposed as a JSON hash. See\r
-<a href="http://i3wm.org/docs/ipc.html#_tree_reply">http://i3wm.org/docs/ipc.html#_tree_reply</a> for documentation on that and an\r
+<a href="https://i3wm.org/docs/ipc.html#_tree_reply">https://i3wm.org/docs/ipc.html#_tree_reply</a> for documentation on that and an\r
example.</p></div>\r
</div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_files">2. Files</h2>\r
+<h2 id="_files">4. Files</h2>\r
<div class="sectionbody">\r
<div class="dlist"><dl>\r
<dt class="hdlist1">\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_data_structures">3. Data structures</h2>\r
+<h2 id="_data_structures">5. Data structures</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>See include/data.h for documented data structures. The most important ones are\r
explained right here.</p></div>\r
</ol></div>\r
<div class="paragraph"><p>The data type is <tt>Con</tt>, in all cases.</p></div>\r
<div class="sect2">\r
-<h3 id="_x11_root_window">3.1. X11 root window</h3>\r
+<h3 id="_x11_root_window">5.1. X11 root window</h3>\r
<div class="paragraph"><p>The X11 root window is a single window per X11 display (a display is identified\r
by <tt>:0</tt> or <tt>:1</tt> etc.). The root window is what you draw your background image\r
on. It spans all the available outputs, e.g. <tt>VGA1</tt> is a specific part of the\r
root window and <tt>LVDS1</tt> is a specific part of the root window.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_output_container">3.2. Output container</h3>\r
+<h3 id="_output_container">5.2. Output container</h3>\r
<div class="paragraph"><p>Every active output obtained through RandR is represented by one output\r
container. Outputs are considered active when a mode is configured (meaning\r
something is actually displayed on the output) and the output is not a clone.</p></div>\r
currently on.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_content_container">3.3. Content container</h3>\r
+<h3 id="_content_container">5.3. Content container</h3>\r
<div class="paragraph"><p>Each output has multiple children. Two of them are dock containers which hold\r
dock clients. The other one is the content container, which holds the actual\r
content (workspaces) of this output.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_workspace">3.4. Workspace</h3>\r
+<h3 id="_workspace">5.4. Workspace</h3>\r
<div class="paragraph"><p>A workspace is identified by its name. Basically, you could think of\r
workspaces as different desks in your office, if you like the desktop\r
metaphor. They just contain different sets of windows and are completely\r
desktops”.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_split_container">3.5. Split container</h3>\r
+<h3 id="_split_container">5.5. Split container</h3>\r
<div class="paragraph"><p>A split container is a container which holds an arbitrary amount of split\r
containers or X11 window containers. It has an orientation (horizontal or\r
vertical) and a layout.</p></div>\r
containers) can have different border styles.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_x11_window_container">3.6. X11 window container</h3>\r
+<h3 id="_x11_window_container">5.6. X11 window container</h3>\r
<div class="paragraph"><p>An X11 window container holds exactly one X11 window. These are the leaf nodes\r
of the layout tree, they cannot have any children.</p></div>\r
</div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_list_queue_macros">4. List/queue macros</h2>\r
+<h2 id="_list_queue_macros">6. List/queue macros</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>i3 makes heavy use of the list macros defined in BSD operating systems. To\r
ensure that the operating system on which i3 is compiled has all the expected\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_naming_conventions">5. Naming conventions</h2>\r
+<h2 id="_naming_conventions">7. Naming conventions</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>There is a row of standard variables used in many events. The following names\r
should be chosen for those:</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_startup_src_mainx_c_main">6. Startup (src/mainx.c, main())</h2>\r
+<h2 id="_startup_src_mainx_c_main">8. Startup (src/mainx.c, main())</h2>\r
<div class="sectionbody">\r
<div class="ulist"><ul>\r
<li>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_keybindings">7. Keybindings</h2>\r
+<h2 id="_keybindings">9. Keybindings</h2>\r
<div class="sectionbody">\r
<div class="sect2">\r
-<h3 id="_grabbing_the_bindings">7.1. Grabbing the bindings</h3>\r
+<h3 id="_grabbing_the_bindings">9.1. Grabbing the bindings</h3>\r
<div class="paragraph"><p>Grabbing the bindings is quite straight-forward. You pass X your combination of\r
modifiers and the keycode you want to grab and whether you want to grab them\r
actively or passively. Most bindings (everything except for bindings using\r
will handle the event, if not, it will replay the event.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_handling_a_keypress">7.2. Handling a keypress</h3>\r
+<h3 id="_handling_a_keypress">9.2. Handling a keypress</h3>\r
<div class="paragraph"><p>As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets\r
the correct state.</p></div>\r
<div class="paragraph"><p>Then, it looks through all bindings and gets the one which matches the received\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_manage_windows_src_main_c_manage_window_and_reparent_window">8. Manage windows (src/main.c, manage_window() and reparent_window())</h2>\r
+<h2 id="_manage_windows_src_main_c_manage_window_and_reparent_window">10. Manage windows (src/main.c, manage_window() and reparent_window())</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p><tt>manage_window()</tt> does some checks to decide whether the window should be\r
managed at all:</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_what_happens_when_an_application_is_started">9. What happens when an application is started?</h2>\r
+<h2 id="_what_happens_when_an_application_is_started">11. What happens when an application is started?</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>i3 does not care about applications. All it notices is when new windows are\r
mapped (see <tt>src/handlers.c</tt>, <tt>handle_map_request()</tt>). The window is then\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_net_wm_state">10. _NET_WM_STATE</h2>\r
+<h2 id="_net_wm_state">12. _NET_WM_STATE</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Only the _NET_WM_STATE_FULLSCREEN and _NET_WM_STATE_DEMANDS_ATTENTION atoms\r
are handled.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_wm_name">11. WM_NAME</h2>\r
+<h2 id="_wm_name">13. WM_NAME</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>When the WM_NAME property of a window changes, its decoration (containing the\r
title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_net_wm_name">12. _NET_WM_NAME</h2>\r
+<h2 id="_net_wm_name">14. _NET_WM_NAME</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME\r
is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_size_hints">13. Size hints</h2>\r
+<h2 id="_size_hints">15. Size hints</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Size hints specify the minimum/maximum size for a given window as well as its\r
aspect ratio. This is important for clients like mplayer, who only set the\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_rendering_src_layout_c_render_layout_and_render_container">14. Rendering (src/layout.c, render_layout() and render_container())</h2>\r
+<h2 id="_rendering_src_layout_c_render_layout_and_render_container">16. Rendering (src/layout.c, render_layout() and render_container())</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Rendering in i3 version 4 is the step which assigns the correct sizes for\r
borders, decoration windows, child windows and the stacking order of all\r
about the different rendering steps, in the order of "top of the tree" (root\r
container) to the bottom.</p></div>\r
<div class="sect2">\r
-<h3 id="_rendering_the_root_container">14.1. Rendering the root container</h3>\r
+<h3 id="_rendering_the_root_container">16.1. Rendering the root container</h3>\r
<div class="paragraph"><p>The i3 root container (<tt>con->type == CT_ROOT</tt>) represents the X11 root window.\r
It contains one child container for every output (like LVDS1, VGA1, …), which\r
is available on your computer.</p></div>\r
only called for the global fullscreen window.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_rendering_an_output">14.2. Rendering an output</h3>\r
+<h3 id="_rendering_an_output">16.2. Rendering an output</h3>\r
<div class="paragraph"><p>Output containers (<tt>con->layout == L_OUTPUT</tt>) represent a hardware output like\r
LVDS1, VGA1, etc. An output container has three children (at the moment): One\r
content container (having workspaces as children) and the top/bottom dock area\r
</ol></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_rendering_a_workspace_or_split_container">14.3. Rendering a workspace or split container</h3>\r
+<h3 id="_rendering_a_workspace_or_split_container">16.3. Rendering a workspace or split container</h3>\r
<div class="paragraph"><p>From here on, there really is no difference anymore. All containers are of\r
<tt>con->type == CT_CON</tt> (whether workspace or split container) and some of them\r
have a <tt>con->window</tt>, meaning they represent an actual window instead of a\r
split container.</p></div>\r
<div class="sect3">\r
-<h4 id="_default_layout">14.3.1. Default layout</h4>\r
+<h4 id="_default_layout">16.3.1. Default layout</h4>\r
<div class="paragraph"><p>In default layout, containers are placed horizontally or vertically next to\r
each other (depending on the <tt>con->orientation</tt>). If a child is a leaf node (as\r
opposed to a split container) and has border style "normal", appropriate space\r
will be reserved for its window decoration.</p></div>\r
</div>\r
<div class="sect3">\r
-<h4 id="_stacked_layout">14.3.2. Stacked layout</h4>\r
+<h4 id="_stacked_layout">16.3.2. Stacked layout</h4>\r
<div class="paragraph"><p>In stacked layout, only the focused window is actually shown (this is achieved\r
by calling <tt>x_raise_con()</tt> in reverse focus order at the end of <tt>render_con()</tt>).</p></div>\r
<div class="paragraph"><p>The available space for the focused window is the size of the container minus\r
the stacked container.</p></div>\r
</div>\r
<div class="sect3">\r
-<h4 id="_tabbed_layout">14.3.3. Tabbed layout</h4>\r
+<h4 id="_tabbed_layout">16.3.3. Tabbed layout</h4>\r
<div class="paragraph"><p>Tabbed layout works precisely like stacked layout, but the window decoration\r
position/size is different: They are placed next to each other on a single line\r
(fixed height).</p></div>\r
</div>\r
<div class="sect3">\r
-<h4 id="_dock_area_layout">14.3.4. Dock area layout</h4>\r
+<h4 id="_dock_area_layout">16.3.4. Dock area layout</h4>\r
<div class="paragraph"><p>This is a special case. Users cannot choose the dock area layout, but it will be\r
set for the dock area containers. In the dockarea layout (at the moment!),\r
windows will be placed above each other.</p></div>\r
</div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_rendering_a_window">14.4. Rendering a window</h3>\r
+<h3 id="_rendering_a_window">16.4. Rendering a window</h3>\r
<div class="paragraph"><p>A window’s size and position will be determined in the following way:</p></div>\r
<div class="olist arabic"><ol class="arabic">\r
<li>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_pushing_updates_to_x11_drawing">15. Pushing updates to X11 / Drawing</h2>\r
+<h2 id="_pushing_updates_to_x11_drawing">17. Pushing updates to X11 / Drawing</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>A big problem with i3 before version 4 was that we just sent requests to X11\r
anywhere in the source code. This was bad because nobody could understand the\r
</li>\r
</ol></div>\r
<div class="sect2">\r
-<h3 id="_pushing_state_to_x11">15.1. Pushing state to X11</h3>\r
+<h3 id="_pushing_state_to_x11">17.1. Pushing state to X11</h3>\r
<div class="paragraph"><p>In general, the function <tt>x_push_changes</tt> should be called to push state\r
changes. Only when the scope of the state change is clearly defined (for\r
example only the title of a window) and its impact is known beforehand, one can\r
<tt>WM_STATE_WITHDRAWN</tt>.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_drawing_window_decorations_borders_backgrounds">15.2. Drawing window decorations/borders/backgrounds</h3>\r
+<h3 id="_drawing_window_decorations_borders_backgrounds">17.2. Drawing window decorations/borders/backgrounds</h3>\r
<div class="paragraph"><p><tt>x_draw_decoration</tt> draws window decorations. It is run for every leaf\r
container (representing an actual X11 window) and for every non-leaf container\r
which is in a stacked/tabbed container (because stacked/tabbed containers\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_user_commands_parser_specs_commands_spec">16. User commands (parser-specs/commands.spec)</h2>\r
+<h2 id="_user_commands_parser_specs_commands_spec">18. User commands (parser-specs/commands.spec)</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>In the configuration file and when using i3 interactively (with <tt>i3-msg</tt>, for\r
example), you use commands to make i3 do things, like focus a different window,\r
in which the parser will transition into, or the keyword <em>call</em>, followed by\r
the name of a function (and optionally a state).</p></div>\r
<div class="sect2">\r
-<h3 id="_example_the_workspace_state">16.1. Example: The WORKSPACE state</h3>\r
+<h3 id="_example_the_workspace_state">18.1. Example: The WORKSPACE state</h3>\r
<div class="paragraph"><p>Let’s have a look at the WORKSPACE state, which is a good example of all\r
features. This is its definition:</p></div>\r
<div class="listingblock">\r
</dl></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_introducing_a_new_command">16.2. Introducing a new command</h3>\r
+<h3 id="_introducing_a_new_command">18.2. Introducing a new command</h3>\r
<div class="paragraph"><p>The following steps have to be taken in order to properly introduce a new\r
command (or possibly extend an existing command):</p></div>\r
<div class="olist arabic"><ol class="arabic">\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_moving_containers">17. Moving containers</h2>\r
+<h2 id="_moving_containers">19. Moving containers</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>The movement code is pretty delicate. You need to consider all cases before\r
making any changes or before being able to fully understand how it works.</p></div>\r
<div class="sect2">\r
-<h3 id="_case_1_moving_inside_the_same_container">17.1. Case 1: Moving inside the same container</h3>\r
+<h3 id="_case_1_moving_inside_the_same_container">19.1. Case 1: Moving inside the same container</h3>\r
<div class="paragraph"><p>The reference layout for this case is a single workspace in horizontal\r
orientation with two containers on it. Focus is on the left container (1).</p></div>\r
<div class="tableblock">\r
of the current one and swaps both containers.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_case_2_move_a_container_into_a_split_container">17.2. Case 2: Move a container into a split container</h3>\r
+<h3 id="_case_2_move_a_container_into_a_split_container">19.2. Case 2: Move a container into a split container</h3>\r
<div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two\r
containers. The right container is a v-split with two containers. Focus is on\r
the left container (1).</p></div>\r
be flattened.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_case_3_moving_to_non_existent_top_bottom">17.3. Case 3: Moving to non-existent top/bottom</h3>\r
+<h3 id="_case_3_moving_to_non_existent_top_bottom">19.3. Case 3: Moving to non-existent top/bottom</h3>\r
<div class="paragraph"><p>Like in case 1, the reference layout for this case is a single workspace in\r
horizontal orientation with two containers on it. Focus is on the left\r
container:</p></div>\r
flattened.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_case_4_moving_to_existent_top_bottom">17.4. Case 4: Moving to existent top/bottom</h3>\r
+<h3 id="_case_4_moving_to_existent_top_bottom">19.4. Case 4: Moving to existent top/bottom</h3>\r
<div class="paragraph"><p>The reference layout for this case is a vertical workspace with two containers.\r
The bottom one is a h-split containing two containers (1 and 2). Focus is on\r
the bottom left container (1).</p></div>\r
is in vertical orientation.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_case_5_moving_in_one_child_h_split">17.5. Case 5: Moving in one-child h-split</h3>\r
+<h3 id="_case_5_moving_in_one_child_h_split">19.5. Case 5: Moving in one-child h-split</h3>\r
<div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two\r
containers having a v-split on the left side with a one-child h-split on the\r
bottom. Focus is on the bottom left container (2(h)):</p></div>\r
4.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_case_6_floating_containers">17.6. Case 6: Floating containers</h3>\r
+<h3 id="_case_6_floating_containers">19.6. Case 6: Floating containers</h3>\r
<div class="paragraph"><p>The reference layout for this case is a horizontal workspace with two\r
containers plus one floating h-split container. Focus is on the floating\r
container.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_click_handling">18. Click handling</h2>\r
+<h2 id="_click_handling">20. Click handling</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Without much ado, here is the list of cases which need to be considered:</p></div>\r
<div class="ulist"><ul>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_gotchas">19. Gotchas</h2>\r
+<h2 id="_gotchas">21. Gotchas</h2>\r
<div class="sectionbody">\r
<div class="ulist"><ul>\r
<li>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_using_git_sending_patches">20. Using git / sending patches</h2>\r
-<div class="sectionbody">\r
-<div class="sect2">\r
-<h3 id="_introduction">20.1. Introduction</h3>\r
-<div class="paragraph"><p>For a short introduction into using git, see\r
-<a href="http://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy">http://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy</a>\r
-or, for more documentation, see <a href="http://git-scm.com/documentation">http://git-scm.com/documentation</a></p></div>\r
-<div class="paragraph"><p>Please talk to us before working on new features to see whether they will be\r
-accepted. A good way for this is to open an issue and asking for opinions on it.\r
-Even for accepted features, this can be a good way to refine an idea upfront. However,\r
-we don’t want to see certain features in i3, e.g., switching window focus in an\r
-Alt+Tab like way.</p></div>\r
-<div class="paragraph"><p>When working on bugfixes, please make sure you mention that you are working on\r
-it in the corresponding bug report at <a href="https://github.com/i3/i3/issues">https://github.com/i3/i3/issues</a>. In case\r
-there is no bug report yet, please create one.</p></div>\r
-<div class="paragraph"><p>After you are done, please submit your work for review as a pull request at\r
-<a href="https://github.com/i3/i3">https://github.com/i3/i3</a>.</p></div>\r
-<div class="paragraph"><p>Do not send emails to the mailing list or any author directly, and don’t submit\r
-them in the bugtracker, since all reviews should be done in public at\r
-<a href="https://github.com/i3/i3">https://github.com/i3/i3</a>. In order to make your review go as fast as possible, you\r
-could have a look at previous reviews and see what the common mistakes are.</p></div>\r
-</div>\r
-<div class="sect2">\r
-<h3 id="_which_branch_to_use">20.2. Which branch to use?</h3>\r
-<div class="paragraph"><p>Work on i3 generally happens in two branches: “master” and “next” (the latter\r
-being the default branch, the one that people get when they check out the git\r
-repository).</p></div>\r
-<div class="paragraph"><p>The contents of “master” are always stable. That is, it contains the source code\r
-of the latest release, plus any bugfixes that were applied since that release.</p></div>\r
-<div class="paragraph"><p>New features are only found in the “next” branch. Therefore, if you are working\r
-on a new feature, use the “next” branch. If you are working on a bugfix, use the\r
-“next” branch, too, but make sure your code also works on “master”.</p></div>\r
-</div>\r
-<div class="sect2">\r
-<h3 id="_how_to_build">20.3. How to build?</h3>\r
-<div class="paragraph"><p>You can build i3 like you build any other software package which uses autotools.\r
-Here’s a memory refresher:</p></div>\r
-<div class="literalblock">\r
-<div class="content">\r
-<pre><tt>$ autoreconf -fi\r
-$ mkdir -p build && cd build\r
-$ ../configure\r
-$ make -j8</tt></pre>\r
-</div></div>\r
-<div class="paragraph"><p>(The autoreconf -fi step is unnecessary if you are building from a release tarball,\r
- but shouldn’t hurt either.)</p></div>\r
-<div class="sect3">\r
-<h4 id="_build_system_features">20.3.1. Build system features</h4>\r
-<div class="ulist"><ul>\r
-<li>\r
-<p>\r
-We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate\r
- directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building\r
- in a separate directory is common practice anyway. In case this causes any\r
- trouble when packaging i3 for your distribution, please open an issue.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-“make check” runs the i3 testsuite. See docs/testsuite for details.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-“make distcheck” (runs testsuite on “make dist” result, tiny bit quicker\r
- feedback cycle than waiting for the travis build to catch the issue).\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-“make uninstall” (occasionally requested by users who compile from source)\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-“make” will build manpages/docs by default if the tools are installed.\r
- Conversely, manpages/docs are not tried to be built for users who don’t want\r
- to install all these dependencies to get started hacking on i3.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-non-release builds will enable address sanitizer by default. Use the\r
- --disable-sanitizers configure option to turn off all sanitizers, and see\r
- --help for available sanitizers.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Support for pre-compiled headers (PCH) has been dropped for now in the\r
- interest of simplicity. If you need support for PCH, please open an issue.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Coverage reports are now generated using “make check-code-coverage”, which\r
- requires specifying --enable-code-coverage when calling configure.\r
-</p>\r
-</li>\r
-</ul></div>\r
-</div>\r
-</div>\r
-</div>\r
-</div>\r
-<div class="sect1">\r
-<h2 id="_thought_experiments">21. Thought experiments</h2>\r
+<h2 id="_thought_experiments">22. Thought experiments</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>In this section, we collect thought experiments, so that we don’t forget our\r
thoughts about specific topics. They are not necessary to get into hacking i3,\r
before asking us why things are the way they are or why we don’t implement\r
things.</p></div>\r
<div class="sect2">\r
-<h3 id="_using_cgroups_per_workspace">21.1. Using cgroups per workspace</h3>\r
+<h3 id="_using_cgroups_per_workspace">22.1. Using cgroups per workspace</h3>\r
<div class="paragraph"><p>cgroups (control groups) are a linux-only feature which provides the ability to\r
group multiple processes. For each group, you can individually set resource\r
limits, like allowed memory usage. Furthermore, and more importantly for our\r
\n.</p></div>\r
<div class="paragraph"><p>You can find an example of a shell script which can be used as your\r
<tt>status_command</tt> in the bar configuration at\r
-<a href="http://code.stapelberg.de/git/i3/tree/contrib/trivial-bar-script.sh?h=next">http://code.stapelberg.de/git/i3/tree/contrib/trivial-bar-script.sh?h=next</a></p></div>\r
+<a href="https://github.com/i3/i3/blob/next/contrib/trivial-bar-script.sh">https://github.com/i3/i3/blob/next/contrib/trivial-bar-script.sh</a></p></div>\r
<div class="sect2">\r
<h3 id="_header_in_detail">2.1. Header in detail</h3>\r
<div class="dlist"><dl>\r
<div class="sect1">\r
<h2 id="_description">4. DESCRIPTION</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>i3status is a small program (about 1500 SLOC) for generating a status bar for\r
+<div class="paragraph"><p>i3status is a small program for generating a status bar for\r
i3bar, dzen2, xmobar or similar programs. It is designed to be very\r
efficient by issuing a very small number of system calls, as one generally\r
wants to update such a status line every second. This ensures that even under\r
group: Docs
---
<div id="content">
-<h2>Documentation for i3 v4.14.1</h2>
+<h2>Documentation for i3 v4.15</h2>
<p>
One of i3’s goals is good documentation. The documents which you will find
<h1>IPC interface (interprocess communication)</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">October 2014</span>\r
+<span id="revdate">September 2017</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 class="paragraph"><p>The magic string currently is "i3-ipc" and will only be changed when a change\r
in the IPC API is done which breaks compatibility (we hope that we don’t need\r
to do that).</p></div>\r
-<div class="paragraph"><p>Currently implemented message types are the following:</p></div>\r
-<div class="dlist"><dl>\r
-<dt class="hdlist1">\r
-COMMAND (0)\r
-</dt>\r
-<dd>\r
-<p>\r
- The payload of the message is a command for i3 (like the commands you\r
- can bind to keys in the configuration file) and will be executed\r
- directly after receiving it.\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-GET_WORKSPACES (1)\r
-</dt>\r
-<dd>\r
-<p>\r
- Gets the current workspaces. The reply will be a JSON-encoded list of\r
- workspaces (see the reply section).\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-SUBSCRIBE (2)\r
-</dt>\r
-<dd>\r
-<p>\r
- Subscribes your connection to certain events. See <a href="#events">[events]</a> for a\r
- description of this message and the concept of events.\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-GET_OUTPUTS (3)\r
-</dt>\r
-<dd>\r
-<p>\r
- Gets the current outputs. The reply will be a JSON-encoded list of outputs\r
- (see the reply section).\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-GET_TREE (4)\r
-</dt>\r
-<dd>\r
-<p>\r
- Gets the layout tree. i3 uses a tree as data structure which includes\r
- every container. The reply will be the JSON-encoded tree (see the reply\r
- section).\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-GET_MARKS (5)\r
-</dt>\r
-<dd>\r
-<p>\r
- Gets a list of marks (identifiers for containers to easily jump to them\r
- later). The reply will be a JSON-encoded list of window marks (see\r
- reply section).\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-GET_BAR_CONFIG (6)\r
-</dt>\r
-<dd>\r
-<p>\r
- Gets the configuration (as JSON map) of the workspace bar with the\r
- given ID. If no ID is provided, an array with all configured bar IDs is\r
- returned instead.\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-GET_VERSION (7)\r
-</dt>\r
-<dd>\r
-<p>\r
- Gets the version of i3. The reply will be a JSON-encoded dictionary\r
- with the major, minor, patch and human-readable version.\r
-</p>\r
-</dd>\r
-<dt class="hdlist1">\r
-GET_BINDING_MODES (8)\r
-</dt>\r
-<dd>\r
-<p>\r
- Gets a list of currently configured binding modes.\r
-</p>\r
-</dd>\r
-</dl></div>\r
+<div class="tableblock">\r
+<table rules="all"\r
+width="100%"\r
+frame="border"\r
+cellspacing="0" cellpadding="4">\r
+<caption class="title">Table 1. Currently implemented message types</caption>\r
+<col width="10%" />\r
+<col width="20%" />\r
+<col width="20%" />\r
+<col width="50%" />\r
+<thead>\r
+<tr>\r
+<th align="center" valign="top"> Type (numeric) </th>\r
+<th align="center" valign="top"> Type (name) </th>\r
+<th align="center" valign="top"> Reply type </th>\r
+<th align="center" valign="top"> Purpose</th>\r
+</tr>\r
+</thead>\r
+<tbody>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">0</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>RUN_COMMAND</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_command_reply">COMMAND</a></p></td>\r
+<td align="center" valign="top"><p class="table">Run the payload as an i3 command (like the commands you can bind to keys).</p></td>\r
+</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">1</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>GET_WORKSPACES</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_workspaces_reply">WORKSPACES</a></p></td>\r
+<td align="center" valign="top"><p class="table">Get the list of current workspaces.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">2</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>SUBSCRIBE</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_subscribe_reply">SUBSCRIBE</a></p></td>\r
+<td align="center" valign="top"><p class="table">Subscribe this IPC connection to the event types specified in the message payload. See <a href="#events">[events]</a>.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">3</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>GET_OUTPUTS</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_outputs_reply">OUTPUTS</a></p></td>\r
+<td align="center" valign="top"><p class="table">Get the list of current outputs.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">4</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>GET_TREE</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_tree_reply">TREE</a></p></td>\r
+<td align="center" valign="top"><p class="table">Get the i3 layout tree.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">5</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>GET_MARKS</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_marks_reply">MARKS</a></p></td>\r
+<td align="center" valign="top"><p class="table">Gets the names of all currently set marks.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">6</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>GET_BAR_CONFIG</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_bar_config_reply">BAR_CONFIG</a></p></td>\r
+<td align="center" valign="top"><p class="table">Gets the specified bar configuration or the names of all bar configurations if payload is empty.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">7</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>GET_VERSION</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_version_reply">VERSION</a></p></td>\r
+<td align="center" valign="top"><p class="table">Gets the i3 version.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">8</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>GET_BINDING_MODES</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_binding_modes_reply">BINDING_MODES</a></p></td>\r
+<td align="center" valign="top"><p class="table">Gets the names of all currently configured binding modes.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">9</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>GET_CONFIG</tt></p></td>\r
+<td align="center" valign="top"><p class="table"><a href="#_config_reply">CONFIG</a></p></td>\r
+<td align="center" valign="top"><p class="table">Returns the last loaded i3 config.</p></td>\r
+</tr>\r
+</tbody>\r
+</table>\r
+</div>\r
<div class="paragraph"><p>So, a typical message could look like this:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
</dt>\r
<dd>\r
<p>\r
- Confirmation/Error code for the COMMAND message.\r
+ Confirmation/Error code for the RUN_COMMAND message.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
Reply to the GET_BINDING_MODES message.\r
</p>\r
</dd>\r
+<dt class="hdlist1">\r
+GET_CONFIG (9)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Reply to the GET_CONFIG message.\r
+</p>\r
+</dd>\r
</dl></div>\r
</div>\r
<div class="sect2">\r
</dt>\r
<dd>\r
<p>\r
- Whether this container (window or workspace) has the urgency hint set.\r
+ Whether this container (window, split container, floating container or\r
+ workspace) has the urgency hint set, directly or indirectly. All parent\r
+ containers up until the workspace container will be marked urgent if they\r
+ have at least one urgent child.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
Whether this container is currently focused.\r
</p>\r
</dd>\r
+<dt class="hdlist1">\r
+focus (array of integer)\r
+</dt>\r
+<dd>\r
+<p>\r
+ List of child node IDs (see <tt>nodes</tt>, <tt>floating_nodes</tt> and <tt>id</tt>) in focus\r
+ order. Traversing the tree by following the first entry in this array\r
+ will result in eventually reaching the one node with <tt>focused</tt> set to\r
+ true.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+nodes (array of node)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The tiling (i.e. non-floating) child containers of this node.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+floating_nodes (array of node)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The floating child containers of this node. Only non-empty on nodes with\r
+ type <tt>workspace</tt>.\r
+</p>\r
+</dd>\r
</dl></div>\r
<div class="paragraph"><p>Please note that in the following example, I have left out some keys/values\r
which are not relevant for the type of the node. Otherwise, the example would\r
<pre><tt>["default", "resize"]</tt></pre>\r
</div></div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_config_reply">3.11. CONFIG reply</h3>\r
+<div class="paragraph"><p>The config reply is a map which currently only contains the "config" member,\r
+which is a string containing the config file as loaded by i3 most recently.</p></div>\r
+<div class="paragraph"><p><strong>Example:</strong></p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{ "config": "font pango:monospace 8\nbindsym Mod4+q exit\n" }</tt></pre>\r
+</div></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
</li>\r
<li>\r
<p>\r
+<a href="https://github.com/Ceryn/i3msg-python">https://github.com/Ceryn/i3msg-python</a>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
<a href="https://github.com/whitelynx/i3ipc">https://github.com/whitelynx/i3ipc</a> (not maintained)\r
</p>\r
</li>\r
</dl></div>\r
</div>\r
</div>\r
+<div class="sect1">\r
+<h2 id="_appendix_a_detecting_byte_order_in_memory_safe_languages">6. Appendix A: Detecting byte order in memory-safe languages</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>Some programming languages such as Go don’t offer a way to serialize data in the\r
+native byte order of the machine they’re running on without resorting to tricks\r
+involving the <tt>unsafe</tt> package.</p></div>\r
+<div class="paragraph"><p>The following technique can be used (and will not be broken by changes to i3) to\r
+detect the byte order i3 is using:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+The byte order dependent fields of an IPC message are message type and\r
+ payload length.\r
+</p>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+The message type <tt>RUN_COMMAND</tt> (0) is the same in big and little endian, so\r
+ we can use it in either byte order to elicit a reply from i3.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The payload length 65536 + 256 (<tt>0x00 01 01 00</tt>) is the same in big and\r
+ little endian, and also small enough to not worry about memory allocations\r
+ of that size. We must use payloads of length 65536 + 256 in every message\r
+ we send, so that i3 will be able to read the entire message regardless of\r
+ the byte order it uses.\r
+</p>\r
+</li>\r
+</ul></div>\r
+</li>\r
+<li>\r
+<p>\r
+Send a big endian encoded message of type <tt>SUBSCRIBE</tt> (2) with payload <tt>[]</tt>\r
+ followed by 65536 + 256 - 2 <tt>SPACE</tt> (ASCII 0x20) bytes.\r
+</p>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+If i3 is running in big endian, this message is treated as a noop,\r
+ resulting in a <tt>SUBSCRIBE</tt> reply with payload <tt>{"success":true}</tt>\r
+ <span class="footnote"><br />[A small payload is important: that way, we circumvent dealing\r
+ with UNIX domain socket buffer sizes, whose size depends on the\r
+ implementation/operating system. Exhausting such a buffer results in an i3\r
+ deadlock unless you concurrently read and write, which — depending on the\r
+ programming language — makes the technique much more complicated.]<br /></span>.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+If i3 is running in little endian, this message is read in its entirety due\r
+ to the byte order independent payload length, then\r
+ <a href="https://github.com/i3/i3/blob/d726d09d496577d1c337a4b97486f2c9fbc914f1/src/ipc.c#L1188">silently\r
+ discarded</a> due to the unknown message type.\r
+</p>\r
+</li>\r
+</ul></div>\r
+</li>\r
+<li>\r
+<p>\r
+Send a byte order independent message, i.e. type <tt>RUN_COMMAND</tt> (0) with\r
+ payload <tt>nop byte order detection. padding:</tt>, padded to 65536 + 256 bytes\r
+ with <tt>a</tt> (ASCII 0x61) bytes. i3 will reply to this message with a reply of\r
+ type <tt>COMMAND</tt> (0).\r
+</p>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+The human-readable prefix is in there to not confuse readers of the i3 log.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+This messages serves as a synchronization primitive so that we know whether\r
+ i3 discarded the <tt>SUBSCRIBE</tt> message or didn’t answer it yet.\r
+</p>\r
+</li>\r
+</ul></div>\r
+</li>\r
+<li>\r
+<p>\r
+Receive a message header from i3, decoding the message type as big endian.\r
+</p>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+If the message’s reply type is <tt>COMMAND</tt> (0), i3 is running in little\r
+ endian (because the <tt>SUBSCRIBE</tt> message was discarded). Decode the message\r
+ payload length as little endian, receive the message payload.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+If the message’s reply type is anything else, i3 is running in big endian\r
+ (because our big endian encoded <tt>SUBSCRIBE</tt> message was answered). Decode\r
+ the message payload length in big endian, receive the message\r
+ payload. Then, receive the pending <tt>COMMAND</tt> message reply in big endian.\r
+</p>\r
+</li>\r
+</ul></div>\r
+</li>\r
+<li>\r
+<p>\r
+From here on out, send/receive all messages using the detected byte order.\r
+</p>\r
+</li>\r
+</ol></div>\r
+</div>\r
+</div>\r
</div>\r
<div id="footnotes"><hr /></div>\r
<div id="footer" lang="de">\r
<strong>swallowed</strong> by the placeholder container, hence the term.</p></div>\r
<div class="paragraph"><p>Note: Swallowing windows into unsatisfied placeholder windows takes precedence\r
over\r
-<a href="http://i3wm.org/docs/userguide.html#_automatically_putting_clients_on_specific_workspaces">assignment\r
+<a href="https://i3wm.org/docs/userguide.html#_automatically_putting_clients_on_specific_workspaces">assignment\r
rules</a>. For example, if you assign all Emacs windows to workspace 1 in your i3\r
configuration file, but there is a placeholder window on workspace 2 which\r
matches Emacs as well, your newly started Emacs window will end up in the\r
</a>\r
</span></p></div>\r
<div class="paragraph"><p>The structure of this JSON file looks a lot like the <tt>TREE</tt> reply, see\r
-<a href="http://build.i3wm.org/docs/ipc.html#_tree_reply">http://build.i3wm.org/docs/ipc.html#_tree_reply</a> for documentation on that. Some\r
+<a href="https://build.i3wm.org/docs/ipc.html#_tree_reply">https://build.i3wm.org/docs/ipc.html#_tree_reply</a> for documentation on that. Some\r
properties are excluded because they are not relevant when restoring a layout.</p></div>\r
<div class="paragraph"><p>Most importantly, look at the "swallows" section of each window. This is where\r
you need to be more or less specific. As an example, remember the section about\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
-<a href="http://cr.i3wm.org/">submit a patch</a> to make <tt>i3-save-tree(1)</tt> optionally\r
-output standard-conforming JSON.</p></div>\r
+<a href="https://github.com/i3/i3/blob/next/.github/CONTRIBUTING.md">submit a patch</a>\r
+to make <tt>i3-save-tree(1)</tt> optionally output standard-conforming JSON.</p></div>\r
</div>\r
</div>\r
</div>\r
<tr>
<td><img class="i3mod" src="logo-30.png" alt="" /> + <kbd>;</kbd>
<td>focus right
+ <tr>
+ <td><img class="i3mod" src="logo-30.png" alt="" /> + <kbd>a</kbd>
+ <td>focus parent
<tr>
<td><img class="i3mod" src="logo-30.png" alt="" /> + <kbd></kbd>
<td>toggle focus mode
release of i3. To use it, run the following commands:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ /usr/lib/apt/apt-helper download-file http://debian.sur5r.net/i3/pool/main/s/sur5r-keyring/sur5r-keyring_2017.01.02_all.deb keyring.deb SHA256:4c3c6685b1181d83efe3a479c5ae38a2a44e23add55e16a328b8c8560bf05e5f\r
+<pre><tt>$ /usr/lib/apt/apt-helper download-file http://debian.sur5r.net/i3/pool/main/s/sur5r-keyring/sur5r-keyring_2018.01.30_all.deb keyring.deb SHA256:baa43dbbd7232ea2b5444cae238d53bebb9d34601cc000e82f11111b1889078a\r
# dpkg -i ./keyring.deb\r
# echo "deb http://debian.sur5r.net/i3/ $(grep '^DISTRIB_CODENAME=' /etc/lsb-release | cut -f2 -d=) universe" >> /etc/apt/sources.list.d/sur5r-i3.list\r
# apt update\r
<p>\r
The latest Perl documentation of the "i3test" (general testcase setup) and\r
"i3test::Test" (additional test instructions) modules:\r
- <a href="http://build.i3wm.org/docs/lib-i3test.html">http://build.i3wm.org/docs/lib-i3test.html</a> respectively\r
- <a href="http://build.i3wm.org/docs/lib-i3test-test.html">http://build.i3wm.org/docs/lib-i3test-test.html</a>\r
+ <a href="https://build.i3wm.org/docs/lib-i3test.html">https://build.i3wm.org/docs/lib-i3test.html</a> respectively\r
+ <a href="https://build.i3wm.org/docs/lib-i3test-test.html">https://build.i3wm.org/docs/lib-i3test-test.html</a>\r
</p>\r
</li>\r
<li>\r
<p>\r
The latest documentation on i3’s IPC interface:\r
- <a href="http://build.i3wm.org/docs/ipc.html">http://build.i3wm.org/docs/ipc.html</a>\r
+ <a href="https://build.i3wm.org/docs/ipc.html">https://build.i3wm.org/docs/ipc.html</a>\r
</p>\r
</li>\r
</ol></div>\r
used to install the testsuite. Many users prefer to use the more modern\r
<tt>cpanminus</tt> instead, though (because it asks no questions and just works):</p></div>\r
<div class="paragraph"><p>The tests additionally require <tt>Xephyr(1)</tt> to run a nested X server. Install\r
-<tt>xserver-xephyr</tt> on Debian or <tt>xorg-xserver-xephyr</tt> on Arch Linux.</p></div>\r
+<tt>xserver-xephyr</tt> on Debian or <tt>xorg-server-xephyr</tt> on Arch Linux.</p></div>\r
<div class="listingblock">\r
<div class="title">Installing testsuite dependencies using cpanminus (preferred)</div>\r
<div class="content">\r
$ sudo apt-get install cpanminus\r
$ sudo cpanm .\r
$ cd ~/i3/AnyEvent-I3\r
+$ sudo cpanm Module::Install\r
$ sudo cpanm .</tt></pre>\r
</div></div>\r
<div class="paragraph"><p>If you don’t want to use cpanminus for some reason, the same works with cpan:</p></div>\r
<pre><tt>$ cd ~/i3/testcases\r
$ sudo cpan .\r
$ cd ~/i3/AnyEvent-I3\r
+$ sudo cpan Module::Install\r
$ sudo cpan .</tt></pre>\r
</div></div>\r
<div class="paragraph"><p>In case you don’t have root permissions, you can also install into your home\r
-directory, see <a href="http://michael.stapelberg.de/cpan/">http://michael.stapelberg.de/cpan/</a></p></div>\r
+directory, see <a href="https://michael.stapelberg.de/cpan/">https://michael.stapelberg.de/cpan/</a></p></div>\r
</div>\r
<div class="sect2">\r
<h3 id="_mechanisms">3.2. Mechanisms</h3>\r
interface which i3 provides. It is used for the startup process of i3, for\r
terminating it cleanly and (most importantly) for modifying and getting the\r
current state (layout tree).</p></div>\r
-<div class="paragraph"><p>See [<a href="http://i3wm.org/docs/ipc.html">http://i3wm.org/docs/ipc.html</a>] for documentation on the IPC interface.</p></div>\r
+<div class="paragraph"><p>See [<a href="https://i3wm.org/docs/ipc.html">https://i3wm.org/docs/ipc.html</a>] for documentation on the IPC interface.</p></div>\r
</div>\r
<div class="sect3">\r
<h4 id="_x11_xcb">3.2.4. X11::XCB</h4>\r
vertically split terminals on the right, focus is on the bottom right one. When\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 solution is to use <tt>focus parent</tt> (<tt>$mod+a</tt> by default), 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
<div class="paragraph"><p>The first part of the WM_CLASS is the instance ("irssi" in this example), the\r
second part is the class ("URxvt" in this example).</p></div>\r
<div class="paragraph"><p>Should you have any problems with assignments, make sure to check the i3\r
-logfile first (see <a href="http://i3wm.org/docs/debugging.html">http://i3wm.org/docs/debugging.html</a>). It includes more\r
+logfile first (see <a href="https://i3wm.org/docs/debugging.html">https://i3wm.org/docs/debugging.html</a>). It includes more\r
details about the matching process and the window’s actual class, instance and\r
title when starting up.</p></div>\r
<div class="paragraph"><p>Note that if you want to start an application just once on a specific\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
available outputs by running <tt>xrandr --current</tt>.</p></div>\r
+<div class="paragraph"><p>If your X server supports RandR 1.5 or newer, i3 will use RandR monitor objects\r
+instead of output objects. Run <tt>xrandr --listmonitors</tt> to see a list. Usually,\r
+a monitor object contains exactly one output, and has the same name as the\r
+output; but should that not be the case, you may specify the name of either the\r
+monitor or the output in i3’s configuration. For example, the Dell UP2414Q uses\r
+two scalers internally, so its output names might be “DP1” and “DP2”, but the\r
+monitor name is “Dell UP2414Q”.</p></div>\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>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>\r
<div class="sect2">\r
<h3 id="_forcing_xinerama">4.25. Forcing Xinerama</h3>\r
-<div class="paragraph"><p>As explained in-depth in <a href="http://i3wm.org/docs/multi-monitor.html">http://i3wm.org/docs/multi-monitor.html</a>, some X11\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
inferior Xinerama API explicitly and therefore don’t provide support for\r
# Focus the primary output\r
bindsym $mod+x focus 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>\r
+<div class="sect2">\r
+<h3 id="_moving_containers">6.5. Moving containers</h3>\r
+<div class="paragraph"><p>Use the <tt>move</tt> command to move a container.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>=== Moving containers\r
-\r
-Use the +move+ command to move a container.\r
-\r
-*Syntax*:</tt></pre>\r
-</div></div>\r
-<div class="paragraph"><p># Moves the container into the given direction.\r
+<pre><tt># Moves the container into the given direction.\r
# The optional pixel argument specifies how far the\r
# container should be moved if it is floating and\r
# defaults to 10 pixels.\r
-move <left|right|down|up> [<px> px]</p></div>\r
-<div class="paragraph"><p># Moves the container either to a specific location\r
-# or to the center of the screen. If <em>absolute</em> is\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
-move [absolute] position center</p></div>\r
-<div class="paragraph"><p># Moves the container to the current position of the\r
+move [absolute] position center\r
+\r
+# Moves the container to the current position of the\r
# mouse cursor. Only affects floating containers.\r
-move position mouse</p></div>\r
+move position mouse</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>*Examples*:</tt></pre>\r
-</div></div>\r
-<div class="paragraph"><p># Move container to the left, bottom, top, right\r
+<pre><tt># Move container to the left, bottom, top, right\r
bindsym $mod+j move left\r
bindsym $mod+k move down\r
bindsym $mod+l move up\r
-bindsym $mod+semicolon move right</p></div>\r
-<div class="paragraph"><p># Move container, but make floating containers\r
+bindsym $mod+semicolon move right\r
+\r
+# Move container, but make floating containers\r
# move more than the default\r
-bindsym $mod+j move left 20 px</p></div>\r
-<div class="paragraph"><p># Move floating container to the center of all outputs\r
-bindsym $mod+c move absolute position center</p></div>\r
-<div class="paragraph"><p># Move container to the current position of the cursor\r
-bindsym $mod+m move position mouse</p></div>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>=== Swapping containers\r
+bindsym $mod+j move left 20 px\r
\r
-Two containers can be swapped (i.e., move to each other's position) by using\r
-the +swap+ command. They will assume the position and geometry of the container\r
-they are swapped with.\r
+# Move floating container to the center of all outputs\r
+bindsym $mod+c move absolute position center\r
\r
-The first container to participate in the swapping can be selected through the\r
+# Move container to the current position of the cursor\r
+bindsym $mod+m move position mouse</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_swapping_containers">6.6. Swapping containers</h3>\r
+<div class="paragraph"><p>Two containers can be swapped (i.e., move to each other’s position) by using\r
+the <tt>swap</tt> command. They will assume the position and geometry of the container\r
+they are swapped with.</p></div>\r
+<div class="paragraph"><p>The first container to participate in the swapping can be selected through the\r
normal command criteria process with the focused window being the usual\r
fallback if no criteria are specified. The second container can be selected\r
-using one of the following methods:\r
-\r
-+id+:: The X11 window ID of a client window.\r
-+con_id+:: The i3 container ID of a container.\r
-+mark+:: A container with the specified mark, see <<vim_like_marks>>.\r
-\r
-Note that swapping does not work with all containers. Most notably, swapping\r
+using one of the following methods:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+<tt>id</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+The X11 window ID of a client window.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+<tt>con_id</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+The i3 container ID of a container.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+<tt>mark</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+A container with the specified mark, see <a href="#vim_like_marks">[vim_like_marks]</a>.\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p>Note that swapping does not work with all containers. Most notably, swapping\r
floating containers or containers that have a parent-child relationship to one\r
-another does not work.\r
-\r
-*Syntax*:</tt></pre>\r
+another does not work.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>swap container with id|con_id|mark <arg></tt></pre>\r
</div></div>\r
-</div>\r
-</div>\r
-</div>\r
-<div class="sect1">\r
-<h2 id="_swap_container_with_id_con_id_mark_lt_arg_gt">7. swap container with id|con_id|mark <arg></h2>\r
-<div class="sectionbody">\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
# Swaps container marked »A« and »B«\r
[con_mark="^A$"] swap container with mark B</tt></pre>\r
</div></div>\r
+</div>\r
<div class="sect2">\r
-<h3 id="_sticky_floating_windows">7.1. Sticky floating windows</h3>\r
+<h3 id="_sticky_floating_windows">6.7. Sticky floating windows</h3>\r
<div class="paragraph"><p>If you want a window to stick to the glass, i.e., have it stay on screen even\r
if you switch to another workspace, you can use the <tt>sticky</tt> command. For\r
example, this can be useful for notepads, a media player or a video chat\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_changing_named_workspaces_moving_to_workspaces">7.2. Changing (named) workspaces/moving to workspaces</h3>\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
bindsym $mod+F1 [class="Firefox"] move workspace current</tt></pre>\r
</div></div>\r
<div class="sect3">\r
-<h4 id="_named_workspaces">7.2.1. Named workspaces</h4>\r
+<h4 id="_named_workspaces">6.8.1. Named workspaces</h4>\r
<div class="paragraph"><p>Workspaces are identified by their name. So, instead of using numbers in the\r
workspace command, you can use an arbitrary name:</p></div>\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
specify a default name if there’s currently no workspace starting with a "1".</p></div>\r
</div>\r
<div class="sect3">\r
-<h4 id="_renaming_workspaces">7.2.2. Renaming workspaces</h4>\r
+<h4 id="_renaming_workspaces">6.8.2. Renaming workspaces</h4>\r
<div class="paragraph"><p>You can rename workspaces. This might be useful to start with the default\r
numbered workspaces, do your work, and rename the workspaces afterwards to\r
reflect what’s actually on them. You can also omit the old name to rename\r
</div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_moving_workspaces_to_a_different_screen">7.3. Moving workspaces to a different screen</h3>\r
+<h3 id="_moving_workspaces_to_a_different_screen">6.9. Moving workspaces to a different screen</h3>\r
<div class="paragraph"><p>See <a href="#move_to_outputs">[move_to_outputs]</a> for how to move a container/workspace to a different\r
RandR output.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_moving_containers_workspaces_to_randr_outputs">7.4. Moving containers/workspaces to RandR outputs</h3>\r
+<h3 id="_moving_containers_workspaces_to_randr_outputs">6.10. 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
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_move_window_container_to_mark_lt_mark_gt">8. move window|container to mark <mark></h2>\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
<pre><tt>for_window [instance="tabme"] move window to mark target</tt></pre>\r
</div></div>\r
<div class="sect2">\r
-<h3 id="resizingconfig">8.1. Resizing containers/windows</h3>\r
+<h3 id="resizingconfig">7.1. 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></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_jumping_to_specific_windows">8.2. Jumping to specific windows</h3>\r
+<h3 id="_jumping_to_specific_windows">7.2. 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">8.3. VIM-like marks (mark/goto)</h3>\r
+<h3 id="vim_like_marks">7.3. 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">8.4. Window title format</h3>\r
+<h3 id="pango_markup">7.4. 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">8.5. Changing border style</h3>\r
+<h3 id="_changing_border_style">7.5. 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></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="shmlog">8.6. Enabling shared memory logging</h3>\r
-<div class="paragraph"><p>As described in <a href="http://i3wm.org/docs/debugging.html">http://i3wm.org/docs/debugging.html</a>, i3 can log to a shared\r
+<h3 id="shmlog">7.6. 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 class="paragraph"><p>Note that when using <tt>shmlog <size_in_bytes></tt>, the current log will be\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_enabling_debug_logging">8.7. Enabling debug logging</h3>\r
+<h3 id="_enabling_debug_logging">7.7. 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">8.8. Reloading/Restarting/Exiting</h3>\r
+<h3 id="_reloading_restarting_exiting">7.8. 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">8.9. Scratchpad</h3>\r
+<h3 id="_scratchpad">7.9. 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">8.10. Nop</h3>\r
+<h3 id="_nop">7.10. 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">8.11. i3bar control</h3>\r
+<h3 id="_i3bar_control">7.11. 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">9. Multiple monitors</h2>\r
+<h2 id="multi_monitor">8. 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">9.1. Configuring your monitors</h3>\r
+<h3 id="_configuring_your_monitors">8.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">9.2. Interesting configuration for multi-monitor environments</h3>\r
+<h3 id="_interesting_configuration_for_multi_monitor_environments">8.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">10. i3 and the rest of your software world</h2>\r
+<h2 id="_i3_and_the_rest_of_your_software_world">9. i3 and the rest of your software world</h2>\r
<div class="sectionbody">\r
<div class="sect2">\r
-<h3 id="_displaying_a_status_line">10.1. Displaying a status line</h3>\r
+<h3 id="_displaying_a_status_line">9.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">10.2. Giving presentations (multi-monitor)</h3>\r
+<h3 id="presentations">9.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">10.2.1. Case 1: everybody gets the same output</h4>\r
+<h4 id="_case_1_everybody_gets_the_same_output">9.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">10.2.2. Case 2: you can see more than your audience</h4>\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
<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 class="sectionbody">\r
<div class="paragraph"><p><tt>i3-wsbar</tt> used to be the reference implementation before we had <tt>i3bar</tt>.\r
Nowadays, it is not shipped with release tarballs, but you can still get it at\r
-<a href="http://code.stapelberg.de/git/i3/tree/contrib/i3-wsbar">http://code.stapelberg.de/git/i3/tree/contrib/i3-wsbar</a></p></div>\r
+<a href="https://github.com/i3/i3/blob/next/contrib/i3-wsbar">https://github.com/i3/i3/blob/next/contrib/i3-wsbar</a></p></div>\r
<div class="sect2">\r
<h3 id="_the_big_picture">5.1. The big picture</h3>\r
<div class="paragraph"><p>The most common reason to use an external workspace bar is to integrate system\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_verify_you_are_using_i3_4_14_1">1. Verify you are using i3 ≥ 4.14.1</h2>\r
+<h2 id="_verify_you_are_using_i3_4_15">1. Verify you are using i3 ≥ 4.15</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="paragraph"><p>When sending bug reports, please attach the <strong>whole</strong> log file. Even if you think\r
you found the section which clearly highlights the problem, additional\r
information might be necessary to completely diagnose the problem.</p></div>\r
-<div class="paragraph"><p>When debugging with us in IRC, be prepared to use a so called nopaste service\r
+<div class="paragraph"><p>When debugging with us in IRC, be prepared to use a so-called nopaste service\r
such as <a href="https://pastebin.com">https://pastebin.com</a> because pasting large amounts of text in IRC\r
sometimes leads to incomplete lines (servers have line length limitations) or\r
flood kicks.</p></div>\r
<p>\r
A string that indicates how the text of the block should be parsed. Set to\r
<tt>"pango"</tt> to use <a href="https://developer.gnome.org/pango/stable/PangoMarkupFormat.html">Pango markup</a>.\r
- Set to <tt>"none"</tt> to not use any markup (default).\r
+ Set to <tt>"none"</tt> to not use any markup (default). Pango markup only works\r
+ if you use a pango font.\r
</p>\r
</dd>\r
</dl></div>\r
X11 button ID (for example 1 to 3 for left/middle/right mouse button)\r
</p>\r
</dd>\r
+<dt class="hdlist1">\r
+relative_x, relative_y\r
+</dt>\r
+<dd>\r
+<p>\r
+ Coordinates where the click occurred, with respect to the top left corner\r
+ of the block\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+width, height\r
+</dt>\r
+<dd>\r
+<p>\r
+ Width and height (in px) of the block\r
+</p>\r
+</dd>\r
</dl></div>\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
<div class="listingblock">\r
"instance": "eth0",\r
"button": 1,\r
"x": 1320,\r
- "y": 1400\r
+ "y": 1400,\r
+ "relative_x": 12,\r
+ "relative_y": 8,\r
+ "width": 50,\r
+ "height": 22\r
}</tt></pre>\r
</div></div>\r
</div>\r
<div class="sect1">\r
<h2 id="_description">4. DESCRIPTION</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>i3status is a small program (about 1500 SLOC) for generating a status bar for\r
+<div class="paragraph"><p>i3status is a small program for generating a status bar for\r
i3bar, dzen2, xmobar or similar programs. It is designed to be very\r
efficient by issuing a very small number of system calls, as one generally\r
wants to update such a status line every second. This ensures that even under\r
group: Docs
---
<div id="content">
-<h2>Documentation for i3 v4.14.1</h2>
+<h2>Documentation for i3 v4.15</h2>
<p>
One of i3’s goals is good documentation. The documents which you will find
<td align="center" valign="top"><p class="table"><a href="#_config_reply">CONFIG</a></p></td>\r
<td align="center" valign="top"><p class="table">Returns the last loaded i3 config.</p></td>\r
</tr>\r
+<tr>\r
+<td align="center" valign="top"><p class="table">10</p></td>\r
+<td align="center" valign="top"><p class="table"><tt>SEND_TICK</tt></p></td>\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
</tbody>\r
</table>\r
</div>\r
Reply to the GET_CONFIG message.\r
</p>\r
</dd>\r
+<dt class="hdlist1">\r
+TICK (10)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Reply to the SEND_TICK message.\r
+</p>\r
+</dd>\r
</dl></div>\r
</div>\r
<div class="sect2">\r
<pre><tt>{ "config": "font pango:monospace 8\nbindsym Mod4+q exit\n" }</tt></pre>\r
</div></div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_tick_reply">3.12. TICK reply</h3>\r
+<div class="paragraph"><p>The reply is a map containing the "success" member. After the reply was\r
+received, the tick event has been written to all IPC connections which subscribe\r
+to tick events. UNIX sockets are usually buffered, but you can be certain that\r
+once you receive the tick event you just triggered, you must have received all\r
+events generated prior to the <tt>SEND_TICK</tt> message (happened-before relation).</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
Sent when the ipc shuts down because of a restart or exit by user command\r
</p>\r
</dd>\r
+<dt class="hdlist1">\r
+tick (7)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Sent when the ipc client subscribes to the tick event (with <tt>"first":\r
+ true</tt>) or when any ipc client sends a SEND_TICK message (with <tt>"first":\r
+ false</tt>).\r
+</p>\r
+</dd>\r
</dl></div>\r
<div class="paragraph"><p><strong>Example:</strong></p></div>\r
<div class="listingblock">\r
}</tt></pre>\r
</div></div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_tick_event">4.10. tick event</h3>\r
+<div class="paragraph"><p>This event is triggered by a subscription to tick events or by a <tt>SEND_TICK</tt>\r
+message.</p></div>\r
+<div class="paragraph"><p><strong>Example (upon subscription):</strong></p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{\r
+ "first": true,\r
+ "payload": ""\r
+}</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p><strong>Example (upon <tt>SEND_TICK</tt> with a payload of <tt>arbitrary string</tt>):</strong></p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{\r
+ "first": false,\r
+ "payload": "arbitrary string"\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
<a href="https://github.com/mdirkse/i3ipc-go">https://github.com/mdirkse/i3ipc-go</a>\r
</p>\r
</li>\r
+<li>\r
+<p>\r
+<a href="https://github.com/i3/go-i3">https://github.com/i3/go-i3</a>\r
+</p>\r
+</li>\r
</ul></div>\r
</dd>\r
<dt class="hdlist1">\r
</li>\r
<li>\r
<p>\r
-<a href="https://github.com/Ceryn/i3msg-python">https://github.com/Ceryn/i3msg-python</a>\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
<a href="https://github.com/whitelynx/i3ipc">https://github.com/whitelynx/i3ipc</a> (not maintained)\r
</p>\r
</li>\r
</p>\r
</li>\r
</ol></div>\r
+<div class="paragraph"><p>Find an example implementation of this technique in\r
+<a href="https://github.com/i3/go-i3/blob/master/byteorder.go">https://github.com/i3/go-i3/blob/master/byteorder.go</a></p></div>\r
</div>\r
</div>\r
</div>\r
release of i3. To use it, run the following commands:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ /usr/lib/apt/apt-helper download-file http://debian.sur5r.net/i3/pool/main/s/sur5r-keyring/sur5r-keyring_2017.01.02_all.deb keyring.deb SHA256:4c3c6685b1181d83efe3a479c5ae38a2a44e23add55e16a328b8c8560bf05e5f\r
+<pre><tt>$ /usr/lib/apt/apt-helper download-file http://debian.sur5r.net/i3/pool/main/s/sur5r-keyring/sur5r-keyring_2018.01.30_all.deb keyring.deb SHA256:baa43dbbd7232ea2b5444cae238d53bebb9d34601cc000e82f11111b1889078a\r
# dpkg -i ./keyring.deb\r
# echo "deb http://debian.sur5r.net/i3/ $(grep '^DISTRIB_CODENAME=' /etc/lsb-release | cut -f2 -d=) universe" >> /etc/apt/sources.list.d/sur5r-i3.list\r
# apt update\r
containing the appropriate i3 logfile for each testcase. The latest folder can\r
always be found under the symlink <tt>latest/</tt>. Unless told differently, it will\r
run the tests on a separate X server instance (using Xephyr).</p></div>\r
-<div class="paragraph"><p>Xephyr will open a window where you can inspect the running test. You can run\r
-the tests without an X session with Xvfb, such as with <tt>xvfb-run\r
-./complete-run</tt>. This will also speed up the tests significantly especially on\r
-machines without a powerful video card.</p></div>\r
+<div class="paragraph"><p>Xephyr will open a window where you can inspect the running test. By default,\r
+tests are run under Xvfb.</p></div>\r
<div class="listingblock">\r
<div class="title">Example invocation of <tt>complete-run.pl</tt></div>\r
<div class="content">\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>
<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
vertically split terminals on the right, focus is on the bottom right one. When\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> (<tt>$mod+a</tt> by default), which will focus the <tt>Parent Container</tt> of\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
<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="_default_border_style_for_new_windows">4.10. 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
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
+<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 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>Note that the arrow is not required, it just looks good :-). If you decide to\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>\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
+<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
<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
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
# 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> [px | ppt] <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
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
+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
<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></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
--- /dev/null
+
+ ┌────────────────────────────┐
+ │ Release notes for i3 v4.15 │
+ └────────────────────────────┘
+
+This is i3 v4.15. This version is considered stable. All users of i3 are
+strongly encouraged to upgrade.
+
+Aside from a number of fixes and documentation improvements, a number of
+commands have been extended to be more complete (e.g. “assign”, “resize”).
+
+ ┌────────────────────────────┐
+ │ Changes in i3 v4.15 │
+ └────────────────────────────┘
+
+ • build: AnyEvent::I3 moved to the i3 repository, so that its main consumer,
+ the i3 testsuite, can use new features immediately (such as the tick event,
+ in this case).
+ • docs/hacking-howto: promote “using git / sending patches” and “how to
+ build?” sections
+ • docs/i3bar-protocol: document that pango markup only works with pango fonts
+ • docs/ipc: document focus, nodes, floating_nodes
+ • docs/ipc: urgent: complete the list of container types
+ • docs/ipc: document how to detect i3’s byte order in memory-safe languages
+ • docs/ipc: document the GET_CONFIG request
+ • docs/userguide: fix formatting issue
+ • docs/userguide: explain why Mod4 is usually preferred as a modifier
+ • docs/userguide: use more idiomatic english (full-size, so-called)
+ • docs/userguide: switch from removed goto command to focus
+ • docs/userguide: mention <criteria> in focus
+ • docs/userguide: remove outdated 2013 last-modified date
+ • dump-asy: add prerequisite checks
+ • dump-asy: fix warnings about empty container names
+ • i3-dump-log: enable shmlog on demand
+ • i3-sensible-terminal: add “kitty”, “guake”, “tilda”
+ • i3-sensible-editor: add “gvim”
+ • i3bar: add --release flag for bindsym in bar blocks
+ • i3bar: add relative coordinates in JSON for click events
+ • ipc: rename COMMAND to RUN_COMMAND for consistency
+ • ipc: implement tick event for less flaky tests
+ • ipc: add error reply to “focus <window_mode>”
+ • ipc: send success response for nop
+ • default config: add $mod+r to toggle resize mode
+ • default config: use variables for workspace names to avoid repetition
+ • introduce “assign <criteria> [→] [workspace] [number] <workspace>”
+ • introduce “assign <criteria> [→] output left|right|up|down|primary|<output>”
+ • introduce a “focus_wrapping” option (subsumes “force_focus_wrapping”)
+ • introduce percentage point resizing for floating containers:
+ “resize set <width> [px | ppt] <height> [px | ppt]”
+ • introduce “resize set <width> ppt <height> ppt” for tiling windows
+ • rename “new_window” and “new_float” to “default_border” and
+ “default_floating_border” (the old names keep working)
+ • output names (e.g. “DP2”) can now be used as synonyms for monitor names
+ (e.g. “Dell UP2414Q”).
+ • the “swap” command now works with fullscreen windows
+ • raise floating windows to top when they are focused programmatically
+ • _NET_ACTIVE_WINDOW: invalidate focus to force SetInputFocus call
+ • make focus handling consistent when changing focus between outputs
+ • round non-integer Xft.dpi values
+ • tiling resize: remove minimum size
+
+ ┌────────────────────────────┐
+ │ Bugfixes │
+ └────────────────────────────┘
+
+ • i3bar: fix various memory leaks
+ • i3bar: fix crash when no status_command is provided
+ • fix uninitialized variables in init_dpi_end, tree_restore
+ • fix incorrectly set up signal handling
+ • fix “swap” debug log message
+ • fix crash when specifying invalid con_id for “swap”
+ • fix crash upon restart with window marks
+ • fix crash when config file does not end in a newline
+ • fix crash in append_layout
+ • fix crash in layout toggle command
+ • fix crash when switching monitors
+ • fix use-after-free in randr_init error path
+ • fix move accidentally moving windows across outputs
+ • fix crash when floating window is tiled while being resized
+ • fix out-of-bounds memory read
+ • fix memory leak when config conversion fails
+ • fix layout toggle split, which didn’t work until enabling tabbed/stack mode
+ once
+ • move XCB event handling into xcb_prepare_cb
+ • avert endless loop on unexpected EOF in ipc messages
+ • perform proper cleanup for signals with Term action
+ • don’t match containers in the scratchpad with criteria
+ • fix “workspace show” related issues
+ • fix config file conversion with long variable names
+ • fix config file conversion memory initialization
+ • prevent access of freed workspace in _workspace_show
+ • disable fullscreen when required when programmatically focusing windows
+ • free last_motion_notify
+ • don’t raise floating windows when focused because of focus_follows_mouse
+ • correctly set EWMH atoms when closing a workspace
+ • don’t raise floating windows when workspace is shown
+ • keep focus order when encapsulating workspaces
+ • validate layout files before loading
+
+ ┌────────────────────────────┐
+ │ Thanks! │
+ └────────────────────────────┘
+
+Thanks for testing, bugfixes, discussions and everything I forgot go out to:
+
+ Alex Lu, Ben Creasy, Bennett Piater, Cast, chressie, clonejo, Dan Elkouby,
+ Daniel Mueller, DebianWall, Diki Ananta, Edward Betts, hwangcc23, Ingo Bürk,
+ Jan Alexander Steffens, Johannes Lange, Kent Fredric, livanh, Martin
+ T. H. Sandsmark, Michael Siegel, Orestis Floros, Pallav Agarwal, Pawel
+ S. Veselov, Pietro Cerutti, Theo Buehler, Thomas Praxl, Tyler Brazier,
+ Vladimir Panteleev, walker0643, Wes Roberts, xzfc
+
+-- Michael Stapelberg, 2018-03-10
--- /dev/null
+-----BEGIN PGP SIGNATURE-----
+
+iQIzBAABCgAdFiEEQk4U1wPnxtQ9nW82TnFg7UrI7h0FAlqkFfEACgkQTnFg7UrI
+7h3d5RAAjvcwo6bDl/Q7frYRp7ZTaacOlEjLNalNWYHnoFoH+E3r1xLjUUhagh4c
+oE0/tIRUjvAjhERv41bG3WpQLnOZojqv17EkDTuZo4CKxfBBZAH9ivDljDjE/TCT
+TS6B9ejdvsxF/VO7ELeYv6FdM13bfi/oVnIm+zAxZD83C/A3dhkMhGsZpTRk4LnW
+EiA4V2NjeLhUP4aybkzfWHR0Nh0XsX0MLMd7TqFzPvUYq47qgLlYcruVY8qYgUtH
+D8ywdnQZHJv33pvvOzkFbfqPJY/yzdgfPzmPZv1Or7i9Gtvq0wb+kHrrfStJBThb
+e26NX2QNn/A3iH87Vd8v6xmuxyDn0h1ZvBm0lVuOlRBPIZSs7Y4htRh9Vfihv0xo
+TZXaLi4c+yZzf1blM+9BQipkPjnW7cdI1e7b7GdADG41utMfhHWSbhDsIzOyZ/9d
+2H9PCfB0E586ntTqKjgyBzNrAB/X+0JhXIfq5CodgFGot2TOnfjGTJmNN15JZ19M
+/KPL/b9uc+DqoCx0tzYBPGAilbvXKw4PfTUyv2mRfmYyilysxhMgZHotSZ/3ogiM
+mi8PNDuzL/WUAW04HlLT1ckmShQPgQXyD0bwYT5BdYGMdVx0B2uwVe4XvfBson4W
+Y5UhXoWhNSoqTwx0MhS4PJ3kvbbaEzzvD+LDoBqAF12jCW6r6Gw=
+=HZK6
+-----END PGP SIGNATURE-----
<h2>Downloads</h2>
<p>
- The current stable version is 4.14.1.
+ The current stable version is 4.15.
</p>
<p>
</thead>
<tbody>
+ <tr>
+ <td>4.15</td>
+ <td><a href="/downloads/i3-4.15.tar.bz2">i3-4.15.tar.bz2</a></td>
+ <td>1.2 MiB</td>
+ <td><a href="/downloads/i3-4.15.tar.bz2.asc">signature</a></td>
+ <td>2018-03-10</td>
+ <td><a href="/downloads/RELEASE-NOTES-4.15.txt">release notes</a></td>
+ </tr>
+
<tr>
<td>4.14.1</td>
<td><a href="/downloads/i3-4.14.1.tar.bz2">i3-4.14.1.tar.bz2</a></td>
<h1>i3status</h1>
<p>
- i3status is a small program (about 3000 SLOC) for generating a status bar
- for i3bar, dzen2, xmobar or similar programs. It is designed to be very
- efficient by issuing a very small number of system calls, as one generally
- wants to update such a status line every second. This ensures that even under
- high load, your status bar is updated correctly. Also, it saves a bit of
- energy by not hogging your CPU as much as spawning the corresponding amount
- of shell commands would.
+ i3status is a small program for generating a status bar for i3bar, dzen2,
+ xmobar or similar programs. It is designed to be very efficient by issuing a
+ very small number of system calls, as one generally wants to update such a
+ status line every second. This ensures that even under high load, your status
+ bar is updated correctly. Also, it saves a bit of energy by not hogging your
+ CPU as much as spawning the corresponding amount of shell commands would.
</p>
<h2>Releases</h2>
<div class="sect1">\r
<h2 id="_description">4. DESCRIPTION</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>i3status is a small program (about 1500 SLOC) for generating a status bar for\r
+<div class="paragraph"><p>i3status is a small program for generating a status bar for\r
i3bar, dzen2, xmobar, lemonbar or similar programs. It is designed to be very\r
efficient by issuing a very small number of system calls, as one generally\r
wants to update such a status line every second. This ensures that even under\r
<a href="/downloads">
<span style="font-weight: bold; color: #3A8ECD; margin-right: .5em">➡</span>
Download the latest version
- <span style="margin-left: 2em; color: #c0c0c0">4.14.1</span>
+ <span style="margin-left: 2em; color: #c0c0c0">4.15</span>
</a>
</div>
</div>
projects / i3 / i3.github.io / commitdiff