2011-01-29 09:10:51 -05:00
|
|
|
|
Tree branch: Migrating
|
|
|
|
|
|
======================
|
|
|
|
|
|
Michael Stapelberg <michael+i3@stapelberg.de>
|
|
|
|
|
|
November 2010
|
|
|
|
|
|
|
|
|
|
|
|
== Introduction
|
|
|
|
|
|
|
|
|
|
|
|
The tree branch (referring to a branch of i3 in the git repository) is the new
|
|
|
|
|
|
version of i3. Due to the very deep changes and heavy refactoring of the source
|
2011-05-12 11:20:00 -04:00
|
|
|
|
source, we decided to develop it in a separate branch (instead of using the
|
2011-01-29 09:10:51 -05:00
|
|
|
|
next/master-branch system like before).
|
|
|
|
|
|
|
|
|
|
|
|
== Current status
|
|
|
|
|
|
|
|
|
|
|
|
Currently, the code is mostly working. Some of the i3 core developers have been
|
|
|
|
|
|
using the tree branch version for a few weeks now. So, if you are eager to try
|
|
|
|
|
|
out the new features and help us find bugs, give it a try!
|
|
|
|
|
|
|
|
|
|
|
|
At the same time, a word of warning is appropriate: This version of i3 might
|
|
|
|
|
|
crash unexpectedly, so please be careful with important data (do not work for
|
|
|
|
|
|
two days without saving…).
|
|
|
|
|
|
|
|
|
|
|
|
== Getting the latest tree branch version
|
|
|
|
|
|
|
|
|
|
|
|
Check out the latest version:
|
|
|
|
|
|
---------------------------------------------
|
|
|
|
|
|
$ git clone -b tree git://code.stapelberg.de/i3
|
|
|
|
|
|
---------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
Then build and install it (has the same dependencies as the latest stable i3
|
|
|
|
|
|
version):
|
|
|
|
|
|
-----------------------------
|
|
|
|
|
|
$ cd i3
|
|
|
|
|
|
$ make
|
|
|
|
|
|
$ sudo cp i3 /usr/bin/i3-tree
|
|
|
|
|
|
-----------------------------
|
|
|
|
|
|
|
|
|
|
|
|
…and execute +i3-tree+ instead of +i3+ in your Xsession.
|
|
|
|
|
|
|
|
|
|
|
|
*IMPORTANT:* Please note that configuration file compatibility is not yet done.
|
|
|
|
|
|
So, make sure you use/customize the provided +i3.config+ file.
|
|
|
|
|
|
|
|
|
|
|
|
== Tree
|
|
|
|
|
|
|
|
|
|
|
|
The most important change and reason for the name is that i3 stores all
|
|
|
|
|
|
information about the X11 outputs, workspaces and layout of the windows on them
|
|
|
|
|
|
in a tree. The root node is the X11 root window, followed by the X11 outputs,
|
|
|
|
|
|
then workspaces and finally the windows themselve. In previous versions of i3
|
|
|
|
|
|
we had multiple lists (of outputs, workspaces) and a table for each workspace.
|
|
|
|
|
|
That approach turned out to be complicated to use (snapping), understand and
|
|
|
|
|
|
implement.
|
|
|
|
|
|
|
|
|
|
|
|
=== The tree consists of Containers
|
|
|
|
|
|
|
|
|
|
|
|
The building blocks of our tree are so called +Containers+. A +Container+ can
|
|
|
|
|
|
host a window (meaning an X11 window, one that you can actually see and use,
|
|
|
|
|
|
like a browser). Alternatively, it could contain one or more +Containers+. A
|
|
|
|
|
|
simple example is the workspace: When you start i3 with a single monitor, a
|
|
|
|
|
|
single workspace and you open two terminal windows, you will end up with a tree
|
|
|
|
|
|
like this:
|
|
|
|
|
|
|
|
|
|
|
|
image::tree-layout2.png["layout2",float="right"]
|
|
|
|
|
|
image::tree-shot4.png["shot4",title="Two terminals on standard workspace"]
|
|
|
|
|
|
|
|
|
|
|
|
=== Orientation and Split Containers
|
|
|
|
|
|
|
|
|
|
|
|
[[OrientationSplit]]
|
|
|
|
|
|
|
|
|
|
|
|
It is only natural to use so-called +Split Containers+ in order to build a
|
|
|
|
|
|
layout when using a tree as data structure. In i3, every +Container+ has an
|
|
|
|
|
|
orientation (horizontal, vertical or unspecified). So, in our example with the
|
|
|
|
|
|
workspace, the default orientation of the workspace +Container+ is horizontal
|
|
|
|
|
|
(most monitors are widescreen nowadays). If you change the orientation to
|
|
|
|
|
|
vertical (+Alt+v+ in the default config) and *then* open two terminals, i3 will
|
|
|
|
|
|
configure your windows like this:
|
|
|
|
|
|
|
|
|
|
|
|
image::tree-shot2.png["shot2",title="Vertical Workspace Orientation"]
|
|
|
|
|
|
|
|
|
|
|
|
An interesting new feature of the tree branch is the ability to split anything:
|
|
|
|
|
|
Let’s assume you have two terminals on a workspace (with horizontal
|
|
|
|
|
|
orientation), focus is on the right terminal. Now you want to open another
|
|
|
|
|
|
terminal window below the current one. If you would just open a new terminal
|
|
|
|
|
|
window, it would show up to the right due to the horizontal workspace
|
|
|
|
|
|
orientation. Instead, press +Alt+v+ to create a +Vertical Split Container+ (to
|
|
|
|
|
|
open a +Horizontal Split Container+, use +Alt+h+). Now you can open a new
|
|
|
|
|
|
terminal and it will open below the current one:
|
|
|
|
|
|
|
|
|
|
|
|
image::tree-layout1.png["Layout",float="right"]
|
|
|
|
|
|
image::tree-shot1.png["shot",title="Vertical Split Container"]
|
|
|
|
|
|
|
|
|
|
|
|
unfloat::[]
|
|
|
|
|
|
|
|
|
|
|
|
You probably guessed it already: There is no limit on how deep your hierarchy
|
|
|
|
|
|
of splits can be.
|
|
|
|
|
|
|
|
|
|
|
|
=== Level up
|
|
|
|
|
|
|
|
|
|
|
|
Let’s stay with our example from above. We have a terminal on the left and two
|
|
|
|
|
|
vertically split terminals on the right, focus is on the bottom right one. When
|
|
|
|
|
|
you open a new terminal, it will open below the current one.
|
|
|
|
|
|
|
|
|
|
|
|
So, how can you open a new terminal window to the *right* of the current one?
|
|
|
|
|
|
The solution is to use +level up+, which will focus the +Parent Container+ of
|
|
|
|
|
|
the current +Container+. In this case, you would focus the +Vertical Split
|
|
|
|
|
|
Container+ which is *inside* the horizontally oriented workspace. Thus, now new
|
|
|
|
|
|
windows will be opened to the right of the +Vertical Split Container+:
|
|
|
|
|
|
|
|
|
|
|
|
image::tree-shot3.png["shot3",title="Level Up, then open new terminal"]
|
|
|
|
|
|
|
|
|
|
|
|
== Commands
|
|
|
|
|
|
|
|
|
|
|
|
The authoritive reference for commands is +src/cmdparse.y+. You can also find
|
|
|
|
|
|
most commands in +i3.config+. Here comes a short overview over the important
|
|
|
|
|
|
commands:
|
|
|
|
|
|
|
|
|
|
|
|
=== Manipulating layout
|
|
|
|
|
|
|
|
|
|
|
|
-------------------------------
|
|
|
|
|
|
layout <default|stacked|tabbed>
|
|
|
|
|
|
-------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
=== Changing Focus
|
|
|
|
|
|
|
|
|
|
|
|
--------------------------
|
|
|
|
|
|
next <horizontal|vertical>
|
|
|
|
|
|
prev <horizontal|vertical>
|
|
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
|
|
|
|
.Examples:
|
|
|
|
|
|
-------------------------
|
|
|
|
|
|
bindsym Mod1+Left prev h
|
|
|
|
|
|
bindsym Mod1+Right next h
|
|
|
|
|
|
bindsym Mod1+Down next v
|
|
|
|
|
|
bindsym Mod1+Up prev v
|
|
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
|
|
|
|
=== Moving
|
|
|
|
|
|
|
|
|
|
|
|
-----------------------------------------
|
|
|
|
|
|
move <before|after> <horizontal|vertical>
|
|
|
|
|
|
-----------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
.Examples:
|
|
|
|
|
|
-----------------------------------------
|
|
|
|
|
|
bindsym Mod1+Shift+Left move before h
|
|
|
|
|
|
bindsym Mod1+Shift+Right move after h
|
|
|
|
|
|
bindsym Mod1+Shift+Down move before v
|
|
|
|
|
|
bindsym Mod1+Shift+Up move after v
|
|
|
|
|
|
-----------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
=== Changing workspace
|
|
|
|
|
|
|
|
|
|
|
|
---------------------------
|
|
|
|
|
|
workspace <name>
|
|
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
|
|
|
|
.Examples:
|
|
|
|
|
|
---------------------------
|
|
|
|
|
|
bindsym Mod1+1 workspace 1
|
|
|
|
|
|
bindsym Mod1+2 workspace 2
|
|
|
|
|
|
…
|
|
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
|
|
|
|
=== Moving Containers to workspaces
|
|
|
|
|
|
|
|
|
|
|
|
---------------------
|
|
|
|
|
|
move workspace <name>
|
|
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
|
|
-------------------------------------
|
|
|
|
|
|
bindsym Mod1+Shift+1 move workspace 1
|
|
|
|
|
|
bindsym Mod1+Shift+2 move workspace 2
|
|
|
|
|
|
…
|
|
|
|
|
|
-------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
=== Changing border style
|
|
|
|
|
|
|
|
|
|
|
|
---------------------------
|
|
|
|
|
|
border <normal|none|1pixel>
|
|
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
|
|
|
|
=== Changing container mode
|
|
|
|
|
|
|
|
|
|
|
|
-----------------------------
|
|
|
|
|
|
mode <tiling|floating|toggle>
|
|
|
|
|
|
-----------------------------
|
|
|
|
|
|
|
|
|
|
|
|
== The rest
|
|
|
|
|
|
|
|
|
|
|
|
What is not mentioned here explicitly is either unchanged and can be read in
|
|
|
|
|
|
the http://i3.zekjur.net/docs/userguide.html[i3 User’s Guide] or it is not yet
|
|
|
|
|
|
implemented.
|
