-all: hacking-howto.html debugging.html repositories.html userguide.html ipc.html multi-monitor.html wsbar.html i3status.html i3.html i3-config-wizard.html i3-nagbar.html i3-migrate-config-to-v4.html i3-msg.html
+all: hacking-howto.html debugging.html repositories.html userguide.html ipc.html multi-monitor.html wsbar.html i3status.html i3.html i3-config-wizard.html i3-nagbar.html i3-migrate-config-to-v4.html i3-msg.html testsuite.html
hacking-howto.html: hacking-howto
asciidoc -a linkcss -a stylesdir=/css -a scriptsdir=/js --backend=xhtml11 -f conf/i3html.conf -a toc -n $<
+testsuite.html: testsuite
+ asciidoc -a linkcss -a stylesdir=/css -a scriptsdir=/js --backend=xhtml11 -f conf/i3html.conf -a toc -n $<
+
debugging.html: debugging
asciidoc -a linkcss -a stylesdir=/css -a scriptsdir=/js --backend=xhtml11 -f conf/i3html.conf -n $<
The multi-monitor situation
===========================
Michael Stapelberg <michael+i3@stapelberg.de>
-March 2010
+September 2011
…or: oh no, I have an nVidia graphics card!
exec i3 --force-xinerama -V >>~/.i3/i3log 2>&1
----------------------------------------------
+…or use +force_xinerama yes+ in your configuration file.
+
== The explanation
Starting with version 3.ε, i3 uses the RandR (Rotate and Resize) API instead
For this very reason, we decided to implement the following workaround: As
long as the nVidia driver does not support RandR, an option called
-+--force-xinerama+ is available in i3. This option gets the list of screens
-*once* when starting, and never updates it. As the nVidia driver cannot do
-dynamic configuration anyways, this is not a big deal.
++--force-xinerama+ is available in i3 (alternatively, you can use the
++force_xinerama+ configuration file directive). This option gets the list of
+screens *once* when starting, and never updates it. As the nVidia driver cannot
+do dynamic configuration anyways, this is not a big deal.
+
+Also note that your output names are not descriptive (like +HDMI1+) when using
+Xinerama, instead they are counted up, starting at 0: +xinerama-0+, +xinerama-1+, …
== See also
--- /dev/null
+i3 testsuite
+============
+Michael Stapelberg <michael+i3@stapelberg.de>
+September 2011
+
+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
+or have not been testing in Perl before. In general, the testsuite is not of
+interest for end users.
+
+
+== Introduction
+
+The i3 testsuite is a collection of files which contain testcases for various
+i3 features. Some of them test if a certain workflow works correctly (moving
+windows, focus behaviour, …). Others are regression tests and contain code
+which previously made i3 crash or lead to unexpected behaviour. They then check
+if i3 still runs (meaning it did not crash) and if it handled everything
+correctly.
+
+The goal of having these tests is to automatically find problems and to
+automatically get a feel for whether a change in the source code breaks any
+existing feature. After every modification of the i3 sourcecode, the developer
+should run the full testsuite. If one of the tests fails, the corresponding
+problem should be fixed (or, in some cases, the testcase has to be modified).
+For every bugreport, a testcase should be written to test the correct
+behaviour. Initially, it will fail, but after fixing the bug, it will pass.
+This ensures (or increases the chance) that bugs which have been fixed once
+will never be found again.
+
+Also, when implementing a new feature, a testcase might be a good way to be
+able to easily test if the feature is working correctly. Many developers will
+test manually if everything works. Having a testcase not only helps you with
+that, but it will also be useful for every future change.
+
+== Implementation
+
+For several reasons, the i3 testsuite has been implemented in Perl:
+
+1. Perl has a long tradition of testing. Every popular/bigger Perl module which
+ you can find on CPAN will not only come with documentation, but also with
+ tests. Therefore, the available infrastructure for tests is comprehensive.
+ See for example the excellent http://search.cpan.org/perldoc?Test::More
+ and the referenced http://search.cpan.org/perldoc?Test::Tutorial.
+
+2. Perl is widely available and has a well-working package infrastructure.
+3. The author is familiar with Perl :).
+
+Please do not start programming language flamewars at this point.
+
+=== Mechanisms
+
+==== Script: complete-run
+
+The testcases are run by a script called +complete-run.pl+. It runs all
+testcases by default, but you can be more specific and let it only run one or
+more testcases. Also, it takes care of starting up a separate instance of i3
+with an appropriate configuration file and creates a folder for each run
+containing the appropriate i3 logfile for each testcase. The latest folder can
+always be found under the symlink +latest/+. Unless told differently, it will
+run the tests on a separate X server instance (using the Xdummy script).
+
+.Example invocation of complete-run.pl+
+---------------------------------------
+$ cd ~/i3/testcases
+
+$ ./complete-run.pl
+# output omitted because it is very long
+All tests successful.
+Files=78, Tests=734, 27 wallclock secs ( 0.38 usr 0.48 sys + 17.65 cusr 3.21 csys = 21.72 CPU)
+Result: PASS
+
+$ ./complete-run.pl t/04-floating.t
+[:3] i3 startup: took 0.07s, status = 1
+[:3] Running t/04-floating.t with logfile testsuite-2011-09-24-16-06-04-4.0.2-226-g1eb011a/i3-log-for-04-floating.t
+[:3] t/04-floating.t finished
+[:3] killing i3
+output for t/04-floating.t:
+ok 1 - use X11::XCB::Window;
+ok 2 - The object isa X11::XCB::Window
+ok 3 - Window is mapped
+ok 4 - i3 raised the width to 75
+ok 5 - i3 raised the height to 50
+ok 6 - i3 did not map it to (0x0)
+ok 7 - The object isa X11::XCB::Window
+ok 8 - i3 let the width at 80
+ok 9 - i3 let the height at 90
+ok 10 - i3 mapped it to x=1
+ok 11 - i3 mapped it to y=18
+ok 12 - The object isa X11::XCB::Window
+ok 13 - i3 let the width at 80
+ok 14 - i3 let the height at 90
+1..14
+
+All tests successful.
+Files=1, Tests=14, 0 wallclock secs ( 0.01 usr 0.00 sys + 0.19 cusr 0.03 csys = 0.23 CPU)
+Result: PASS
+
+$ less latest/i3-log-for-04-floating.t
+----------------------------------------
+
+==== IPC interface
+
+The testsuite makes extensive use of the IPC (Inter-Process Communication)
+interface which i3 provides. It is used for the startup process of i3, for
+terminating it cleanly and (most importantly) for modifying and getting the
+current state (layout tree).
+
+See [http://i3wm.org/docs/ipc.html] for documentation on the IPC interface.
+
+==== X11::XCB
+
+In order to open new windows, change attributes, get events, etc., the
+testsuite uses X11::XCB, a new (and quite specific to i3 at the moment) Perl
+module which uses the XCB protocol description to generate Perl bindings to
+X11. They work in a very similar way to libxcb (which i3 uses) and provide
+relatively high-level interfaces (objects such as +X11::XCB::Window+) aswell as
+access to the low-level interface, which is very useful when testing a window
+manager.
+
+=== Filesystem structure
+
+In the git root of i3, the testcases live in the folder +testcases+. This
+folder contains the +complete-run.pl+ and +Xdummy+ scripts and a base
+configuration file which will be used for the tests. The different testcases
+(their file extension is .t, not .pl) themselves can be found in the
+conventionally named subfolder +t+:
+
+.Filesystem structure
+--------------------------------------------
+├── testcases
+│ ├── complete-run.pl
+│ ├── i3-test.config
+│ ├── lib
+│ │ ├── i3test.pm
+│ │ ├── SocketActivation.pm
+│ │ └── StartXDummy.pm
+│ ├── t
+│ │ ├── 00-load.t
+│ │ ├── 01-tile.t
+│ │ ├── 02-fullscreen.t
+│ │ ├── ...
+│ │ ├── omitted for brevity
+│ │ ├── ...
+│ │ └── 74-regress-focus-toggle.t
+│ └── Xdummy
+--------------------------------------------
+
+== Anatomy of a testcase
+
+Learning by example is definitely a good strategy when you are wondering how to
+write a testcase. Let's take +t/11-goto.t+ as an easy example and go through it
+step by step:
+
+.t/11-goto.t: Boilerplate
+----------------------
+#!perl
+# vim:ts=4:sw=4:expandtab
+
+use i3test;
+use File::Temp;
+
+my $x = X11::XCB::Connection->new;
+-----------------------
+
+This is what we call boilerplate. It exists at the top of every test file (to
+some extent). The first line is the shebang, which specifies that this file is
+a Perl script. The second line contains VIM specific settings on how to
+edit/format this file (use spaces instead of tabs, indent using 4 spaces).
+Afterwards, the +i3test+ module is used. This module contains i3 testsuite
+specific functions which you are strongly encouraged to use. They make writing
+testcases a lot easier and will make it easier for other people to read your
+tests.
+
+The next line uses the +File::Temp+ module. This is specific to this testcase,
+because it needs to generate a temporary name during the test. Many testcases
+use only the +i3test+ module.
+
+The last line opens a connection to X11. You might or might not need this in
+your testcase, depending on whether you are going to open windows (etc.) or
+only use i3 commands.
+
+.t/11-goto.t: Setup
+----------------------
+my $tmp = fresh_workspace;
+
+cmd 'split h';
+----------------------
+
+The first line calls i3test's +fresh_workspace+ function which looks for a
+currently unused workspace, switches to it, and returns its name. The variable
++$tmp+ will end up having a value such as +"/tmp/87kBVcHbA9"+. Note that this
+is not (necessarily) a valid path, it's just a random workspace name.
+
+So, now that we are on a new workspace, we ensure that the workspace uses
+horizontal orientation by issuing the +split h+ command (see the i3 User's
+Guide for a list of commands). This is not strictly necessary, but good style.
+In general, the +cmd+ function executes the specified i3 command by using the
+IPC interface and returns once i3 acknowledged the command.
+
+.t/11-goto.t: Setup
+----------------------
+#####################################################################
+# Create two windows and make sure focus switching works
+#####################################################################
+
+my $top = open_window($x);
+my $mid = open_window($x);
+my $bottom = open_window($x);
+----------------------
+
+In every major section of a testcase, you should put a comment like the one
+above. This makes it immediately clear how the file is structured.
+
+The +open_window+ function opens a standard window, which will then be put into
+tiling mode by i3. If you want a floating window, use the
++open_floating_window+ function. These functions accept the same parameters as
++X11::XCB::Window->new+, see the i3test documentation at TODO.
+
+.t/11-goto.t: Helper function
+----------------------
+#
+# Returns the input focus after sending the given command to i3 via IPC
+# and syncing with i3
+#
+sub focus_after {
+ my $msg = shift;
+
+ cmd $msg;
+ sync_with_i3 $x;
+ return $x->input_focus;
+}
+----------------------
+
+This section defines a helper function which will be used over and over in this
+testcase. If you have code which gets executed more than once or twice
+(depending on the length of your test, use your best judgement), please put it
+in a function. Tests should be short, concise and clear.
+
+The +focus_after+ function executes a command and returns the X11 focus after
+the command was executed. The +sync_with_i3+ command makes sure that i3 could
+push its state to X11. See <<i3_sync>> to learn how this works exactly.
+
+.t/11-goto.t: Test assumptions
+----------------------
+$focus = $x->input_focus;
+is($focus, $bottom->id, "Latest window focused");
+
+$focus = focus_after('focus left');
+is($focus, $mid->id, "Middle window focused");
+----------------------
+
+Now, we run the first two real tests. They use +Test::More+'s +is+ function,
+which compares two values and prints the differences if they are not the same.
+After the arguments, we supply a short comment to indicate what we are testing
+here. This makes it vastly more easy for the developer to spot which testcase
+is the problem in case one fails.
+
+The first test checks that the most recently opened window is focused.
+Afterwards, the command +focus left+ is issued and it is verified that the
+middle window now has focus.
+
+Note that this is not a comprehensive test of the +focus+ command -- we would
+have to test wrapping, focus when using a more complex layout, focusing the
+parent/child containers, etc. But that is not the point of this testcase.
+Instead, we just want to know if +$x->input_focus+ corresponds with what we are
+expecting. If not, something is completely wrong with the test environment and
+this trivial test will fail.
+
+.t/11-goto.t: Test that the feature does not work (yet)
+----------------------
+#####################################################################
+# Now goto a mark which does not exist
+#####################################################################
+
+my $random_mark = mktemp('mark.XXXXXX');
+
+$focus = focus_after(qq|[con_mark="$random_mark"] focus|);
+is($focus, $mid->id, "focus unchanged");
+----------------------
+
+Syntax hint: The qq keyword is the interpolating quote operator. It lets you
+chose a quote character (in this case the +|+ character, a pipe). This makes
+having double quotes in our string easy.
+
+In this new major section, a random mark (mark is an identifier for a window,
+see "VIM-like marks" in the i3 User’s Guide) will be generated. Afterwards, we
+test that trying to focus that mark will not do anything. This is important: Do
+not only test that using a feature has the expected outcome, but also test that
+using it without properly initializing it does no harm. This command could for
+example have changed focus anyways (a bug) or crash i3 (obviously a bug).
+
+.t/11-goto.t: Test that the feature does work
+----------------------
+cmd "mark $random_mark";
+
+$focus = focus_after('focus left');
+is($focus, $top->id, "Top window focused");
+
+$focus = focus_after(qq|[con_mark="$random_mark"] focus|);
+is($focus, $mid->id, "goto worked");
+----------------------
+
+Remember: Focus was on the middle window (we verified that earlier in "Test
+assumptions"). We now mark the middle window with our randomly generated mark.
+Afterwards, we switch focus away from the middle window to be able to tell if
+focusing it via its mark will work. If the test works, the goto command seems
+to be working.
+
+.t/11-goto.t: Test corner case
+----------------------
+# check that we can specify multiple criteria
+
+$focus = focus_after('focus left');
+is($focus, $top->id, "Top window focused");
+
+$focus = focus_after(qq|[con_mark="$random_mark" con_mark="$random_mark"] focus|);
+is($focus, $mid->id, "goto worked");
+----------------------
+
+Now we test the same feature, but specifying the mark twice in the command.
+This should have no effect, but let’s be sure: test it and see if things go
+wrong.
+
+.t/11-goto.t: Test second code path
+----------------------
+#####################################################################
+# Check whether the focus command will switch to a different
+# workspace if necessary
+#####################################################################
+
+my $tmp2 = fresh_workspace;
+
+is(focused_ws(), $tmp2, 'tmp2 now focused');
+
+cmd qq|[con_mark="$random_mark"] focus|;
+
+is(focused_ws(), $tmp, 'tmp now focused');
+----------------------
+
+This part of the test checks that focusing windows by mark works across
+workspaces. It uses i3test's +focused_ws+ function to get the current
+workspace.
+
+.t/11-goto.t: Test second code path
+----------------------
+done_testing;
+----------------------
+
+The end of every testcase has to contain the +done_testing+ line. This tells
++complete-run.pl+ that the test was finished successfully. If it does not
+occur, the test might have crashed during execution -- some of the reasons why
+that could happen are bugs in the used modules, bugs in the testcase itself or
+an i3 crash resulting in the testcase being unable to communicate with i3 via
+IPC anymore.
+
+[[i3_sync]]
+== Appendix A: The i3 sync protocol
+
+Consider the following situation: You open two windows in your testcase, then
+you use +focus left+ and want to verify that the X11 focus has been updated
+properly. Sounds simple, right? Let’s assume you use this straight-forward
+implementation:
+
+.Racey focus testcase
+-----------
+my $left = open_window($x);
+my $right = open_window($x);
+cmd 'focus left';
+is($x->input_focus, $left->id, 'left window focused');
+----------
+
+However, the test fails. Sometimes. Apparantly, there is a race condition in
+your test. If you think about it, this is because you are using two different
+pieces of software: You tell i3 to update focus, i3 confirms that, and then you
+ask X11 to give you the current focus. There is a certain time i3 needs to
+update the X11 state. If the testcase gets CPU time before X11 processed i3's
+requests, the test will fail.
+
+image::i3-sync.png["Diagram of the race condition", title="Diagram of the race condition"]
+
+One way to "solve" this would be to add +sleep 0.5;+ after the +cmd+ call.
+After 0.5 seconds it should be safe to assume that focus has been updated,
+right?
+
+In practice, this usually works. However, it has several problems:
+
+1. This is obviously not a clean solution, but a workaround. Ugly.
+2. On very slow machines, this might not work. Unlikely, but in different
+ situations (a delay to wait for i3 to startup) the necessary time is much
+ harder to guess, even for fast machines.
+3. This *wastes a lot of time*. Usually, your computer is much faster than 0.5s
+ to update the status. However, sometimes, it might take 0.4s, so we can’t
+ make it +sleep 0.1+.
+
+To illustrate how grave the problem with wasting time actually is: Before
+removing all sleeps from the testsuite, a typical run using 4 separate X
+servers took around 50 seconds on my machine. After removing all the sleeps,
+we achieved times of about 25 seconds. This is very significant and influences
+the way you think about tests -- the faster they are, the more likely you are
+to check whether everything still works quite often (which you should).
+
+What I am trying to say is: Delays adds up quickly and make the test suite
+less robust.
+
+The real solution for this problem is a mechanism which I call "the i3 sync
+protocol". The idea is to send a request (which does not modify state) via X11
+to i3 which will then be answered. Due to the request's position in the event
+queue (*after* all previous events), you can be sure that by the time you
+receive the reply, all other events have been dealt with by i3 (and, more
+importantly, X11).
+
+image::i3-sync-working.png["Diagram of the i3 sync solution", title="Diagram of the i3 sync solution"]
+
+=== Implementation details
+
+The client which wants to sync with i3 initiates the protocol by sending a
+ClientMessage to the X11 root window:
+
+.Send ClientMessage
+-------------------
+# Generate a ClientMessage, see xcb_client_message_t
+my $msg = pack "CCSLLLLLLL",
+ CLIENT_MESSAGE, # response_type
+ 32, # format
+ 0, # sequence
+ $root, # destination window
+ $x->atom(name => 'I3_SYNC')->id,
+
+ $_sync_window->id, # data[0]: our own window id
+ $myrnd, # data[1]: a random value to identify the request
+ 0,
+ 0,
+ 0;
+
+# Send it to the root window -- since i3 uses the SubstructureRedirect
+# event mask, it will get the ClientMessage.
+$x->send_event(0, $root, EVENT_MASK_SUBSTRUCTURE_REDIRECT, $msg);
+-------------------
+
+i3 will then reply with the same ClientMessage, sent to the window specified in
++data[0]+. In the reply, +data[0]+ and +data[1]+ are exactly the same as in the
+request. You should use a random value in +data[1]+ and check that you received
+the same one when getting the reply.
+
+== Appendix B: Socket activation
+
+Socket activation is a mechanism which was made popular by systemd, an init
+replacement. It basically describes creating a listening socket before starting
+a program. systemd will invoke the program only when an actual connection to
+the socket is made, hence the term socket activation.
+
+The interesting part of this (in the i3 context) is that you can very precisely
+detect when the program is ready (finished its initialization).
+
+=== Preparing the listening socket
+
++complete-run.pl+ will create a listening UNIX socket which it will then pass
+to i3. This socket will be used by i3 as an additional IPC socket, just like
+the one it will create on its own. Passing the socket happens implicitly
+because children will inherit the parent’s sockets when fork()ing and sockets
+will continue to exist after an exec() call (unless CLOEXEC is set of course).
+
+The only explicit things +complete-run.pl+ has to do is setting the +LISTEN_FDS+
+environment variable to the number of sockets which exist (1 in our case) and
+setting the +LISTEN_PID+ environment variable to the current process ID. Both
+variables are necessary so that the program (i3) knows how many sockets it
+should use and if the environment variable is actually intended for it. i3 will
+then start looking for sockets at file descriptor 3 (since 0, 1 and 2 are used
+for stdin, stdout and stderr, respectively).
+
+The actual Perl code which sets up the socket, fork()s, makes sure the socket
+has file descriptor 3 and sets up the environment variables follows (shortened
+a bit):
+
+
+.Setup socket and environment
+-----------------------------
+my $socket = IO::Socket::UNIX->new(
+ Listen => 1,
+ Local => $args{unix_socket_path},
+);
+
+my $pid = fork;
+if ($pid == 0) {
+ $ENV{LISTEN_PID} = $$;
+ $ENV{LISTEN_FDS} = 1;
+
+ # Only pass file descriptors 0 (stdin), 1 (stdout),
+ # 2 (stderr) and 3 (socket) to the child.
+ $^F = 3;
+
+ # If the socket does not use file descriptor 3 by chance
+ # already, we close fd 3 and dup2() the socket to 3.
+ if (fileno($socket) != 3) {
+ POSIX::close(3);
+ POSIX::dup2(fileno($socket), 3);
+ }
+
+ exec "/usr/bin/i3";
+}
+-----------------------------
+
+=== Waiting for a reply
+
+In the parent process, we want to know when i3 is ready to answer our IPC
+requests and handle our windows. Therefore, after forking, we immediately close
+the listening socket (i3 will handle this side of the socket) and connect to it
+(remember, we are talking about a named UNIX socket) as a client. This connect
+call will immediately succeed because the kernel buffers it. Then, we send a
+request (of type GET_TREE, but that is not really relevant). Writing data to
+the socket will also succeed immediately because, again, the kernel buffers it
+(only up to a certain amount of data of course).
+
+Afterwards, we just blockingly wait until we get an answer. In the child
+process, i3 will setup the listening socket in its event loop. Immediately
+after actually starting the event loop, it will notice a new client connecting
+(the parent process) and handle its request. Since all initialization has been
+completed successfully by the time the event loop is entered, we can now assume
+that i3 is ready.
+
+=== Timing and conclusion
+
+A beautiful feature of this mechanism is that it does not depend on timing. It
+does not matter when the child process gets CPU time or when the parent process
+gets CPU time. On heavily loaded machines (or machines with multiple CPUs,
+cores or unreliable schedulers), this makes waiting for i3 much more robust.
+
+Before using socket activation, we typically used a +sleep(1)+ and hoped that
+i3 was initialized by that time. Of course, this breaks on some (slow)
+computers and wastes a lot of time on faster computers. By using socket
+activation, we decreased the total amount of time necessary to run all tests
+(72 files at the time of writing) from > 100 seconds to 16 seconds. This makes
+it significantly more attractive to run the test suite more often (or at all)
+during development.
+
+An alternative approach to using socket activation is polling for the existance
+of the IPC socket and connecting to it. While this might be slightly easier to
+implement, it wastes CPU time and is considerably uglier than this solution
+:). After all, +lib/SocketActivation.pm+ contains only 54 SLOC.
i3 User’s Guide
===============
Michael Stapelberg <michael+i3@stapelberg.de>
-August 2011
+October 2011
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
When holding the floating modifier, you can resize a floating window by
pressing the right mouse button on it and moving around while holding it. If
-you hold the shift button as well, the resize will be proportional.
+you hold the shift button as well, the resize will be proportional (the aspect
+ratio will be preserved).
*Syntax*:
--------------------------------
*Syntax*:
-----------------------------
-for_window [criteria] command
+for_window <criteria> command
-----------------------------
*Examples*:
[[assign_workspace]]
-Specific windows can be matched by window class and/or window title. It is
-recommended that you match on window classes instead of window titles whenever
-possible because some applications first create their window, and then worry
-about setting the correct title. Firefox with Vimperator comes to mind. The
-window starts up being named Firefox, and only when Vimperator is loaded does
-the title change. As i3 will get the title as soon as the application maps the
+To automatically make a specific window show up on a specific workspace, you
+can use an *assignment*. You can match windows by using any criteria,
+see <<command_criteria>>. It is recommended that you match on window classes
+(and instances, when appropriate) instead of window titles whenever possible
+because some applications first create their window, and then worry about
+setting the correct title. Firefox with Vimperator comes to mind. The window
+starts up being named Firefox, and only when Vimperator is loaded does the
+title change. As i3 will get the title as soon as the application maps the
window (mapping means actually displaying it on the screen), you’d need to have
to match on 'Firefox' in this case.
-You can prefix or suffix workspaces with a `~` to specify that matching clients
-should be put into floating mode. If you specify only a `~`, the client will
-not be put onto any workspace, but will be set floating on the current one.
-
*Syntax*:
------------------------------------------------------------
-assign ["]window class[/window title]["] [→] [workspace]
+assign <criteria> [→] workspace
------------------------------------------------------------
*Examples*:
----------------------
-assign urxvt 2
-assign urxvt → 2
-assign urxvt → work
-assign "urxvt" → 2
-assign "urxvt/VIM" → 3
-assign "gecko" → 4
+# Assign URxvt terminals to workspace 2
+assign [class="URxvt"] 2
+
+# Same thing, but more precise (exact match instead of substring)
+assign [class="^URxvt$"] 2
+
+# Same thing, but with a beautiful arrow :)
+assign [class="^URxvt$"] → 2
+
+# Assignment to a named workspace
+assign [class="^URxvt$"] → work
+
+# Start urxvt -name irssi
+assign [class="^URxvt$" instance="^irssi$"] → 3
----------------------
Note that 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
+window, you will see the following output:
+
+*xwininfo*:
+-----------------------------------
+WM_CLASS(STRING) = "irssi", "URxvt"
+-----------------------------------
+
+The first part of the WM_CLASS is the instance ("irssi" in this example), the
+second part is the class ("URxvt" in this example).
+
+Should you have any problems with assignments, make sure to check the i3
+logfile first (see http://i3wm.org/docs/debugging.html). It includes more
+details about the matching process and the window’s actual class, instance and
+title when starting up.
+
=== Automatically starting applications on i3 startup
By using the +exec+ keyword outside a keybinding, you can configure
*Syntax*:
-------------------
-exec command
-exec_always command
+exec [--no-startup-id] command
+exec_always [--no-startup-id] command
-------------------
*Examples*:
--------------------------------
-exec i3status | i3bar -d
+exec chromium
exec_always ~/my_script.sh
+
+# Execute the terminal emulator urxvt, which is not yet startup-notification aware.
+exec --no-startup-id urxvt
--------------------------------
+The flag --no-startup-id is explained in <<exec>>.
+
[[workspace_screen]]
=== Automatically putting workspaces on specific screens
*Syntax*:
----------------------------------
-workspace <number> output <output>
+workspace <workspace> output <output>
----------------------------------
The 'output' is the name of the RandR output you attach your screen to. On a
laptop, you might have VGA1 and LVDS1 as output names. You can see the
available outputs by running +xrandr --current+.
+If you use named workspaces, they must be quoted:
+
*Examples*:
---------------------------
workspace 1 output LVDS1
workspace 5 output VGA1
+workspace "2: vim" output VGA1
---------------------------
=== Changing colors
force_focus_wrapping yes
------------------------
+=== Forcing Xinerama
+
+As explained in-depth in <http://i3wm.org/docs/multi-monitor.html>, some X11
+video drivers (especially the nVidia binary driver) only provide support for
+Xinerama instead of RandR. In such a situation, i3 must be told to use the
+inferior Xinerama API explicitly and therefore don’t provide support for
+reconfiguring your screens on the fly (they are read only once on startup and
+that’s it).
+
+For people who do cannot modify their +~/.xsession+ to add the
++--force-xinerama+ commandline parameter, a configuration option is provided:
+
+*Syntax*:
+-----------------------
+force_xinerama <yes|no>
+-----------------------
+
+*Example*:
+------------------
+force_xinerama yes
+------------------
+
+Also note that your output names are not descriptive (like +HDMI1+) when using
+Xinerama, instead they are counted up, starting at 0: +xinerama-0+, +xinerama-1+, …
+
+=== Automatic back-and-forth when switching to the current workspace
+
+This configuration directive enables automatic +workspace back_and_forth+ (see
+<<back_and_forth>>) when switching to the workspace that is currently focused.
+
+For instance: Assume you are on workspace "1: www" and switch to "2: IM" using
+mod+2 because somebody sent you a message. You don’t need to remember where you
+came from now, you can just press mod+2 again to switch back to "1: www".
+
+*Syntax*:
+--------------------------------------
+workspace_auto_back_and_forth <yes|no>
+--------------------------------------
+
+*Example*:
+---------------------------------
+workspace_auto_back_and_forth yes
+---------------------------------
+
+== Configuring i3bar
+
+The bar at the bottom of your monitor is drawn by a separate process called
+i3bar. Having this part of "the i3 user interface" in a separate process has
+several advantages:
+
+1. It is a modular approach. If you don’t need a workspace bar at all, or if
+ you prefer a different one (dzen2, xmobar, maybe even gnome-panel?), you can
+ just remove the i3bar configuration and start your favorite bar instead.
+2. It follows the UNIX philosophy of "Make each program do one thing well".
+ While i3 manages your windows well, i3bar is good at displaying a bar on
+ each monitor (unless you configure it otherwise).
+3. It leads to two separate, clean codebases. If you want to understand i3, you
+ don’t need to bother with the details of i3bar and vice versa.
+
+That said, i3bar is configured in the same configuration file as i3. This is
+because it is tightly coupled with i3 (in contrary to i3lock or i3status which
+are useful for people using other window managers). Therefore, it makes no
+sense to use a different configuration place when we already have a good
+configuration infrastructure in place.
+
+Configuring your workspace bar starts with opening a +bar+ block. You can have
+multiple bar blocks to use different settings for different outputs (monitors):
+
+*Example*:
+---------------------------
+bar {
+ status_command i3status
+}
+---------------------------
+
+=== Statusline command
+
+i3bar can run a program and display every line of its +stdout+ output on the
+right hand side of the bar. This is useful to display system information like
+your current IP address, battery status or date/time.
+
+The specified command will be passed to +sh -c+, so you can use globbing and
+have to have correct quoting etc.
+
+*Syntax*:
+----------------------
+status_command command
+----------------------
+
+*Example*:
+-------------------------------------------------
+status_command i3status --config ~/.i3status.conf
+-------------------------------------------------
+
+=== Display mode
+
+You can have i3bar either be visible permanently at one edge of the screen
+(+dock+ mode) or make it show up when you press your modifier key (+hide+
+mode).
+
+The hide mode maximizes screen space that can be used for actual windows. Also,
+i3bar sends the +SIGSTOP+ and +SIGCONT+ signals to the statusline process to
+save battery power.
+
+The default is dock mode.
+
+*Syntax*:
+----------------
+mode <dock|hide>
+----------------
+
+*Example*:
+----------------
+mode hide
+----------------
+
+=== Position
+
+This option determines in which edge of the screen i3bar should show up.
+
+The default is bottom.
+
+*Syntax*:
+---------------------
+position <top|bottom>
+---------------------
+
+*Example*:
+---------------------
+position top
+---------------------
+
+=== Output(s)
+
+You can restrict i3bar to one or more outputs (monitors). The default is to
+handle all outputs. Restricting the outputs is useful for using different
+options for different outputs by using multiple 'bar' blocks.
+
+*Syntax*:
+---------------
+output <output>
+---------------
+
+*Example*:
+-------------------------------
+# big monitor: everything
+bar {
+ output HDMI2
+ status_command i3status
+}
+
+# laptop monitor: bright colors and i3status with less modules.
+bar {
+ output LVDS1
+ status_command i3status --config ~/.i3status-small.conf
+ colors {
+ background #000000
+ statusline #ffffff
+ }
+}
+-------------------------------
+
+=== Tray output
+
+i3bar by default provides a system tray area where programs such as
+NetworkManager, VLC, Pidgin, etc. can place little icons.
+
+You can configure on which output (monitor) the icons should be displayed or
+you can turn off the functionality entirely.
+
+*Syntax*:
+-------------------------
+tray_output <none|output>
+-------------------------
+
+*Example*:
+-------------------------
+# disable system tray
+tray_output none
+
+# show tray icons on the big monitor
+tray_output HDMI2
+-------------------------
+
+=== Font
+
+Specifies the font (again, X core font, not Xft, just like in i3) to be used in
+the bar.
+
+*Syntax*:
+---------------------
+font <font>
+---------------------
+
+*Example*:
+--------------------------------------------------------------
+font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+--------------------------------------------------------------
+
+=== Workspace buttons
+
+Specifies whether workspace buttons should be shown or not. This is useful if
+you want to display a statusline-only bar containing additional information.
+
+The default is to show workspace buttons.
+
+*Syntax*:
+--------------------------
+workspace_buttons <yes|no>
+--------------------------
+
+*Example*:
+--------------------
+workspace_buttons no
+--------------------
+
+=== Colors
+
+As with i3, colors are in HTML hex format (#rrggbb). The following colors can
+be configured at the moment:
+
+background::
+ Background color of the bar.
+statusline::
+ Text color to be used for the statusline.
+focused_workspace::
+ Text color/background color for a workspace button when the workspace
+ has focus.
+active_workspace::
+ Text color/background color for a workspace button when the workspace
+ is active (visible) on some output, but the focus is on another one.
+ You can only tell this apart from the focused workspace when you are
+ using multiple monitors.
+inactive_workspace::
+ Text color/background color for a workspace button when the workspace
+ does not have focus and is not active (visible) on any output. This
+ will be the case for most workspaces.
+urgent_workspace::
+ Text color/background color for workspaces which contain at least one
+ window with the urgency hint set.
+
+*Syntax*:
+----------------------------------------
+colors {
+ background <color>
+ statusline <color>
+
+ colorclass <foreground> <background>
+}
+----------------------------------------
+
+*Example*:
+--------------------------------------
+colors {
+ background #000000
+ statusline #ffffff
+
+ focused_workspace #ffffff #285577
+ active_workspace #ffffff #333333
+ inactive_workspace #888888 #222222
+ urgent_workspace #ffffff #900000
+}
+--------------------------------------
+
== List of commands
Commands are what you bind to specific keypresses. You can also issue commands
*Example*:
------------------------------------
bindsym mod+x [class="Firefox"] kill
+
+# same thing, but case-insensitive
+bindsym mod+x [class="(?i)firefox"] kill
------------------------------------
The criteria which are currently implemented are:
Compares the window class (the second part of WM_CLASS)
instance::
Compares the window instance (the first part of WM_CLASS)
+window_role::
+ Compares the window role (WM_WINDOW_ROLE).
id::
Compares the X11 window ID, which you can get via +xwininfo+ for example.
title::
Compares the X11 window title (_NET_WM_NAME or WM_NAME as fallback).
-mark::
+con_mark::
Compares the mark set for this container, see <<vim_like_marks>>.
con_id::
Compares the i3-internal container ID, which you can get via the IPC
interface. Handy for scripting.
-Note that currently all criteria are compared case-insensitive and do not
-support regular expressions. This is planned to change in the future.
+The criteria +class+, +instance+, +role+, +title+ and +mark+ are actually
+regular expressions (PCRE). See +pcresyntax(3)+ or +perldoc perlre+ for
+information on how to use them.
+
+[[exec]]
+
+=== Executing applications (exec)
+
+What good is a window manager if you can’t actually start any applications?
+The exec command starts an application by passing the command you specify to a
+shell. This implies that you can use globbing (wildcards) and programs will be
+searched in your $PATH.
+
+*Syntax*:
+------------------------------
+exec [--no-startup-id] command
+------------------------------
+
+*Example*:
+------------------------------
+# Start the GIMP
+bindsym mod+g exec gimp
+
+# Start the terminal emulator urxvt which is not yet startup-notification-aware
+bindsym mod+enter exec --no-startup-id urxvt
+------------------------------
+
+The +--no-startup-id+ parameter disables startup-notification support for this
+particular exec command. With startup-notification, i3 can make sure that a
+window appears on the workspace on which you used the exec command. Also, it
+will change the X11 cursor to +watch+ (a clock) while the application is
+launching. So, if an application is not startup-notification aware (most GTK
+and Qt using applications seem to be, though), you will end up with a watch
+cursor for 60 seconds.
=== Splitting containers
For moving, use +move left+, +move right+, +move down+ and +move up+.
+*Syntax*:
+-----------------------------------
+focus <left|right|down|up>
+focus <parent|child|floating|tiling|mode_toggle>
+move <left|right|down|up> [<px> px]
+-----------------------------------
+
+Note that the amount of pixels you can specify for the +move+ command is only
+relevant for floating containers. The default amount is 10 pixels.
+
*Examples*:
----------------------
-# Focus clients on the left, bottom, top, right:
+# Focus container on the left, bottom, top, right:
bindsym mod+j focus left
bindsym mod+k focus down
bindsym mod+l focus up
# Focus last floating/tiling container
bindsym mod+g focus mode_toggle
-# Move client to the left, bottom, top, right:
+# Move container to the left, bottom, top, right:
bindsym mod+j move left
bindsym mod+k move down
bindsym mod+l move up
bindsym mod+semicolon move right
+
+# Move container, but make floating containers
+# move more than the default
+bindsym mod+j move left 20 px
----------------------
=== Changing (named) workspaces/moving to workspaces
You can also switch to the next and previous workspace with the commands
+workspace next+ and +workspace prev+, which is handy, for example, if you have
workspace 1, 3, 4 and 9 and you want to cycle through them with a single key
-combination.
+combination. Similarily, you can use +move workspace next+ and +move workspace
+prev+ to move a container to the next/previous workspace.
+
+[[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 output+ command followed by the name of the target output. You
bindsym mod+Shift+1 move workspace 1
bindsym mod+Shift+2 move workspace 2
...
+
+# switch between the current and the previously focused one
+bindsym mod+b workspace back_and_forth
-------------------------
==== Named workspaces
Direction can be one of +up+, +down+, +left+ or +right+. The optional pixel
argument specifies by how many pixels a *floating container* should be grown or
-shrinked (the default is 10 pixels). The ppt argument means percentage points
+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 shrinked (the default is 10 percentage points).
+grown or shrunk (the default is 10 percentage points).
I recommend using the resize command inside a so called +mode+:
<h1>The multi-monitor situation</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">March 2010</span>\r
+<span id="revdate">September 2011</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="content">\r
<pre><tt>exec i3 --force-xinerama -V >>~/.i3/i3log 2>&1</tt></pre>\r
</div></div>\r
+<div class="paragraph"><p>…or use <tt>force_xinerama yes</tt> in your configuration file.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
these are two screens).</p></div>\r
<div class="paragraph"><p>For this very reason, we decided to implement the following workaround: As\r
long as the nVidia driver does not support RandR, an option called\r
-<tt>--force-xinerama</tt> is available in i3. This option gets the list of screens\r
-<strong>once</strong> when starting, and never updates it. As the nVidia driver cannot do\r
-dynamic configuration anyways, this is not a big deal.</p></div>\r
+<tt>--force-xinerama</tt> is available in i3 (alternatively, you can use the\r
+<tt>force_xinerama</tt> configuration file directive). This option gets the list of\r
+screens <strong>once</strong> when starting, and never updates it. As the nVidia driver cannot\r
+do dynamic configuration anyways, this is not a big deal.</p></div>\r
+<div class="paragraph"><p>Also note that your output names are not descriptive (like <tt>HDMI1</tt>) when using\r
+Xinerama, instead they are counted up, starting at 0: <tt>xinerama-0</tt>, <tt>xinerama-1</tt>, …</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\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
+<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
+<script type="text/javascript">\r
+/*<![CDATA[*/\r
+window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}\r
+/*]]>*/\r
+</script>\r
+<script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\r
+</head>\r
+<body class="article">\r
+\r
+ <div id="main">\r
+ <a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>\r
+ <ul id="nav">\r
+ <li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>\r
+ <li><a href="/screenshots">Screens</a></li>\r
+ <li><a href="/contact">Contact</a></li>\r
+ <li><a href="http://bugs.i3wm.org/">Bugs</a></li>\r
+ </ul>\r
+ <br style="clear: both">\r
+<div id="content">\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
+<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 id="preamble">\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>This document explains how the i3 testsuite works, how to use it and extend it.\r
+It is targeted at developers who not necessarily have been doing testing before\r
+or have not been testing in Perl before. In general, the testsuite is not of\r
+interest for end users.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_introduction">1. Introduction</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>The i3 testsuite is a collection of files which contain testcases for various\r
+i3 features. Some of them test if a certain workflow works correctly (moving\r
+windows, focus behaviour, …). Others are regression tests and contain code\r
+which previously made i3 crash or lead to unexpected behaviour. They then check\r
+if i3 still runs (meaning it did not crash) and if it handled everything\r
+correctly.</p></div>\r
+<div class="paragraph"><p>The goal of having these tests is to automatically find problems and to\r
+automatically get a feel for whether a change in the source code breaks any\r
+existing feature. After every modification of the i3 sourcecode, the developer\r
+should run the full testsuite. If one of the tests fails, the corresponding\r
+problem should be fixed (or, in some cases, the testcase has to be modified).\r
+For every bugreport, a testcase should be written to test the correct\r
+behaviour. Initially, it will fail, but after fixing the bug, it will pass.\r
+This ensures (or increases the chance) that bugs which have been fixed once\r
+will never be found again.</p></div>\r
+<div class="paragraph"><p>Also, when implementing a new feature, a testcase might be a good way to be\r
+able to easily test if the feature is working correctly. Many developers will\r
+test manually if everything works. Having a testcase not only helps you with\r
+that, but it will also be useful for every future change.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_implementation">2. 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
+<li>\r
+<p>\r
+Perl has a long tradition of testing. Every popular/bigger Perl module which\r
+ you can find on CPAN will not only come with documentation, but also with\r
+ tests. Therefore, the available infrastructure for tests is comprehensive.\r
+ See for example the excellent <a href="http://search.cpan.org/perldoc?Test::More">http://search.cpan.org/perldoc?Test::More</a>\r
+ and the referenced <a href="http://search.cpan.org/perldoc?Test::Tutorial">http://search.cpan.org/perldoc?Test::Tutorial</a>.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Perl is widely available and has a well-working package infrastructure.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The author is familiar with Perl :).\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
+<div class="sect3">\r
+<h4 id="_script_complete_run">2.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
+with an appropriate configuration file and creates a folder for each run\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 the Xdummy script).</p></div>\r
+<div class="listingblock">\r
+<div class="title">Example invocation of complete-run.pl+</div>\r
+<div class="content">\r
+<pre><tt>$ cd ~/i3/testcases\r
+\r
+$ ./complete-run.pl\r
+# output omitted because it is very long\r
+All tests successful.\r
+Files=78, Tests=734, 27 wallclock secs ( 0.38 usr 0.48 sys + 17.65 cusr 3.21 csys = 21.72 CPU)\r
+Result: PASS\r
+\r
+$ ./complete-run.pl t/04-floating.t\r
+[:3] i3 startup: took 0.07s, status = 1\r
+[:3] Running t/04-floating.t with logfile testsuite-2011-09-24-16-06-04-4.0.2-226-g1eb011a/i3-log-for-04-floating.t\r
+[:3] t/04-floating.t finished\r
+[:3] killing i3\r
+output for t/04-floating.t:\r
+ok 1 - use X11::XCB::Window;\r
+ok 2 - The object isa X11::XCB::Window\r
+ok 3 - Window is mapped\r
+ok 4 - i3 raised the width to 75\r
+ok 5 - i3 raised the height to 50\r
+ok 6 - i3 did not map it to (0x0)\r
+ok 7 - The object isa X11::XCB::Window\r
+ok 8 - i3 let the width at 80\r
+ok 9 - i3 let the height at 90\r
+ok 10 - i3 mapped it to x=1\r
+ok 11 - i3 mapped it to y=18\r
+ok 12 - The object isa X11::XCB::Window\r
+ok 13 - i3 let the width at 80\r
+ok 14 - i3 let the height at 90\r
+1..14\r
+\r
+All tests successful.\r
+Files=1, Tests=14, 0 wallclock secs ( 0.01 usr 0.00 sys + 0.19 cusr 0.03 csys = 0.23 CPU)\r
+Result: PASS\r
+\r
+$ less latest/i3-log-for-04-floating.t</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect3">\r
+<h4 id="_ipc_interface">2.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
+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>\r
+<div class="sect3">\r
+<h4 id="_x11_xcb">2.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
+X11. They work in a very similar way to libxcb (which i3 uses) and provide\r
+relatively high-level interfaces (objects such as <tt>X11::XCB::Window</tt>) aswell as\r
+access to the low-level interface, which is very useful when testing a window\r
+manager.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_filesystem_structure">2.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
+(their file extension is .t, not .pl) themselves can be found in the\r
+conventionally named subfolder <tt>t</tt>:</p></div>\r
+<div class="listingblock">\r
+<div class="title">Filesystem structure</div>\r
+<div class="content">\r
+<pre><tt>├── testcases\r
+│ ├── complete-run.pl\r
+│ ├── i3-test.config\r
+│ ├── lib\r
+│ │ ├── i3test.pm\r
+│ │ ├── SocketActivation.pm\r
+│ │ └── StartXDummy.pm\r
+│ ├── t\r
+│ │ ├── 00-load.t\r
+│ │ ├── 01-tile.t\r
+│ │ ├── 02-fullscreen.t\r
+│ │ ├── ...\r
+│ │ ├── omitted for brevity\r
+│ │ ├── ...\r
+│ │ └── 74-regress-focus-toggle.t\r
+│ └── Xdummy</tt></pre>\r
+</div></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_anatomy_of_a_testcase">3. 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
+step by step:</p></div>\r
+<div class="listingblock">\r
+<div class="title">t/11-goto.t: Boilerplate</div>\r
+<div class="content">\r
+<pre><tt>#!perl\r
+# vim:ts=4:sw=4:expandtab\r
+\r
+use i3test;\r
+use File::Temp;\r
+\r
+my $x = X11::XCB::Connection->new;</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>This is what we call boilerplate. It exists at the top of every test file (to\r
+some extent). The first line is the shebang, which specifies that this file is\r
+a Perl script. The second line contains VIM specific settings on how to\r
+edit/format this file (use spaces instead of tabs, indent using 4 spaces).\r
+Afterwards, the <tt>i3test</tt> module is used. This module contains i3 testsuite\r
+specific functions which you are strongly encouraged to use. They make writing\r
+testcases a lot easier and will make it easier for other people to read your\r
+tests.</p></div>\r
+<div class="paragraph"><p>The next line uses the <tt>File::Temp</tt> module. This is specific to this testcase,\r
+because it needs to generate a temporary name during the test. Many testcases\r
+use only the <tt>i3test</tt> module.</p></div>\r
+<div class="paragraph"><p>The last line opens a connection to X11. You might or might not need this in\r
+your testcase, depending on whether you are going to open windows (etc.) or\r
+only use i3 commands.</p></div>\r
+<div class="listingblock">\r
+<div class="title">t/11-goto.t: Setup</div>\r
+<div class="content">\r
+<pre><tt>my $tmp = fresh_workspace;\r
+\r
+cmd 'split h';</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>The first line calls i3test’s <tt>fresh_workspace</tt> function which looks for a\r
+currently unused workspace, switches to it, and returns its name. The variable\r
+<tt>$tmp</tt> will end up having a value such as <tt>"/tmp/87kBVcHbA9"</tt>. Note that this\r
+is not (necessarily) a valid path, it’s just a random workspace name.</p></div>\r
+<div class="paragraph"><p>So, now that we are on a new workspace, we ensure that the workspace uses\r
+horizontal orientation by issuing the <tt>split h</tt> command (see the i3 User’s\r
+Guide for a list of commands). This is not strictly necessary, but good style.\r
+In general, the <tt>cmd</tt> function executes the specified i3 command by using the\r
+IPC interface and returns once i3 acknowledged the command.</p></div>\r
+<div class="listingblock">\r
+<div class="title">t/11-goto.t: Setup</div>\r
+<div class="content">\r
+<pre><tt>#####################################################################\r
+# Create two windows and make sure focus switching works\r
+#####################################################################\r
+\r
+my $top = open_window($x);\r
+my $mid = open_window($x);\r
+my $bottom = open_window($x);</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>In every major section of a testcase, you should put a comment like the one\r
+above. This makes it immediately clear how the file is structured.</p></div>\r
+<div class="paragraph"><p>The <tt>open_window</tt> function opens a standard window, which will then be put into\r
+tiling mode by i3. If you want a floating window, use the\r
+<tt>open_floating_window</tt> function. These functions accept the same parameters as\r
+<tt>X11::XCB::Window→new</tt>, see the i3test documentation at TODO.</p></div>\r
+<div class="listingblock">\r
+<div class="title">t/11-goto.t: Helper function</div>\r
+<div class="content">\r
+<pre><tt>#\r
+# Returns the input focus after sending the given command to i3 via IPC\r
+# and syncing with i3\r
+#\r
+sub focus_after {\r
+ my $msg = shift;\r
+\r
+ cmd $msg;\r
+ sync_with_i3 $x;\r
+ return $x->input_focus;\r
+}</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>This section defines a helper function which will be used over and over in this\r
+testcase. If you have code which gets executed more than once or twice\r
+(depending on the length of your test, use your best judgement), please put it\r
+in a function. Tests should be short, concise and clear.</p></div>\r
+<div class="paragraph"><p>The <tt>focus_after</tt> function executes a command and returns the X11 focus after\r
+the command was executed. The <tt>sync_with_i3</tt> command makes sure that i3 could\r
+push its state to X11. See <a href="#i3_sync">[i3_sync]</a> to learn how this works exactly.</p></div>\r
+<div class="listingblock">\r
+<div class="title">t/11-goto.t: Test assumptions</div>\r
+<div class="content">\r
+<pre><tt>$focus = $x->input_focus;\r
+is($focus, $bottom->id, "Latest window focused");\r
+\r
+$focus = focus_after('focus left');\r
+is($focus, $mid->id, "Middle window focused");</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Now, we run the first two real tests. They use <tt>Test::More</tt>'s <tt>is</tt> function,\r
+which compares two values and prints the differences if they are not the same.\r
+After the arguments, we supply a short comment to indicate what we are testing\r
+here. This makes it vastly more easy for the developer to spot which testcase\r
+is the problem in case one fails.</p></div>\r
+<div class="paragraph"><p>The first test checks that the most recently opened window is focused.\r
+Afterwards, the command <tt>focus left</tt> is issued and it is verified that the\r
+middle window now has focus.</p></div>\r
+<div class="paragraph"><p>Note that this is not a comprehensive test of the <tt>focus</tt> command — we would\r
+have to test wrapping, focus when using a more complex layout, focusing the\r
+parent/child containers, etc. But that is not the point of this testcase.\r
+Instead, we just want to know if <tt>$x→input_focus</tt> corresponds with what we are\r
+expecting. If not, something is completely wrong with the test environment and\r
+this trivial test will fail.</p></div>\r
+<div class="listingblock">\r
+<div class="title">t/11-goto.t: Test that the feature does not work (yet)</div>\r
+<div class="content">\r
+<pre><tt>#####################################################################\r
+# Now goto a mark which does not exist\r
+#####################################################################\r
+\r
+my $random_mark = mktemp('mark.XXXXXX');\r
+\r
+$focus = focus_after(qq|[con_mark="$random_mark"] focus|);\r
+is($focus, $mid->id, "focus unchanged");</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Syntax hint: The qq keyword is the interpolating quote operator. It lets you\r
+chose a quote character (in this case the <tt>|</tt> character, a pipe). This makes\r
+having double quotes in our string easy.</p></div>\r
+<div class="paragraph"><p>In this new major section, a random mark (mark is an identifier for a window,\r
+see "VIM-like marks" in the i3 User’s Guide) will be generated. Afterwards, we\r
+test that trying to focus that mark will not do anything. This is important: Do\r
+not only test that using a feature has the expected outcome, but also test that\r
+using it without properly initializing it does no harm. This command could for\r
+example have changed focus anyways (a bug) or crash i3 (obviously a bug).</p></div>\r
+<div class="listingblock">\r
+<div class="title">t/11-goto.t: Test that the feature does work</div>\r
+<div class="content">\r
+<pre><tt>cmd "mark $random_mark";\r
+\r
+$focus = focus_after('focus left');\r
+is($focus, $top->id, "Top window focused");\r
+\r
+$focus = focus_after(qq|[con_mark="$random_mark"] focus|);\r
+is($focus, $mid->id, "goto worked");</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Remember: Focus was on the middle window (we verified that earlier in "Test\r
+assumptions"). We now mark the middle window with our randomly generated mark.\r
+Afterwards, we switch focus away from the middle window to be able to tell if\r
+focusing it via its mark will work. If the test works, the goto command seems\r
+to be working.</p></div>\r
+<div class="listingblock">\r
+<div class="title">t/11-goto.t: Test corner case</div>\r
+<div class="content">\r
+<pre><tt># check that we can specify multiple criteria\r
+\r
+$focus = focus_after('focus left');\r
+is($focus, $top->id, "Top window focused");\r
+\r
+$focus = focus_after(qq|[con_mark="$random_mark" con_mark="$random_mark"] focus|);\r
+is($focus, $mid->id, "goto worked");</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Now we test the same feature, but specifying the mark twice in the command.\r
+This should have no effect, but let’s be sure: test it and see if things go\r
+wrong.</p></div>\r
+<div class="listingblock">\r
+<div class="title">t/11-goto.t: Test second code path</div>\r
+<div class="content">\r
+<pre><tt>#####################################################################\r
+# Check whether the focus command will switch to a different\r
+# workspace if necessary\r
+#####################################################################\r
+\r
+my $tmp2 = fresh_workspace;\r
+\r
+is(focused_ws(), $tmp2, 'tmp2 now focused');\r
+\r
+cmd qq|[con_mark="$random_mark"] focus|;\r
+\r
+is(focused_ws(), $tmp, 'tmp now focused');</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>This part of the test checks that focusing windows by mark works across\r
+workspaces. It uses i3test’s <tt>focused_ws</tt> function to get the current\r
+workspace.</p></div>\r
+<div class="listingblock">\r
+<div class="title">t/11-goto.t: Test second code path</div>\r
+<div class="content">\r
+<pre><tt>done_testing;</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>The end of every testcase has to contain the <tt>done_testing</tt> line. This tells\r
+<tt>complete-run.pl</tt> that the test was finished successfully. If it does not\r
+occur, the test might have crashed during execution — some of the reasons why\r
+that could happen are bugs in the used modules, bugs in the testcase itself or\r
+an i3 crash resulting in the testcase being unable to communicate with i3 via\r
+IPC anymore.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="i3_sync">4. 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
+properly. Sounds simple, right? Let’s assume you use this straight-forward\r
+implementation:</p></div>\r
+<div class="listingblock">\r
+<div class="title">Racey focus testcase</div>\r
+<div class="content">\r
+<pre><tt>my $left = open_window($x);\r
+my $right = open_window($x);\r
+cmd 'focus left';\r
+is($x->input_focus, $left->id, 'left window focused');</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>However, the test fails. Sometimes. Apparantly, there is a race condition in\r
+your test. If you think about it, this is because you are using two different\r
+pieces of software: You tell i3 to update focus, i3 confirms that, and then you\r
+ask X11 to give you the current focus. There is a certain time i3 needs to\r
+update the X11 state. If the testcase gets CPU time before X11 processed i3’s\r
+requests, the test will fail.</p></div>\r
+<div class="imageblock">\r
+<div class="content">\r
+<img src="i3-sync.png" alt="Diagram of the race condition" />\r
+</div>\r
+<div class="title">Figure 1. Diagram of the race condition</div>\r
+</div>\r
+<div class="paragraph"><p>One way to "solve" this would be to add <tt>sleep 0.5;</tt> after the <tt>cmd</tt> call.\r
+After 0.5 seconds it should be safe to assume that focus has been updated,\r
+right?</p></div>\r
+<div class="paragraph"><p>In practice, this usually works. However, it has several problems:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+This is obviously not a clean solution, but a workaround. Ugly.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+On very slow machines, this might not work. Unlikely, but in different\r
+ situations (a delay to wait for i3 to startup) the necessary time is much\r
+ harder to guess, even for fast machines.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+This <strong>wastes a lot of time</strong>. Usually, your computer is much faster than 0.5s\r
+ to update the status. However, sometimes, it might take 0.4s, so we can’t\r
+ make it <tt>sleep 0.1</tt>.\r
+</p>\r
+</li>\r
+</ol></div>\r
+<div class="paragraph"><p>To illustrate how grave the problem with wasting time actually is: Before\r
+removing all sleeps from the testsuite, a typical run using 4 separate X\r
+servers took around 50 seconds on my machine. After removing all the sleeps,\r
+we achieved times of about 25 seconds. This is very significant and influences\r
+the way you think about tests — the faster they are, the more likely you are\r
+to check whether everything still works quite often (which you should).</p></div>\r
+<div class="paragraph"><p>What I am trying to say is: Delays adds up quickly and make the test suite\r
+less robust.</p></div>\r
+<div class="paragraph"><p>The real solution for this problem is a mechanism which I call "the i3 sync\r
+protocol". The idea is to send a request (which does not modify state) via X11\r
+to i3 which will then be answered. Due to the request’s position in the event\r
+queue (<strong>after</strong> all previous events), you can be sure that by the time you\r
+receive the reply, all other events have been dealt with by i3 (and, more\r
+importantly, X11).</p></div>\r
+<div class="imageblock">\r
+<div class="content">\r
+<img src="i3-sync-working.png" alt="Diagram of the i3 sync solution" />\r
+</div>\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
+<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 class="title">Send ClientMessage</div>\r
+<div class="content">\r
+<pre><tt># Generate a ClientMessage, see xcb_client_message_t\r
+my $msg = pack "CCSLLLLLLL",\r
+ CLIENT_MESSAGE, # response_type\r
+ 32, # format\r
+ 0, # sequence\r
+ $root, # destination window\r
+ $x->atom(name => 'I3_SYNC')->id,\r
+\r
+ $_sync_window->id, # data[0]: our own window id\r
+ $myrnd, # data[1]: a random value to identify the request\r
+ 0,\r
+ 0,\r
+ 0;\r
+\r
+# Send it to the root window -- since i3 uses the SubstructureRedirect\r
+# event mask, it will get the ClientMessage.\r
+$x->send_event(0, $root, EVENT_MASK_SUBSTRUCTURE_REDIRECT, $msg);</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>i3 will then reply with the same ClientMessage, sent to the window specified in\r
+<tt>data[0]</tt>. In the reply, <tt>data[0]</tt> and <tt>data[1]</tt> are exactly the same as in the\r
+request. You should use a random value in <tt>data[1]</tt> and check that you received\r
+the same one when getting the reply.</p></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_appendix_b_socket_activation">5. 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
+a program. systemd will invoke the program only when an actual connection to\r
+the socket is made, hence the term socket activation.</p></div>\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
+<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
+because children will inherit the parent’s sockets when fork()ing and sockets\r
+will continue to exist after an exec() call (unless CLOEXEC is set of course).</p></div>\r
+<div class="paragraph"><p>The only explicit things <tt>complete-run.pl</tt> has to do is setting the <tt>LISTEN_FDS</tt>\r
+environment variable to the number of sockets which exist (1 in our case) and\r
+setting the <tt>LISTEN_PID</tt> environment variable to the current process ID. Both\r
+variables are necessary so that the program (i3) knows how many sockets it\r
+should use and if the environment variable is actually intended for it. i3 will\r
+then start looking for sockets at file descriptor 3 (since 0, 1 and 2 are used\r
+for stdin, stdout and stderr, respectively).</p></div>\r
+<div class="paragraph"><p>The actual Perl code which sets up the socket, fork()s, makes sure the socket\r
+has file descriptor 3 and sets up the environment variables follows (shortened\r
+a bit):</p></div>\r
+<div class="listingblock">\r
+<div class="title">Setup socket and environment</div>\r
+<div class="content">\r
+<pre><tt>my $socket = IO::Socket::UNIX->new(\r
+ Listen => 1,\r
+ Local => $args{unix_socket_path},\r
+);\r
+\r
+my $pid = fork;\r
+if ($pid == 0) {\r
+ $ENV{LISTEN_PID} = $$;\r
+ $ENV{LISTEN_FDS} = 1;\r
+\r
+ # Only pass file descriptors 0 (stdin), 1 (stdout),\r
+ # 2 (stderr) and 3 (socket) to the child.\r
+ $^F = 3;\r
+\r
+ # If the socket does not use file descriptor 3 by chance\r
+ # already, we close fd 3 and dup2() the socket to 3.\r
+ if (fileno($socket) != 3) {\r
+ POSIX::close(3);\r
+ POSIX::dup2(fileno($socket), 3);\r
+ }\r
+\r
+ exec "/usr/bin/i3";\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_waiting_for_a_reply">5.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
+(remember, we are talking about a named UNIX socket) as a client. This connect\r
+call will immediately succeed because the kernel buffers it. Then, we send a\r
+request (of type GET_TREE, but that is not really relevant). Writing data to\r
+the socket will also succeed immediately because, again, the kernel buffers it\r
+(only up to a certain amount of data of course).</p></div>\r
+<div class="paragraph"><p>Afterwards, we just blockingly wait until we get an answer. In the child\r
+process, i3 will setup the listening socket in its event loop. Immediately\r
+after actually starting the event loop, it will notice a new client connecting\r
+(the parent process) and handle its request. Since all initialization has been\r
+completed successfully by the time the event loop is entered, we can now assume\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
+<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
+cores or unreliable schedulers), this makes waiting for i3 much more robust.</p></div>\r
+<div class="paragraph"><p>Before using socket activation, we typically used a <tt>sleep(1)</tt> and hoped that\r
+i3 was initialized by that time. Of course, this breaks on some (slow)\r
+computers and wastes a lot of time on faster computers. By using socket\r
+activation, we decreased the total amount of time necessary to run all tests\r
+(72 files at the time of writing) from > 100 seconds to 16 seconds. This makes\r
+it significantly more attractive to run the test suite more often (or at all)\r
+during development.</p></div>\r
+<div class="paragraph"><p>An alternative approach to using socket activation is polling for the existance\r
+of the IPC socket and connecting to it. While this might be slightly easier to\r
+implement, it wastes CPU time and is considerably uglier than this solution\r
+:). After all, <tt>lib/SocketActivation.pm</tt> contains only 54 SLOC.</p></div>\r
+</div>\r
+</div>\r
+</div>\r
+</div>\r
+<div id="footnotes"><hr /></div>\r
+<div id="footer" lang="de">\r
+© 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>\r
+</div>\r
+</body>\r
+</html>\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">August 2011</span>\r
+<span id="revdate">October 2011</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>
it to the position you want.</p></div>\r
<div class="paragraph"><p>When holding the floating modifier, you can resize a floating window by\r
pressing the right mouse button on it and moving around while holding it. If\r
-you hold the shift button as well, the resize will be proportional.</p></div>\r
+you hold the shift button as well, the resize will be proportional (the aspect\r
+ratio will be preserved).</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>for_window [criteria] command</tt></pre>\r
+<pre><tt>for_window <criteria> command</tt></pre>\r
</div></div>\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
</div>\r
<div class="sect2">\r
<h3 id="_automatically_putting_clients_on_specific_workspaces">4.10. Automatically putting clients on specific workspaces</h3>\r
-<div class="paragraph" id="assign_workspace"><p>Specific windows can be matched by window class and/or window title. It is\r
-recommended that you match on window classes instead of window titles whenever\r
-possible because some applications first create their window, and then worry\r
-about setting the correct title. Firefox with Vimperator comes to mind. The\r
-window starts up being named Firefox, and only when Vimperator is loaded does\r
-the title change. As i3 will get the title as soon as the application maps the\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
+(and instances, when appropriate) instead of window titles whenever possible\r
+because some applications first create their window, and then worry about\r
+setting the correct title. Firefox with Vimperator comes to mind. The window\r
+starts up being named Firefox, and only when Vimperator is loaded does the\r
+title change. As i3 will get the title as soon as the application maps the\r
window (mapping means actually displaying it on the screen), you’d need to have\r
to match on <em>Firefox</em> in this case.</p></div>\r
-<div class="paragraph"><p>You can prefix or suffix workspaces with a <tt>~</tt> to specify that matching clients\r
-should be put into floating mode. If you specify only a <tt>~</tt>, the client will\r
-not be put onto any workspace, but will be set floating on the current one.</p></div>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>assign ["]window class[/window title]["] [→] [workspace]</tt></pre>\r
+<pre><tt>assign <criteria> [→] workspace</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>assign urxvt 2\r
-assign urxvt → 2\r
-assign urxvt → work\r
-assign "urxvt" → 2\r
-assign "urxvt/VIM" → 3\r
-assign "gecko" → 4</tt></pre>\r
+<pre><tt># Assign URxvt terminals to workspace 2\r
+assign [class="URxvt"] 2\r
+\r
+# Same thing, but more precise (exact match instead of substring)\r
+assign [class="^URxvt$"] 2\r
+\r
+# Same thing, but with a beautiful arrow :)\r
+assign [class="^URxvt$"] → 2\r
+\r
+# Assignment to a named workspace\r
+assign [class="^URxvt$"] → work\r
+\r
+# Start urxvt -name irssi\r
+assign [class="^URxvt$" instance="^irssi$"] → 3</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
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 class="paragraph"><p><strong>xwininfo</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>WM_CLASS(STRING) = "irssi", "URxvt"</tt></pre>\r
+</div></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
+details about the matching process and the window’s actual class, instance and\r
+title when starting up.</p></div>\r
</div>\r
<div class="sect2">\r
<h3 id="_automatically_starting_applications_on_i3_startup">4.11. Automatically starting applications on i3 startup</h3>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>exec command\r
-exec_always command</tt></pre>\r
+<pre><tt>exec [--no-startup-id] command\r
+exec_always [--no-startup-id] command</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>exec i3status | i3bar -d\r
-exec_always ~/my_script.sh</tt></pre>\r
+<pre><tt>exec chromium\r
+exec_always ~/my_script.sh\r
+\r
+# Execute the terminal emulator urxvt, which is not yet startup-notification aware.\r
+exec --no-startup-id urxvt</tt></pre>\r
</div></div>\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.12. Automatically putting workspaces on specific screens</h3>\r
<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>workspace <number> output <output></tt></pre>\r
+<pre><tt>workspace <workspace> output <output></tt></pre>\r
</div></div>\r
<div class="paragraph"><p>The <em>output</em> is the name of the RandR output you attach your screen to. On a\r
laptop, you might have VGA1 and LVDS1 as output names. You can see the\r
available outputs by running <tt>xrandr --current</tt>.</p></div>\r
+<div class="paragraph"><p>If you use named workspaces, they must be quoted:</p></div>\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>workspace 1 output LVDS1\r
-workspace 5 output VGA1</tt></pre>\r
+workspace 5 output VGA1\r
+workspace "2: vim" output VGA1</tt></pre>\r
</div></div>\r
</div>\r
<div class="sect2">\r
<pre><tt>force_focus_wrapping yes</tt></pre>\r
</div></div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_forcing_xinerama">4.18. 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
+inferior Xinerama API explicitly and therefore don’t provide support for\r
+reconfiguring your screens on the fly (they are read only once on startup and\r
+that’s it).</p></div>\r
+<div class="paragraph"><p>For people who do cannot modify their <tt>~/.xsession</tt> to add the\r
+<tt>--force-xinerama</tt> commandline parameter, a configuration option is provided:</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>force_xinerama <yes|no></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>force_xinerama yes</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Also note that your output names are not descriptive (like <tt>HDMI1</tt>) when using\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.19. 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
+mod+2 because somebody sent you a message. You don’t need to remember where you\r
+came from now, you can just press mod+2 again to switch back to "1: www".</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>workspace_auto_back_and_forth <yes|no></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>workspace_auto_back_and_forth yes</tt></pre>\r
+</div></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_configuring_i3bar">5. Configuring i3bar</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>The bar at the bottom of your monitor is drawn by a separate process called\r
+i3bar. Having this part of "the i3 user interface" in a separate process has\r
+several advantages:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+It is a modular approach. If you don’t need a workspace bar at all, or if\r
+ you prefer a different one (dzen2, xmobar, maybe even gnome-panel?), you can\r
+ just remove the i3bar configuration and start your favorite bar instead.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+It follows the UNIX philosophy of "Make each program do one thing well".\r
+ While i3 manages your windows well, i3bar is good at displaying a bar on\r
+ each monitor (unless you configure it otherwise).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+It leads to two separate, clean codebases. If you want to understand i3, you\r
+ don’t need to bother with the details of i3bar and vice versa.\r
+</p>\r
+</li>\r
+</ol></div>\r
+<div class="paragraph"><p>That said, i3bar is configured in the same configuration file as i3. This is\r
+because it is tightly coupled with i3 (in contrary to i3lock or i3status which\r
+are useful for people using other window managers). Therefore, it makes no\r
+sense to use a different configuration place when we already have a good\r
+configuration infrastructure in place.</p></div>\r
+<div class="paragraph"><p>Configuring your workspace bar starts with opening a <tt>bar</tt> block. You can have\r
+multiple bar blocks to use different settings for different outputs (monitors):</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>bar {\r
+ status_command i3status\r
+}</tt></pre>\r
+</div></div>\r
+<div class="sect2">\r
+<h3 id="_statusline_command">5.1. Statusline command</h3>\r
+<div class="paragraph"><p>i3bar can run a program and display every line of its <tt>stdout</tt> output on the\r
+right hand side of the bar. This is useful to display system information like\r
+your current IP address, battery status or date/time.</p></div>\r
+<div class="paragraph"><p>The specified command will be passed to <tt>sh -c</tt>, so you can use globbing and\r
+have to have correct quoting etc.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>status_command command</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>status_command i3status --config ~/.i3status.conf</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_display_mode">5.2. Display mode</h3>\r
+<div class="paragraph"><p>You can have i3bar either be visible permanently at one edge of the screen\r
+(<tt>dock</tt> mode) or make it show up when you press your modifier key (<tt>hide</tt>\r
+mode).</p></div>\r
+<div class="paragraph"><p>The hide mode maximizes screen space that can be used for actual windows. Also,\r
+i3bar sends the <tt>SIGSTOP</tt> and <tt>SIGCONT</tt> signals to the statusline process to\r
+save battery power.</p></div>\r
+<div class="paragraph"><p>The default is dock mode.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>mode <dock|hide></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>mode hide</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_position">5.3. Position</h3>\r
+<div class="paragraph"><p>This option determines in which edge of the screen i3bar should show up.</p></div>\r
+<div class="paragraph"><p>The default is bottom.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>position <top|bottom></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>position top</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_output_s">5.4. Output(s)</h3>\r
+<div class="paragraph"><p>You can restrict i3bar to one or more outputs (monitors). The default is to\r
+handle all outputs. Restricting the outputs is useful for using different\r
+options for different outputs by using multiple <em>bar</em> blocks.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>output <output></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># big monitor: everything\r
+bar {\r
+ output HDMI2\r
+ status_command i3status\r
+}\r
+\r
+# laptop monitor: bright colors and i3status with less modules.\r
+bar {\r
+ output LVDS1\r
+ status_command i3status --config ~/.i3status-small.conf\r
+ colors {\r
+ background #000000\r
+ statusline #ffffff\r
+ }\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_tray_output">5.5. Tray output</h3>\r
+<div class="paragraph"><p>i3bar by default provides a system tray area where programs such as\r
+NetworkManager, VLC, Pidgin, etc. can place little icons.</p></div>\r
+<div class="paragraph"><p>You can configure on which output (monitor) the icons should be displayed or\r
+you can turn off the functionality entirely.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>tray_output <none|output></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># disable system tray\r
+tray_output none\r
+\r
+# show tray icons on the big monitor\r
+tray_output HDMI2</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_font">5.6. 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><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>font <font></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>font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_workspace_buttons">5.7. Workspace buttons</h3>\r
+<div class="paragraph"><p>Specifies whether workspace buttons should be shown or not. This is useful if\r
+you want to display a statusline-only bar containing additional information.</p></div>\r
+<div class="paragraph"><p>The default is to show workspace buttons.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>workspace_buttons <yes|no></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>workspace_buttons no</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_colors">5.8. Colors</h3>\r
+<div class="paragraph"><p>As with i3, colors are in HTML hex format (#rrggbb). The following colors can\r
+be configured at the moment:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+background\r
+</dt>\r
+<dd>\r
+<p>\r
+ Background color of the bar.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+statusline\r
+</dt>\r
+<dd>\r
+<p>\r
+ Text color to be used for the statusline.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+focused_workspace\r
+</dt>\r
+<dd>\r
+<p>\r
+ Text color/background color for a workspace button when the workspace\r
+ has focus.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+active_workspace\r
+</dt>\r
+<dd>\r
+<p>\r
+ Text color/background color for a workspace button when the workspace\r
+ is active (visible) on some output, but the focus is on another one.\r
+ You can only tell this apart from the focused workspace when you are\r
+ using multiple monitors.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+inactive_workspace\r
+</dt>\r
+<dd>\r
+<p>\r
+ Text color/background color for a workspace button when the workspace\r
+ does not have focus and is not active (visible) on any output. This\r
+ will be the case for most workspaces.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+urgent_workspace\r
+</dt>\r
+<dd>\r
+<p>\r
+ Text color/background color for workspaces which contain at least one\r
+ window with the urgency hint set.\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>colors {\r
+ background <color>\r
+ statusline <color>\r
+\r
+ colorclass <foreground> <background>\r
+}</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>colors {\r
+ background #000000\r
+ statusline #ffffff\r
+\r
+ focused_workspace #ffffff #285577\r
+ active_workspace #ffffff #333333\r
+ inactive_workspace #888888 #222222\r
+ urgent_workspace #ffffff #900000\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_list_of_commands">5. List of commands</h2>\r
+<h2 id="_list_of_commands">6. List of commands</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Commands are what you bind to specific keypresses. You can also issue commands\r
at runtime without pressing a key by using the IPC interface. An easy way to\r
<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>bindsym mod+x [class="Firefox"] kill</tt></pre>\r
+<pre><tt>bindsym mod+x [class="Firefox"] kill\r
+\r
+# same thing, but case-insensitive\r
+bindsym mod+x [class="(?i)firefox"] kill</tt></pre>\r
</div></div>\r
<div class="paragraph"><p>The criteria which are currently implemented are:</p></div>\r
<div class="dlist"><dl>\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+window_role\r
+</dt>\r
+<dd>\r
+<p>\r
+ Compares the window role (WM_WINDOW_ROLE).\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
id\r
</dt>\r
<dd>\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
-mark\r
+con_mark\r
</dt>\r
<dd>\r
<p>\r
</p>\r
</dd>\r
</dl></div>\r
-<div class="paragraph"><p>Note that currently all criteria are compared case-insensitive and do not\r
-support regular expressions. This is planned to change in the future.</p></div>\r
+<div class="paragraph"><p>The criteria <tt>class</tt>, <tt>instance</tt>, <tt>role</tt>, <tt>title</tt> and <tt>mark</tt> are actually\r
+regular expressions (PCRE). See <tt>pcresyntax(3)</tt> or <tt>perldoc perlre</tt> for\r
+information on how to use them.</p></div>\r
<div class="sect2">\r
-<h3 id="_splitting_containers">5.1. Splitting containers</h3>\r
+<h3 id="exec">6.1. Executing applications (exec)</h3>\r
+<div class="paragraph"><p>What good is a window manager if you can’t actually start any applications?\r
+The exec command starts an application by passing the command you specify to a\r
+shell. This implies that you can use globbing (wildcards) and programs will be\r
+searched in your $PATH.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>exec [--no-startup-id] command</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># Start the GIMP\r
+bindsym mod+g exec gimp\r
+\r
+# Start the terminal emulator urxvt which is not yet startup-notification-aware\r
+bindsym mod+enter exec --no-startup-id urxvt</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>The <tt>--no-startup-id</tt> parameter disables startup-notification support for this\r
+particular exec command. With startup-notification, i3 can make sure that a\r
+window appears on the workspace on which you used the exec command. Also, it\r
+will change the X11 cursor to <tt>watch</tt> (a clock) while the application is\r
+launching. So, if an application is not startup-notification aware (most GTK\r
+and Qt using applications seem to be, though), you will end up with a watch\r
+cursor for 60 seconds.</p></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
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_manipulating_layout">5.2. Manipulating layout</h3>\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>To make the current window (!) fullscreen, use <tt>fullscreen</tt>, to make\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_focusing_moving_containers">5.3. Focusing/Moving containers</h3>\r
+<h3 id="_focusing_moving_containers">6.4. Focusing/Moving containers</h3>\r
<div class="paragraph"><p>To change the focus, use the focus command: <tt>focus left</tt>, <tt>focus right</tt>, <tt>focus down</tt> and <tt>focus up</tt>.</p></div>\r
<div class="paragraph"><p>There are a few special parameters you can use for the focus command:</p></div>\r
<div class="dlist"><dl>\r
</dd>\r
</dl></div>\r
<div class="paragraph"><p>For moving, use <tt>move left</tt>, <tt>move right</tt>, <tt>move down</tt> and <tt>move up</tt>.</p></div>\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
+focus <parent|child|floating|tiling|mode_toggle>\r
+move <left|right|down|up> [<px> px]</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>Note that the amount of pixels you can specify for the <tt>move</tt> command is only\r
+relevant for floating containers. The default amount is 10 pixels.</p></div>\r
<div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt># Focus clients on the left, bottom, top, right:\r
+<pre><tt># 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
# Focus last floating/tiling container\r
bindsym mod+g focus mode_toggle\r
\r
-# Move client to the left, bottom, top, right:\r
+# 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</tt></pre>\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</tt></pre>\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_changing_named_workspaces_moving_to_workspaces">5.4. Changing (named) workspaces/moving to workspaces</h3>\r
+<h3 id="_changing_named_workspaces_moving_to_workspaces">6.5. 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. To move containers to specific workspaces, use\r
<tt>move workspace</tt>.</p></div>\r
<div class="paragraph"><p>You can also switch to the next and previous workspace with the commands\r
<tt>workspace next</tt> and <tt>workspace prev</tt>, which is handy, for example, if you have\r
workspace 1, 3, 4 and 9 and you want to cycle through them with a single key\r
-combination.</p></div>\r
+combination. Similarily, you can use <tt>move workspace next</tt> and <tt>move workspace\r
+prev</tt> to move a container to the next/previous workspace.</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 output</tt> command followed by the name of the target output. You\r
may also use <tt>left</tt>, <tt>right</tt>, <tt>up</tt>, <tt>down</tt> instead of the xrandr output name to\r
\r
bindsym mod+Shift+1 move workspace 1\r
bindsym mod+Shift+2 move workspace 2\r
-...</tt></pre>\r
+...\r
+\r
+# switch between the current and the previously focused one\r
+bindsym mod+b workspace back_and_forth</tt></pre>\r
</div></div>\r
<div class="sect3">\r
-<h4 id="_named_workspaces">5.4.1. Named workspaces</h4>\r
+<h4 id="_named_workspaces">6.5.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
</div>\r
</div>\r
<div class="sect2">\r
-<h3 id="resizingconfig">5.5. Resizing containers/windows</h3>\r
+<h3 id="resizingconfig">6.6. 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 class="paragraph"><p>Direction can be one of <tt>up</tt>, <tt>down</tt>, <tt>left</tt> or <tt>right</tt>. The optional pixel\r
argument specifies by how many pixels a <strong>floating container</strong> should be grown or\r
-shrinked (the default is 10 pixels). The ppt argument means percentage points\r
+shrunk (the default is 10 pixels). The ppt argument means percentage points\r
and specifies by how many percentage points a <strong>tiling container</strong> should be\r
-grown or shrinked (the default is 10 percentage points).</p></div>\r
+grown or shrunk (the default is 10 percentage points).</p></div>\r
<div class="paragraph"><p>I recommend using the resize command inside a so called <tt>mode</tt>:</p></div>\r
<div class="listingblock">\r
<div class="title">Example: Configuration file, defining a mode for resizing</div>\r
</div></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_jumping_to_specific_windows">5.6. Jumping to specific windows</h3>\r
+<h3 id="_jumping_to_specific_windows">6.7. 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_mark_goto">5.7. VIM-like marks (mark/goto)</h3>\r
+<h3 id="_vim_like_marks_mark_goto">6.8. VIM-like marks (mark/goto)</h3>\r
<div class="paragraph" id="vim_like_marks"><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="_changing_border_style">5.8. Changing border style</h3>\r
+<h3 id="_changing_border_style">6.9. 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 1pixel</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="stack-limit">5.9. Reloading/Restarting/Exiting</h3>\r
+<h3 id="stack-limit">6.10. 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>\r
</div>\r
<div class="sect1">\r
-<h2 id="multi_monitor">6. 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">6.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">6.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">7. 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">7.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
screen.</p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_giving_presentations_multi_monitor">7.2. Giving presentations (multi-monitor)</h3>\r
+<h3 id="_giving_presentations_multi_monitor">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="presentations">7.2.1. Case 1: everybody gets the same output</h4>\r
+<h4 id="presentations">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">7.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
projects / i3 / i3.github.io / commitdiff