To get an impression of how different layouts are represented, just play around
and look at the data structures -- they are exposed as a JSON hash. See
-http://i3wm.org/docs/ipc.html#_get_tree_reply for documentation on that and an
+http://i3wm.org/docs/ipc.html#_tree_reply for documentation on that and an
example.
== Files
Contains code for loading layouts from JSON files.
src/log.c::
-Handles the setting of loglevels, contains the logging functions.
+Contains the logging functions.
src/main.c::
Initializes the window manager.
IPC interface (interprocess communication)
==========================================
Michael Stapelberg <michael@i3wm.org>
-February 2012
+August 2012
This document describes how to interface with i3 from a separate process. This
is useful for example to remote-control i3 (to write test cases for example) or
Gets the configuration (as JSON map) of the workspace bar with the
given ID. If no ID is provided, an array with all configured bar IDs is
returned instead.
+GET_VERSION (7)::
+ Gets the version of i3. The reply will be a JSON-encoded dictionary
+ with the major, minor, patch and human-readable version.
So, a typical message could look like this:
--------------------------------------------------
Reply to the GET_MARKS message.
BAR_CONFIG (6)::
Reply to the GET_BAR_CONFIG message.
+VERSION (7)::
+ Reply to the GET_VERSION message.
=== COMMAND reply
{ "success": true }
-------------------
-=== GET_OUTPUTS reply
+=== OUTPUTS reply
The reply consists of a serialized list of outputs. Each output has the
following properties:
Can be either "normal", "none" or "1pixel", dependending on the
container’s border style.
layout (string)::
- Can be either "default", "stacked", "tabbed", "dockarea" or "output".
+ Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or
+ "output".
Other values might be possible in the future, should we add new
layouts.
orientation (string)::
Can be either "none" (for non-split containers), "horizontal" or
"vertical".
+ THIS FIELD IS OBSOLETE. It is still present, but your code should not
+ use it. Instead, rely on the layout field.
percent (float)::
The percentage which this container takes in its parent. A value of
+null+ means that the percent property does not make sense for this
geometry (map)::
The original geometry the window specified when i3 mapped it. Used when
switching a window to floating mode, for example.
+window (integer)::
+ The X11 window ID of the *actual client window* inside this container.
+ This field is set to null for split containers or otherwise empty
+ containers. This ID corresponds to what xwininfo(1) and other
+ X11-related tools display (usually in hex).
urgent (bool)::
Whether this container (window or workspace) has the urgency hint set.
focused (bool)::
}
--------------
+=== VERSION reply
+
+The reply consists of a single JSON dictionary with the following keys:
+
+major (integer)::
+ The major version of i3, such as +4+.
+minor (integer)::
+ The minor version of i3, such as +2+. Changes in the IPC interface (new
+ features) will only occur with new minor (or major) releases. However,
+ bugfixes might be introduced in patch releases, too.
+patch (integer)::
+ The patch version of i3, such as +1+ (when the complete version is
+ +4.2.1+). For versions such as +4.2+, patch will be set to +0+.
+human_readable (string)::
+ A human-readable version of i3 containing the precise git version,
+ build date and branch name. When you need to display the i3 version to
+ your users, use the human-readable version whenever possible (since
+ this is what +i3 --version+ displays, too).
+
+*Example:*
+-------------------
+{
+ "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")",
+ "minor" : 2,
+ "patch" : 0,
+ "major" : 4
+}
+-------------------
+
== Events
[[events]]
Ruby::
http://github.com/badboy/i3-ipc
Perl::
- http://search.cpan.org/search?query=AnyEvent::I3
+ https://metacpan.org/module/AnyEvent::I3
Python::
- https://github.com/whitelynx/i3ipc
- https://github.com/ziberna/i3-py (includes higher-level features)
+ * https://github.com/whitelynx/i3ipc
+ * https://github.com/ziberna/i3-py (includes higher-level features)
The multi-monitor situation
===========================
-Michael Stapelberg <michael@i3wm.org>
-July 2012
+Michael Stapelberg <michael+i3@stapelberg.de>
+September 2011
…or: oh no, I have an nVidia graphics card!
== The quick fix
If you are using the nVidia binary graphics driver (also known as 'blob')
-you need to upgrade to at least version 302.17 (released in June 2012).
-
-In case you cannot update the driver to 302.17 or newer on your machine for
-some reason, use the +--force-xinerama+ flag (in your .xsession) when starting
+you need to use the +--force-xinerama+ flag (in your .xsession) when starting
i3, like so:
.Example:
== The explanation
-Starting with version 3.ε (March 2010), i3 uses the RandR (Rotate and Resize)
-API instead of Xinerama. The reason for this, is that RandR provides more
-information about your outputs and connected screens than Xinerama does. To be
-specific, the code which handled on-the-fly screen reconfiguration (meaning
-without restarting the X server) was a very messy heuristic and most of the
-time did not work correctly -- that is just not possible with the little
-information Xinerama offers (just a list of screen resolutions, no identifiers
-for the screens or any additional information). Xinerama simply was not
-designed for dynamic configuration.
+Starting with version 3.ε, i3 uses the RandR (Rotate and Resize) API instead
+of Xinerama. The reason for this, is that RandR provides more information
+about your outputs and connected screens than Xinerama does. To be specific,
+the code which handled on-the-fly screen reconfiguration (meaning without
+restarting the X server) was a very messy heuristic and most of the time did
+not work correctly -- that is just not possible with the little information
+Xinerama offers (just a list of screen resolutions, no identifiers for the
+screens or any additional information). Xinerama simply was not designed
+for dynamic configuration.
So RandR came along, as a more powerful alternative (RandR 1.2 to be specific).
It offers all of Xinerama’s possibilities and lots more. Using the RandR API
As RandR has been around for about three years as of this writing, it seemed
like a very good idea to us, and it still is a very good one. What we did not
-expect, however, was the nVidia binary driver. It did not support RandR until
-mid 2012, even though nVidia had announced that it will support RandR
-previously. What does missing RandR support mean for you? First of all, you are
-stuck with TwinView and cannot use +xrandr+. While this ruins the user
-experience, the more grave problem is that the nVidia driver not only does not
-support dynamic configuration using RandR, it also does not expose correct
-multi-monitor information via the RandR API. So, in some setups, i3 will not
-find any screens; in others, it will find one large screen which actually
-contains both of your physical screens (but it will not know that these are two
-screens).
+expect, however, was the nVidia binary driver. It still does not support RandR
+(as of March 2010), even though nVidia has announced that it will support RandR
+eventually. What does this mean for you, if you are stuck with the binary
+driver for some reason (say the free drivers don’t work with your card)? First
+of all, you are stuck with TwinView and cannot use +xrandr+. While this ruins
+the user experience, the more grave problem is that the nVidia driver not only
+does not support dynamic configuration using RandR, it also does not expose
+correct multi-monitor information via the RandR API. So, in some setups, i3
+will not find any screens; in others, it will find one large screen which
+actually contains both of your physical screens (but it will not know that
+these are two screens).
For this very reason, we decided to implement the following workaround: As
long as the nVidia driver does not support RandR, an option called
i3 testsuite
============
-Michael Stapelberg <michael+i3@stapelberg.de>
-September 2011
+Michael Stapelberg <michael@i3wm.org>
+September 2012
This document explains how the i3 testsuite works, how to use it and extend it.
It is targeted at developers who not necessarily have been doing testing before
test manually if everything works. Having a testcase not only helps you with
that, but it will also be useful for every future change.
+== Relevant documentation
+
+Apart from this document, you should also have a look at:
+
+1. The "Modern Perl" book, which can be found at
+ http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf
+2. The latest Perl documentation of the "i3test" (general testcase setup) and
+ "i3test::Test" (additional test instructions) modules:
+ http://build.i3wm.org/docs/lib-i3test.html respectively
+ http://build.i3wm.org/docs/lib-i3test-test.html
+3. The latest documentation on i3’s IPC interface:
+ http://build.i3wm.org/docs/ipc.html
+
== Implementation
For several reasons, the i3 testsuite has been implemented in Perl:
2. Perl is widely available and has a well-working package infrastructure.
3. The author is familiar with Perl :).
+4. It is a good idea to use a different language for the tests than the
+ implementation itself.
Please do not start programming language flamewars at this point.
i3 User’s Guide
===============
-Michael Stapelberg <michael+i3@stapelberg.de>
-April 2012
+Michael Stapelberg <michael@i3wm.org>
+August 2012
This document contains all the information you need to configure and use the i3
-window manager. If it does not, please contact us on IRC (preferred) or post your
-question(s) on the mailing list.
+window manager. If it does not, please check http://faq.i3wm.org/ first, then
+contact us on IRC (preferred) or post your question(s) on the mailing list.
== Default keybindings
TODO: picture of the tree
-To split a window vertically, press +mod+v+. To split it horizontally, press
-+mod+h+.
+To split a window vertically, press +mod+v+ before you create the new window.
+To split it horizontally, press +mod+h+.
=== Changing the container layout
A split container can have one of the following layouts:
-default::
+splith/splitv::
Windows are sized so that every window gets an equal amount of space in the
-container.
+container. splith distributes the windows horizontally (windows are right next
+to each other), splitv distributes them vertically (windows are on top of each
+other).
stacking::
Only the focused window in the container is displayed. You get a list of
windows at the top of the container.
The same principle as +stacking+, but the list of windows at the top is only
a single line which is vertically split.
-To switch modes, press +mod+e+ for default, +mod+s+ for stacking and
-+mod+w+ for tabbed.
+To switch modes, press +mod+e+ for splith/splitv (it toggles), +mod+s+ for
+stacking and +mod+w+ for tabbed.
image:modes.png[Container modes]
It is only natural to use so-called +Split Containers+ in order to build a
layout when using a tree as data structure. In i3, every +Container+ has an
-orientation (horizontal, vertical or unspecified). So, in our example with the
-workspace, the default orientation of the workspace +Container+ is horizontal
-(most monitors are widescreen nowadays). If you change the orientation to
-vertical (+mod+v+ in the default config) and *then* open two terminals, i3 will
-configure your windows like this:
+orientation (horizontal, vertical or unspecified) and the orientation depends
+on the layout the container is in (vertical for splitv and stacking, horizontal
+for splith and tabbed). So, in our example with the workspace, the default
+layout of the workspace +Container+ is splith (most monitors are widescreen
+nowadays). If you change the layout to splitv (+mod+l+ in the default config)
+and *then* open two terminals, i3 will configure your windows like this:
image::tree-shot2.png["shot2",title="Vertical Workspace Orientation"]
-An interesting new feature of the tree branch is the ability to split anything:
-Let’s assume you have two terminals on a workspace (with horizontal
-orientation), focus is on the right terminal. Now you want to open another
-terminal window below the current one. If you would just open a new terminal
-window, it would show up to the right due to the horizontal workspace
-orientation. Instead, press +mod+v+ to create a +Vertical Split Container+ (to
+An interesting new feature of i3 since version 4 is the ability to split anything:
+Let’s assume you have two terminals on a workspace (with splith layout, that is
+horizontal orientation), focus is on the right terminal. Now you want to open
+another terminal window below the current one. If you would just open a new
+terminal window, it would show up to the right due to the splith layout.
+Instead, press +mod+v+ to split the container with the splitv layout (to
open a +Horizontal Split Container+, use +mod+h+). Now you can open a new
terminal and it will open below the current one:
image::tree-shot3.png["shot3",title="Focus parent, then open new terminal"]
+=== Implicit containers
+
+In some cases, i3 needs to implicitly create a container to fulfill your
+command.
+
+One example is the following scenario: You start i3 with a single monitor and a
+single workspace on which you open three terminal windows. All these terminal
+windows are directly attached to one node inside i3’s layout tree, the
+workspace node. By default, the workspace node’s orientation is +horizontal+.
+
+Now you move one of these terminals down (+mod+k+ by default). The workspace
+node’s orientation will be changed to +vertical+. The terminal window you moved
+down is directly attached to the workspace and appears on the bottom of the
+screen. A new (horizontal) container was created to accomodate the other two
+terminal windows. You will notice this when switching to tabbed mode (for
+example). You would end up having one tab called "another container" and the
+other one being the terminal window you moved down.
+
[[configuring]]
== Configuring i3
# This is a comment
-------------------
+[[fonts]]
+
=== Fonts
-i3 uses X core fonts (not Xft) for rendering window titles. You can use
-+xfontsel(1)+ to generate such a font description. To see special characters
-(Unicode), you need to use a font which supports the ISO-10646 encoding.
+i3 has support for both X core fonts and FreeType fonts (through Pango) to
+render window titles.
+
+To generate an X core font description, you can use +xfontsel(1)+. To see
+special characters (Unicode), you need to use a font which supports the
+ISO-10646 encoding.
+
+A FreeType font description is composed by a font family, a style, a weight,
+a variant, a stretch and a size.
+FreeType fonts support right-to-left rendering and contain often more
+Unicode glyphs than X core fonts.
If i3 cannot open the configured font, it will output an error in the logfile
and fall back to a working font.
*Syntax*:
------------------------------
font <X core font description>
+font xft:<a FreeType font description>
------------------------------
*Examples*:
--------------------------------------------------------------
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+font xft:DejaVu Sans Mono 10
--------------------------------------------------------------
[[keybindings]]
If you don’t switch layouts, and want a clean and simple config file, use
keysyms.
+Some tools (such as +import+ or +xdotool+) might be unable to run upon a
+KeyPress event, because the keyboard/pointer is still grabbed. For these
+situations, the +--release+ flag can be used, which will execute the command
+after the keys have been released.
+
*Syntax*:
----------------------------------
-bindsym [Modifiers+]keysym command
-bindcode [Modifiers+]keycode command
+bindsym [--release] [Modifiers+]keysym command
+bindcode [--release] [Modifiers+]keycode command
----------------------------------
*Examples*:
bindsym mod+Shift+r restart
# Notebook-specific hotkeys
-bindcode 214 exec /home/michael/toggle_beamer.sh
+bindcode 214 exec --no-startup-id /home/michael/toggle_beamer.sh
+
+# Simulate ctrl+v upon pressing $mod+x
+bindsym --release $mod+x exec --no-startup-id xdotool key --clearmodifiers ctrl+v
+
+# Take a screenshot upon pressing $mod+x (select an area)
+bindsym --release $mod+x exec --no-startup-id import /tmp/latest-screenshot.png
--------------------------------
Available Modifiers:
=== Border style for new windows
-This option determines which border style new windows will have.
+This option determines which border style new windows will have. The default is
+"normal".
*Syntax*:
---------------------------------------------
new_window 1pixel
---------------------
+=== Hiding vertical borders
+
+You can hide vertical borders adjacent to the screen edges using
++hide_edge_borders+. This is useful if you are using scrollbars, or do not want
+to waste even two pixels in displayspace. Default is none.
+
+*Syntax*:
+----------------------------
+hide_edge_borders <none|vertical|horizontal|both>
+----------------------------
+
+*Example*:
+----------------------
+hide_edge_borders vertical
+----------------------
+
=== Arbitrary commands for specific windows (for_window)
With the +for_window+ command, you can let i3 execute any command when it
details about the matching process and the window’s actual class, instance and
title when starting up.
+Note that if you want to start an application just once on a specific
+workspace, but you don’t want to assign all instances of it permanently, you
+can make use of i3’s startup-notification support (see <<exec>>) in your config
+file in the following way:
+
+*Start iceweasel on workspace 3 (once)*:
+-------------------------------------------------------------------------------
+# Start iceweasel on workspace 3, then switch back to workspace 1
+# (Being a command-line utility, i3-msg does not support startup notifications,
+# hence the exec --no-startup-id.)
+# (Starting iceweasel with i3’s exec command is important in order to make i3
+# create a startup notification context, without which the iceweasel window(s)
+# cannot be matched onto the workspace on which the command was started.)
+exec --no-startup-id i3-msg 'workspace 3; exec iceweasel; workspace 1'
+-------------------------------------------------------------------------------
+
=== Automatically starting applications on i3 startup
By using the +exec+ keyword outside a keybinding, you can configure
=== Focus follows mouse
-If you have a setup where your mouse usually is in your way (like a touchpad
-on your laptop which you do not want to disable completely), you might want
-to disable 'focus follows mouse' and control focus only by using your keyboard.
-The mouse will still be useful inside the currently active window (for example
-to click on links in your browser window).
+By default, window focus follows your mouse movements. However, if you have a
+setup where your mouse usually is in your way (like a touchpad on your laptop
+which you do not want to disable completely), you might want to disable 'focus
+follows mouse' and control focus only by using your keyboard. The mouse will
+still be useful inside the currently active window (for example to click on
+links in your browser window).
*Syntax*:
----------------------------
=== Font
-Specifies the font (again, X core font, not Xft, just like in i3) to be used in
-the bar.
+Specifies the font to be used in the bar. See <<fonts>>.
*Syntax*:
---------------------
--------------------------------------------------------------
bar {
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+ font xft:DejaVu Sans Mono 10
}
--------------------------------------------------------------
=== Splitting containers
The split command makes the current window a split container. Split containers
-can contain multiple windows. Every split container has an orientation, it is
-either split horizontally (a new window gets placed to the right of the current
-one) or vertically (a new window gets placed below the current one).
+can contain multiple windows. Depending on the layout of the split container,
+new windows get placed to the right of the current one (splith) or new windows
+get placed below the current one (splitv).
If you apply this command to a split container with the same orientation,
nothing will happen. If you use a different orientation, the split container’s
-orientation will be changed (if it does not have more than one window).
+orientation will be changed (if it does not have more than one window). Use
++layout toggle split+ to change the layout of any split container from splitv
+to splith or vice-versa.
*Syntax*:
---------------------------
=== Manipulating layout
-Use +layout default+, +layout stacking+ or +layout tabbed+ to change the
-current container layout to default, stacking or tabbed layout, respectively.
+Use +layout toggle split+, +layout stacking+ or +layout tabbed+ to change the
+current container layout to splith/splitv, stacking or tabbed layout,
+respectively.
To make the current window (!) fullscreen, use +fullscreen+, to make
it floating (or tiling again) use +floating enable+ respectively +floating disable+
(or +floating toggle+):
+*Syntax*:
+--------------
+layout <tabbed|stacking>
+layout toggle [split|all]
+--------------
+
*Examples*:
--------------
bindsym mod+s layout stacking
-bindsym mod+l layout default
+bindsym mod+l layout toggle split
bindsym mod+w layout tabbed
+# Toggle between stacking/tabbed/split:
+bindsym mod+x layout toggle
+
+# Toggle between stacking/tabbed/splith/splitv:
+bindsym mod+x layout toggle all
+
# Toggle fullscreen
bindsym mod+f fullscreen
workspace 1, 3, 4 and 9 and you want to cycle through them with a single key
combination. To restrict those to the current output, use +workspace
next_on_output+ and +workspace prev_on_output+. Similarly, you can use +move
-container to workspace next+ and +move container to workspace prev+ to move a
-container to the next/previous workspace.
+container to workspace next+, +move container to workspace prev+ to move a
+container to the next/previous workspace and +move container to workspace current+
+(the last one makes sense only when used with criteria).
+
+See <<move_to_outputs>> for how to move a container/workspace to a different
+RandR output.
[[back_and_forth]]
To switch back to the previously focused workspace, use +workspace
back_and_forth+.
-To move a container to another xrandr output such as +LVDS1+ or +VGA1+, you can
-use the +move container to output+ command followed by the name of the target
-output. You may also use +left+, +right+, +up+, +down+ instead of the xrandr
-output name to move to the next output in the specified direction.
-
-To move a whole workspace to another xrandr output such as +LVDS1+ or +VGA1+,
-you can use the +move workspace to output+ command followed by the name of the
-target output. You may also use +left+, +right+, +up+, +down+ instead of the
-xrandr output name to move to the next output in the specified direction.
+*Syntax*:
+-----------------------------------
+workspace <next|prev|next_on_output|prev_on_output>
+workspace back_and_forth
+workspace <name>
+workspace number <number>
+
+move [window|container] [to] workspace <name>
+move [window|container] [to] workspace number <number>
+move [window|container] [to] workspace <prev|next|current>
+-----------------------------------
*Examples*:
-------------------------
# move the whole workspace to the next output
bindsym mod+x move workspace to output right
+
+# move firefox to current workspace
+bindsym mod+F1 [class="Firefox"] move workspace current
-------------------------
==== Named workspaces
it has. This is useful in case you are changing the workspace’s name
dynamically.
-=== Renaming workspaces
+==== Renaming workspaces
You can rename workspaces. This might be useful to start with the default
numbered workspaces, do your work, and rename the workspaces afterwards to
i3-msg 'rename workspace "1: www" to "10: www"'
------------------------------------------------
+=== Moving containers/workspaces to RandR outputs
+
+[[move_to_outputs]]
+
+To move a container to another RandR output (addressed by names like +LVDS1+ or
++VGA1+) or to a RandR output identified by a specific direction (like +left+,
++right+, +up+ or +down+), there are two commands:
+
+*Syntax*:
+--------------------------------------------------------
+move container to output <<left|right|down|up>|<output>>
+move workspace to output <<left|right|down|up>|<output>>
+--------------------------------------------------------
+
+*Examples*:
+--------------------------------------------------------
+# Move the current workspace to the next output
+# (effectively toggles when you only have two outputs)
+bindsym mod+x move workspace to output right
+
+# Put this window on the presentation output.
+bindsym mod+x move container to output VGA1
+--------------------------------------------------------
+
[[resizingconfig]]
=== Resizing containers/windows
<head>\r
<link rel="icon" type="image/png" href="/favicon.png">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.4" />\r
+<meta name="generator" content="AsciiDoc 8.6.7" />\r
<title>i3: Debugging i3: How To (release version)</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<head>\r
<link rel="icon" type="image/png" href="/favicon.png">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.4" />\r
+<meta name="generator" content="AsciiDoc 8.6.7" />\r
<title>i3: Debugging i3: How To</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<head>\r
<link rel="icon" type="image/png" href="/favicon.png">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.4" />\r
+<meta name="generator" content="AsciiDoc 8.6.7" />\r
<title>i3: Hacking i3: How To</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
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#_get_tree_reply">http://i3wm.org/docs/ipc.html#_get_tree_reply</a> for documentation on that and an\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
example.</p></div>\r
</div>\r
</div>\r
</dt>\r
<dd>\r
<p>\r
-Handles the setting of loglevels, contains the logging functions.\r
+Contains the logging functions.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
%>
<%inherit file="_templates/i3.mako" />
<div id="content">
-<h2>Documentation for i3 v4.2</h2>
+<h2>Documentation for i3 v4.3</h2>
<p>
One of i3’s goals is good documentation. The documents which you will find
<head>\r
<link rel="icon" type="image/png" href="/favicon.png">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.4" />\r
+<meta name="generator" content="AsciiDoc 8.6.7" />\r
<title>i3: IPC interface (interprocess communication)</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<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">February 2012</span>\r
+<span id="revdate">August 2012</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>
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
</dl></div>\r
<div class="paragraph"><p>So, a typical message could look like this:</p></div>\r
<div class="listingblock">\r
Reply to the GET_BAR_CONFIG message.\r
</p>\r
</dd>\r
+<dt class="hdlist1">\r
+VERSION (7)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Reply to the GET_VERSION message.\r
+</p>\r
+</dd>\r
</dl></div>\r
</div>\r
<div class="sect2">\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_get_outputs_reply">3.5. GET_OUTPUTS reply</h3>\r
+<h3 id="_outputs_reply">3.5. OUTPUTS reply</h3>\r
<div class="paragraph"><p>The reply consists of a serialized list of outputs. Each output has the\r
following properties:</p></div>\r
<div class="dlist"><dl>\r
</dt>\r
<dd>\r
<p>\r
- Can be either "default", "stacked", "tabbed", "dockarea" or "output".\r
+ Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or\r
+ "output".\r
Other values might be possible in the future, should we add new\r
layouts.\r
</p>\r
<p>\r
Can be either "none" (for non-split containers), "horizontal" or\r
"vertical".\r
+ THIS FIELD IS OBSOLETE. It is still present, but your code should not\r
+ use it. Instead, rely on the layout field.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+window (integer)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The X11 window ID of the <strong>actual client window</strong> inside this container.\r
+ This field is set to null for split containers or otherwise empty\r
+ containers. This ID corresponds to what xwininfo(1) and other\r
+ X11-related tools display (usually in hex).\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
urgent (bool)\r
</dt>\r
<dd>\r
}</tt></pre>\r
</div></div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_version_reply">3.9. VERSION reply</h3>\r
+<div class="paragraph"><p>The reply consists of a single JSON dictionary with the following keys:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+major (integer)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The major version of i3, such as <tt>4</tt>.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+minor (integer)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The minor version of i3, such as <tt>2</tt>. Changes in the IPC interface (new\r
+ features) will only occur with new minor (or major) releases. However,\r
+ bugfixes might be introduced in patch releases, too.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+patch (integer)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The patch version of i3, such as <tt>1</tt> (when the complete version is\r
+ <tt>4.2.1</tt>). For versions such as <tt>4.2</tt>, patch will be set to <tt>0</tt>.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+human_readable (string)\r
+</dt>\r
+<dd>\r
+<p>\r
+ A human-readable version of i3 containing the precise git version,\r
+ build date and branch name. When you need to display the i3 version to\r
+ your users, use the human-readable version whenever possible (since\r
+ this is what <tt>i3 --version</tt> displays, too).\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p><strong>Example:</strong></p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{\r
+ "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")",\r
+ "minor" : 2,\r
+ "patch" : 0,\r
+ "major" : 4\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
</dt>\r
<dd>\r
<p>\r
- <a href="http://search.cpan.org/search?query=AnyEvent::I3">http://search.cpan.org/search?query=AnyEvent::I3</a>\r
+ <a href="https://metacpan.org/module/AnyEvent::I3">https://metacpan.org/module/AnyEvent::I3</a>\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
Python\r
</dt>\r
<dd>\r
+<div class="ulist"><ul>\r
+<li>\r
<p>\r
- <a href="https://github.com/whitelynx/i3ipc">https://github.com/whitelynx/i3ipc</a>\r
- <a href="https://github.com/ziberna/i3-py">https://github.com/ziberna/i3-py</a> (includes higher-level features)\r
+<a href="https://github.com/whitelynx/i3ipc">https://github.com/whitelynx/i3ipc</a>\r
</p>\r
+</li>\r
+<li>\r
+<p>\r
+<a href="https://github.com/ziberna/i3-py">https://github.com/ziberna/i3-py</a> (includes higher-level features)\r
+</p>\r
+</li>\r
+</ul></div>\r
</dd>\r
</dl></div>\r
</div>\r
<head>\r
<link rel="icon" type="image/png" href="/favicon.png">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.4" />\r
+<meta name="generator" content="AsciiDoc 8.6.7" />\r
<title>i3: i3 testsuite</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<div id="header">\r
<h1>i3 testsuite</h1>\r
<span id="author">Michael Stapelberg</span><br />\r
-<span id="email"><tt><<a href="mailto:michael+i3@stapelberg.de">michael+i3@stapelberg.de</a>></tt></span><br />\r
-<span id="revdate">September 2011</span>\r
+<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
+<span id="revdate">September 2012</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>\r
</div>\r
<div class="sect1">\r
-<h2 id="_implementation">2. Implementation</h2>\r
+<h2 id="_relevant_documentation">2. Relevant documentation</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>Apart from this document, you should also have a look at:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+The "Modern Perl" book, which can be found at\r
+ <a href="http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf">http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf</a>\r
+</p>\r
+</li>\r
+<li>\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
+</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
+</p>\r
+</li>\r
+</ol></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_implementation">3. Implementation</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>For several reasons, the i3 testsuite has been implemented in Perl:</p></div>\r
<div class="olist arabic"><ol class="arabic">\r
The author is familiar with Perl :).\r
</p>\r
</li>\r
+<li>\r
+<p>\r
+It is a good idea to use a different language for the tests than the\r
+ implementation itself.\r
+</p>\r
+</li>\r
</ol></div>\r
<div class="paragraph"><p>Please do not start programming language flamewars at this point.</p></div>\r
<div class="sect2">\r
-<h3 id="_mechanisms">2.1. Mechanisms</h3>\r
+<h3 id="_mechanisms">3.1. Mechanisms</h3>\r
<div class="sect3">\r
-<h4 id="_script_complete_run">2.1.1. Script: complete-run</h4>\r
+<h4 id="_script_complete_run">3.1.1. Script: complete-run</h4>\r
<div class="paragraph"><p>The testcases are run by a script called <tt>complete-run.pl</tt>. It runs all\r
testcases by default, but you can be more specific and let it only run one or\r
more testcases. Also, it takes care of starting up a separate instance of i3\r
</div></div>\r
</div>\r
<div class="sect3">\r
-<h4 id="_ipc_interface">2.1.2. IPC interface</h4>\r
+<h4 id="_ipc_interface">3.1.2. IPC interface</h4>\r
<div class="paragraph"><p>The testsuite makes extensive use of the IPC (Inter-Process Communication)\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
<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>\r
<div class="sect3">\r
-<h4 id="_x11_xcb">2.1.3. X11::XCB</h4>\r
+<h4 id="_x11_xcb">3.1.3. X11::XCB</h4>\r
<div class="paragraph"><p>In order to open new windows, change attributes, get events, etc., the\r
testsuite uses X11::XCB, a new (and quite specific to i3 at the moment) Perl\r
module which uses the XCB protocol description to generate Perl bindings to\r
</div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_filesystem_structure">2.2. Filesystem structure</h3>\r
+<h3 id="_filesystem_structure">3.2. Filesystem structure</h3>\r
<div class="paragraph"><p>In the git root of i3, the testcases live in the folder <tt>testcases</tt>. This\r
folder contains the <tt>complete-run.pl</tt> and <tt>Xdummy</tt> scripts and a base\r
configuration file which will be used for the tests. The different testcases\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_anatomy_of_a_testcase">3. Anatomy of a testcase</h2>\r
+<h2 id="_anatomy_of_a_testcase">4. Anatomy of a testcase</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Learning by example is definitely a good strategy when you are wondering how to\r
write a testcase. Let’s take <tt>t/11-goto.t</tt> as an easy example and go through it\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="i3_sync">4. Appendix A: The i3 sync protocol</h2>\r
+<h2 id="i3_sync">5. Appendix A: The i3 sync protocol</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Consider the following situation: You open two windows in your testcase, then\r
you use <tt>focus left</tt> and want to verify that the X11 focus has been updated\r
<div class="title">Figure 2. Diagram of the i3 sync solution</div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_implementation_details">4.1. Implementation details</h3>\r
+<h3 id="_implementation_details">5.1. Implementation details</h3>\r
<div class="paragraph"><p>The client which wants to sync with i3 initiates the protocol by sending a\r
ClientMessage to the X11 root window:</p></div>\r
<div class="listingblock">\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_appendix_b_socket_activation">5. Appendix B: Socket activation</h2>\r
+<h2 id="_appendix_b_socket_activation">6. Appendix B: Socket activation</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Socket activation is a mechanism which was made popular by systemd, an init\r
replacement. It basically describes creating a listening socket before starting\r
<div class="paragraph"><p>The interesting part of this (in the i3 context) is that you can very precisely\r
detect when the program is ready (finished its initialization).</p></div>\r
<div class="sect2">\r
-<h3 id="_preparing_the_listening_socket">5.1. Preparing the listening socket</h3>\r
+<h3 id="_preparing_the_listening_socket">6.1. Preparing the listening socket</h3>\r
<div class="paragraph"><p><tt>complete-run.pl</tt> will create a listening UNIX socket which it will then pass\r
to i3. This socket will be used by i3 as an additional IPC socket, just like\r
the one it will create on its own. Passing the socket happens implicitly\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_waiting_for_a_reply">5.2. Waiting for a reply</h3>\r
+<h3 id="_waiting_for_a_reply">6.2. Waiting for a reply</h3>\r
<div class="paragraph"><p>In the parent process, we want to know when i3 is ready to answer our IPC\r
requests and handle our windows. Therefore, after forking, we immediately close\r
the listening socket (i3 will handle this side of the socket) and connect to it\r
that i3 is ready.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_timing_and_conclusion">5.3. Timing and conclusion</h3>\r
+<h3 id="_timing_and_conclusion">6.3. Timing and conclusion</h3>\r
<div class="paragraph"><p>A beautiful feature of this mechanism is that it does not depend on timing. It\r
does not matter when the child process gets CPU time or when the parent process\r
gets CPU time. On heavily loaded machines (or machines with multiple CPUs,\r
<head>\r
<link rel="icon" type="image/png" href="/favicon.png">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.4" />\r
+<meta name="generator" content="AsciiDoc 8.6.7" />\r
<title>i3: i3 User’s Guide</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<div id="header">\r
<h1>i3 User’s Guide</h1>\r
<span id="author">Michael Stapelberg</span><br />\r
-<span id="email"><tt><<a href="mailto:michael+i3@stapelberg.de">michael+i3@stapelberg.de</a>></tt></span><br />\r
-<span id="revdate">April 2012</span>\r
+<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
+<span id="revdate">August 2012</span>\r
<div id="toc">
<div id="toctitle">Table of Contents</div>
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
<div id="preamble">\r
<div class="sectionbody">\r
<div class="paragraph"><p>This document contains all the information you need to configure and use the i3\r
-window manager. If it does not, please contact us on IRC (preferred) or post your\r
-question(s) on the mailing list.</p></div>\r
+window manager. If it does not, please check <a href="http://faq.i3wm.org/">http://faq.i3wm.org/</a> first, then\r
+contact us on IRC (preferred) or post your question(s) on the mailing list.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
or browser) and "split container" for containers that consist of one or more\r
windows.</p></div>\r
<div class="paragraph"><p>TODO: picture of the tree</p></div>\r
-<div class="paragraph"><p>To split a window vertically, press <tt>mod+v</tt>. To split it horizontally, press\r
-<tt>mod+h</tt>.</p></div>\r
+<div class="paragraph"><p>To split a window vertically, press <tt>mod+v</tt> before you create the new window.\r
+To split it horizontally, press <tt>mod+h</tt>.</p></div>\r
</div>\r
<div class="sect2">\r
<h3 id="_changing_the_container_layout">2.2. Changing the container layout</h3>\r
<div class="paragraph"><p>A split container can have one of the following layouts:</p></div>\r
<div class="dlist"><dl>\r
<dt class="hdlist1">\r
-default\r
+splith/splitv\r
</dt>\r
<dd>\r
<p>\r
Windows are sized so that every window gets an equal amount of space in the\r
-container.\r
+container. splith distributes the windows horizontally (windows are right next\r
+to each other), splitv distributes them vertically (windows are on top of each\r
+other).\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
</dl></div>\r
-<div class="paragraph"><p>To switch modes, press <tt>mod+e</tt> for default, <tt>mod+s</tt> for stacking and\r
-<tt>mod+w</tt> for tabbed.</p></div>\r
+<div class="paragraph"><p>To switch modes, press <tt>mod+e</tt> for splith/splitv (it toggles), <tt>mod+s</tt> for\r
+stacking and <tt>mod+w</tt> for tabbed.</p></div>\r
<div class="paragraph"><p><span class="image">\r
<img src="modes.png" alt="Container modes" />\r
</span></p></div>\r
<h3 id="_orientation_and_split_containers">3.2. Orientation and Split Containers</h3>\r
<div class="paragraph" id="OrientationSplit"><p>It is only natural to use so-called <tt>Split Containers</tt> in order to build a\r
layout when using a tree as data structure. In i3, every <tt>Container</tt> has an\r
-orientation (horizontal, vertical or unspecified). So, in our example with the\r
-workspace, the default orientation of the workspace <tt>Container</tt> is horizontal\r
-(most monitors are widescreen nowadays). If you change the orientation to\r
-vertical (<tt>mod+v</tt> in the default config) and <strong>then</strong> open two terminals, i3 will\r
-configure your windows like this:</p></div>\r
+orientation (horizontal, vertical or unspecified) and the orientation depends\r
+on the layout the container is in (vertical for splitv and stacking, horizontal\r
+for splith and tabbed). So, in our example with the workspace, the default\r
+layout of the workspace <tt>Container</tt> is splith (most monitors are widescreen\r
+nowadays). If you change the layout to splitv (<tt>mod+l</tt> in the default config)\r
+and <strong>then</strong> open two terminals, i3 will configure your windows like this:</p></div>\r
<div class="imageblock">\r
<div class="content">\r
<img src="tree-shot2.png" alt="shot2" />\r
</div>\r
<div class="title">Figure 2. Vertical Workspace Orientation</div>\r
</div>\r
-<div class="paragraph"><p>An interesting new feature of the tree branch is the ability to split anything:\r
-Let’s assume you have two terminals on a workspace (with horizontal\r
-orientation), focus is on the right terminal. Now you want to open another\r
-terminal window below the current one. If you would just open a new terminal\r
-window, it would show up to the right due to the horizontal workspace\r
-orientation. Instead, press <tt>mod+v</tt> to create a <tt>Vertical Split Container</tt> (to\r
+<div class="paragraph"><p>An interesting new feature of i3 since version 4 is the ability to split anything:\r
+Let’s assume you have two terminals on a workspace (with splith layout, that is\r
+horizontal orientation), focus is on the right terminal. Now you want to open\r
+another terminal window below the current one. If you would just open a new\r
+terminal window, it would show up to the right due to the splith layout.\r
+Instead, press <tt>mod+v</tt> to split the container with the splitv layout (to\r
open a <tt>Horizontal Split Container</tt>, use <tt>mod+h</tt>). Now you can open a new\r
terminal and it will open below the current one:</p></div>\r
<div class="imageblock" style="float:right;">\r
<div class="title">Figure 4. Focus parent, then open new terminal</div>\r
</div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_implicit_containers">3.4. Implicit containers</h3>\r
+<div class="paragraph"><p>In some cases, i3 needs to implicitly create a container to fulfill your\r
+command.</p></div>\r
+<div class="paragraph"><p>One example is the following scenario: You start i3 with a single monitor and a\r
+single workspace on which you open three terminal windows. All these terminal\r
+windows are directly attached to one node inside i3’s layout tree, the\r
+workspace node. By default, the workspace node’s orientation is <tt>horizontal</tt>.</p></div>\r
+<div class="paragraph"><p>Now you move one of these terminals down (<tt>mod+k</tt> by default). The workspace\r
+node’s orientation will be changed to <tt>vertical</tt>. The terminal window you moved\r
+down is directly attached to the workspace and appears on the bottom of the\r
+screen. A new (horizontal) container was created to accomodate the other two\r
+terminal windows. You will notice this when switching to tabbed mode (for\r
+example). You would end up having one tab called "another container" and the\r
+other one being the terminal window you moved down.</p></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_fonts">4.2. Fonts</h3>\r
-<div class="paragraph"><p>i3 uses X core fonts (not Xft) for rendering window titles. You can use\r
-<tt>xfontsel(1)</tt> to generate such a font description. To see special characters\r
-(Unicode), you need to use a font which supports the ISO-10646 encoding.</p></div>\r
+<h3 id="fonts">4.2. Fonts</h3>\r
+<div class="paragraph"><p>i3 has support for both X core fonts and FreeType fonts (through Pango) to\r
+render window titles.</p></div>\r
+<div class="paragraph"><p>To generate an X core font description, you can use <tt>xfontsel(1)</tt>. To see\r
+special characters (Unicode), you need to use a font which supports the\r
+ISO-10646 encoding.</p></div>\r
+<div class="paragraph"><p>A FreeType font description is composed by a font family, a style, a weight,\r
+a variant, a stretch and a size.\r
+FreeType fonts support right-to-left rendering and contain often more\r
+Unicode glyphs than X core fonts.</p></div>\r
<div class="paragraph"><p>If i3 cannot open the configured font, it will output an error in the logfile\r
and fall back to a working font.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>font <X core font description></tt></pre>\r
+<pre><tt>font <X core font description>\r
+font xft:<a FreeType font description></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>font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1</tt></pre>\r
+<pre><tt>font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1\r
+font xft:DejaVu Sans Mono 10</tt></pre>\r
</div></div>\r
</div>\r
<div class="sect2">\r
your bindings in the same physical location on the keyboard, use keycodes.\r
If you don’t switch layouts, and want a clean and simple config file, use\r
keysyms.</p></div>\r
+<div class="paragraph"><p>Some tools (such as <tt>import</tt> or <tt>xdotool</tt>) might be unable to run upon a\r
+KeyPress event, because the keyboard/pointer is still grabbed. For these\r
+situations, the <tt>--release</tt> flag can be used, which will execute the command\r
+after the keys have been released.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>bindsym [Modifiers+]keysym command\r
-bindcode [Modifiers+]keycode command</tt></pre>\r
+<pre><tt>bindsym [--release] [Modifiers+]keysym command\r
+bindcode [--release] [Modifiers+]keycode command</tt></pre>\r
</div></div>\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
bindsym mod+Shift+r restart\r
\r
# Notebook-specific hotkeys\r
-bindcode 214 exec /home/michael/toggle_beamer.sh</tt></pre>\r
+bindcode 214 exec --no-startup-id /home/michael/toggle_beamer.sh\r
+\r
+# Simulate ctrl+v upon pressing $mod+x\r
+bindsym --release $mod+x exec --no-startup-id xdotool key --clearmodifiers ctrl+v\r
+\r
+# Take a screenshot upon pressing $mod+x (select an area)\r
+bindsym --release $mod+x exec --no-startup-id import /tmp/latest-screenshot.png</tt></pre>\r
</div></div>\r
<div class="paragraph"><p>Available Modifiers:</p></div>\r
<div class="dlist"><dl>\r
</div>\r
<div class="sect2">\r
<h3 id="_border_style_for_new_windows">4.8. Border style for new windows</h3>\r
-<div class="paragraph"><p>This option determines which border style new windows will have.</p></div>\r
+<div class="paragraph"><p>This option determines which border style new windows will have. The default is\r
+"normal".</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_arbitrary_commands_for_specific_windows_for_window">4.9. Arbitrary commands for specific windows (for_window)</h3>\r
+<h3 id="_hiding_vertical_borders">4.9. Hiding vertical borders</h3>\r
+<div class="paragraph"><p>You can hide vertical borders adjacent to the screen edges using\r
+<tt>hide_edge_borders</tt>. This is useful if you are using scrollbars, or do not want\r
+to waste even two pixels in displayspace. Default is none.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>hide_edge_borders <none|vertical|horizontal|both></tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>hide_edge_borders vertical</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_arbitrary_commands_for_specific_windows_for_window">4.10. Arbitrary commands for specific windows (for_window)</h3>\r
<div class="paragraph"><p>With the <tt>for_window</tt> command, you can let i3 execute any command when it\r
encounters a specific window. This can be used to set windows to floating or to\r
change their border style, for example.</p></div>\r
<div class="paragraph"><p>The valid criteria are the same as those for commands, see <a href="#command_criteria">[command_criteria]</a>.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_variables">4.10. Variables</h3>\r
+<h3 id="_variables">4.11. Variables</h3>\r
<div class="paragraph"><p>As you learned in the section about keyboard bindings, you will have\r
to configure lots of bindings containing modifier keys. If you want to save\r
yourself some typing and be able to change the modifier you use later,\r
<tt>~/.xsession</tt> file).</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_automatically_putting_clients_on_specific_workspaces">4.11. Automatically putting clients on specific workspaces</h3>\r
+<h3 id="_automatically_putting_clients_on_specific_workspaces">4.12. Automatically putting clients on specific workspaces</h3>\r
<div class="paragraph" id="assign_workspace"><p>To automatically make a specific window show up on a specific workspace, you\r
can use an <strong>assignment</strong>. You can match windows by using any criteria,\r
see <a href="#command_criteria">[command_criteria]</a>. It is recommended that you match on window classes\r
logfile first (see <a href="http://i3wm.org/docs/debugging.html">http://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
+workspace, but you don’t want to assign all instances of it permanently, you\r
+can make use of i3’s startup-notification support (see <a href="#exec">[exec]</a>) in your config\r
+file in the following way:</p></div>\r
+<div class="paragraph"><p><strong>Start iceweasel on workspace 3 (once)</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt># Start iceweasel on workspace 3, then switch back to workspace 1\r
+# (Being a command-line utility, i3-msg does not support startup notifications,\r
+# hence the exec --no-startup-id.)\r
+# (Starting iceweasel with i3’s exec command is important in order to make i3\r
+# create a startup notification context, without which the iceweasel window(s)\r
+# cannot be matched onto the workspace on which the command was started.)\r
+exec --no-startup-id i3-msg 'workspace 3; exec iceweasel; workspace 1'</tt></pre>\r
+</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_automatically_starting_applications_on_i3_startup">4.12. Automatically starting applications on i3 startup</h3>\r
+<h3 id="_automatically_starting_applications_on_i3_startup">4.13. Automatically starting applications on i3 startup</h3>\r
<div class="paragraph"><p>By using the <tt>exec</tt> keyword outside a keybinding, you can configure\r
which commands will be performed by i3 on initial startup. <tt>exec</tt>\r
commands will not run when restarting i3, if you need a command to run\r
<div class="paragraph"><p>The flag --no-startup-id is explained in <a href="#exec">[exec]</a>.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="workspace_screen">4.13. Automatically putting workspaces on specific screens</h3>\r
+<h3 id="workspace_screen">4.14. Automatically putting workspaces on specific screens</h3>\r
<div class="paragraph"><p>If you assign clients to workspaces, it might be handy to put the\r
workspaces on specific screens. Also, the assignment of workspaces to screens\r
will determine which workspace i3 uses for a new screen when adding screens\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_changing_colors">4.14. Changing colors</h3>\r
+<h3 id="_changing_colors">4.15. Changing colors</h3>\r
<div class="paragraph"><p>You can change all colors which i3 uses to draw the window decorations.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
from single windows outside of a split container.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_interprocess_communication">4.15. Interprocess communication</h3>\r
+<h3 id="_interprocess_communication">4.16. Interprocess communication</h3>\r
<div class="paragraph"><p>i3 uses unix sockets to provide an IPC interface. This allows third-party\r
programs to get information from i3, such as the current workspaces\r
(to display a workspace bar), and to control i3.</p></div>\r
the next section.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_focus_follows_mouse">4.16. Focus follows mouse</h3>\r
-<div class="paragraph"><p>If you have a setup where your mouse usually is in your way (like a touchpad\r
-on your laptop which you do not want to disable completely), you might want\r
-to disable <em>focus follows mouse</em> and control focus only by using your keyboard.\r
-The mouse will still be useful inside the currently active window (for example\r
-to click on links in your browser window).</p></div>\r
+<h3 id="_focus_follows_mouse">4.17. Focus follows mouse</h3>\r
+<div class="paragraph"><p>By default, window focus follows your mouse movements. However, if you have a\r
+setup where your mouse usually is in your way (like a touchpad on your laptop\r
+which you do not want to disable completely), you might want to disable <em>focus\r
+follows mouse</em> and control focus only by using your keyboard. The mouse will\r
+still be useful inside the currently active window (for example to click on\r
+links in your browser window).</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_popups_during_fullscreen_mode">4.17. Popups during fullscreen mode</h3>\r
+<h3 id="_popups_during_fullscreen_mode">4.18. Popups during fullscreen mode</h3>\r
<div class="paragraph"><p>When you are in fullscreen mode, some applications still open popup windows\r
(take Xpdf for example). This is because these applications may not be aware\r
that they are in fullscreen mode (they do not check the corresponding hint).\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_focus_wrapping">4.18. Focus wrapping</h3>\r
+<h3 id="_focus_wrapping">4.19. 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
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_forcing_xinerama">4.19. Forcing Xinerama</h3>\r
+<h3 id="_forcing_xinerama">4.20. 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
video drivers (especially the nVidia binary driver) only provide support for\r
Xinerama instead of RandR. In such a situation, i3 must be told to use the\r
Xinerama, instead they are counted up, starting at 0: <tt>xinerama-0</tt>, <tt>xinerama-1</tt>, …</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_automatic_back_and_forth_when_switching_to_the_current_workspace">4.20. Automatic back-and-forth when switching to the current workspace</h3>\r
+<h3 id="_automatic_back_and_forth_when_switching_to_the_current_workspace">4.21. Automatic back-and-forth when switching to the current workspace</h3>\r
<div class="paragraph"><p>This configuration directive enables automatic <tt>workspace back_and_forth</tt> (see\r
<a href="#back_and_forth">[back_and_forth]</a>) when switching to the workspace that is currently focused.</p></div>\r
<div class="paragraph"><p>For instance: Assume you are on workspace "1: www" and switch to "2: IM" using\r
</div>\r
<div class="sect2">\r
<h3 id="_font">5.7. Font</h3>\r
-<div class="paragraph"><p>Specifies the font (again, X core font, not Xft, just like in i3) to be used in\r
-the bar.</p></div>\r
+<div class="paragraph"><p>Specifies the font to be used in the bar. See <a href="#fonts">[fonts]</a>.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
<div class="content">\r
<pre><tt>bar {\r
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1\r
+ font xft:DejaVu Sans Mono 10\r
}</tt></pre>\r
</div></div>\r
</div>\r
<div class="sect2">\r
<h3 id="_splitting_containers">6.2. Splitting containers</h3>\r
<div class="paragraph"><p>The split command makes the current window a split container. Split containers\r
-can contain multiple windows. Every split container has an orientation, it is\r
-either split horizontally (a new window gets placed to the right of the current\r
-one) or vertically (a new window gets placed below the current one).</p></div>\r
+can contain multiple windows. Depending on the layout of the split container,\r
+new windows get placed to the right of the current one (splith) or new windows\r
+get placed below the current one (splitv).</p></div>\r
<div class="paragraph"><p>If you apply this command to a split container with the same orientation,\r
nothing will happen. If you use a different orientation, the split container’s\r
-orientation will be changed (if it does not have more than one window).</p></div>\r
+orientation will be changed (if it does not have more than one window). Use\r
+<tt>layout toggle split</tt> to change the layout of any split container from splitv\r
+to splith or vice-versa.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
</div>\r
<div class="sect2">\r
<h3 id="_manipulating_layout">6.3. Manipulating layout</h3>\r
-<div class="paragraph"><p>Use <tt>layout default</tt>, <tt>layout stacking</tt> or <tt>layout tabbed</tt> to change the\r
-current container layout to default, stacking or tabbed layout, respectively.</p></div>\r
+<div class="paragraph"><p>Use <tt>layout toggle split</tt>, <tt>layout stacking</tt> or <tt>layout tabbed</tt> to change the\r
+current container layout to splith/splitv, stacking or tabbed layout,\r
+respectively.</p></div>\r
<div class="paragraph"><p>To make the current window (!) fullscreen, use <tt>fullscreen</tt>, to make\r
it floating (or tiling again) use <tt>floating enable</tt> respectively <tt>floating disable</tt>\r
(or <tt>floating toggle</tt>):</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>layout <tabbed|stacking>\r
+layout toggle [split|all]</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>bindsym mod+s layout stacking\r
-bindsym mod+l layout default\r
+bindsym mod+l layout toggle split\r
bindsym mod+w layout tabbed\r
\r
+# Toggle between stacking/tabbed/split:\r
+bindsym mod+x layout toggle\r
+\r
+# Toggle between stacking/tabbed/splith/splitv:\r
+bindsym mod+x layout toggle all\r
+\r
# Toggle fullscreen\r
bindsym mod+f fullscreen\r
\r
workspace 1, 3, 4 and 9 and you want to cycle through them with a single key\r
combination. To restrict those to the current output, use <tt>workspace\r
next_on_output</tt> and <tt>workspace prev_on_output</tt>. Similarly, you can use <tt>move\r
-container to workspace next</tt> and <tt>move container to workspace prev</tt> to move a\r
-container to the next/previous workspace.</p></div>\r
+container to workspace next</tt>, <tt>move container to workspace prev</tt> to move a\r
+container to the next/previous workspace and <tt>move container to workspace current</tt>\r
+(the last one makes sense only when used with criteria).</p></div>\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 class="paragraph" id="back_and_forth"><p>To switch back to the previously focused workspace, use <tt>workspace\r
back_and_forth</tt>.</p></div>\r
-<div class="paragraph"><p>To move a container to another xrandr output such as <tt>LVDS1</tt> or <tt>VGA1</tt>, you can\r
-use the <tt>move container to output</tt> command followed by the name of the target\r
-output. You may also use <tt>left</tt>, <tt>right</tt>, <tt>up</tt>, <tt>down</tt> instead of the xrandr\r
-output name to move to the next output in the specified direction.</p></div>\r
-<div class="paragraph"><p>To move a whole workspace to another xrandr output such as <tt>LVDS1</tt> or <tt>VGA1</tt>,\r
-you can use the <tt>move workspace to output</tt> command followed by the name of the\r
-target output. You may also use <tt>left</tt>, <tt>right</tt>, <tt>up</tt>, <tt>down</tt> instead of the\r
-xrandr output name to move to the next output in the specified direction.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>workspace <next|prev|next_on_output|prev_on_output>\r
+workspace back_and_forth\r
+workspace <name>\r
+workspace number <number>\r
+\r
+move [window|container] [to] workspace <name>\r
+move [window|container] [to] workspace number <number>\r
+move [window|container] [to] workspace <prev|next|current></tt></pre>\r
+</div></div>\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
bindsym mod+b workspace back_and_forth\r
\r
# move the whole workspace to the next output\r
-bindsym mod+x move workspace to output right</tt></pre>\r
+bindsym mod+x move workspace to output right\r
+\r
+# move firefox to current workspace\r
+bindsym mod+F1 [class="Firefox"] move workspace current</tt></pre>\r
</div></div>\r
<div class="sect3">\r
<h4 id="_named_workspaces">6.5.1. Named workspaces</h4>\r
it has. This is useful in case you are changing the workspace’s name\r
dynamically.</p></div>\r
</div>\r
-</div>\r
-<div class="sect2">\r
-<h3 id="_renaming_workspaces">6.6. Renaming workspaces</h3>\r
+<div class="sect3">\r
+<h4 id="_renaming_workspaces">6.5.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.</p></div>\r
i3-msg 'rename workspace "1: www" to "10: www"'</tt></pre>\r
</div></div>\r
</div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_moving_containers_workspaces_to_randr_outputs">6.6. Moving containers/workspaces to RandR outputs</h3>\r
+<div class="paragraph" id="move_to_outputs"><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 class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>move container to output <<left|right|down|up>|<output>>\r
+move workspace to output <<left|right|down|up>|<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># Move the current workspace to the next output\r
+# (effectively toggles when you only have two outputs)\r
+bindsym mod+x move workspace to output right\r
+\r
+# Put this window on the presentation output.\r
+bindsym mod+x move container to output VGA1</tt></pre>\r
+</div></div>\r
+</div>\r
<div class="sect2">\r
<h3 id="resizingconfig">6.7. Resizing containers/windows</h3>\r
<div class="paragraph"><p>If you want to resize containers/windows using your keyboard, you can use the\r
<head>\r
<link rel="icon" type="image/png" href="/favicon.png">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.4" />\r
+<meta name="generator" content="AsciiDoc 8.6.7" />\r
<title>i3: External workspace bars</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
projects / i3 / i3.github.io / commitdiff