193 lines
6.3 KiB
Plaintext
193 lines
6.3 KiB
Plaintext
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
|
||
source, we decided to develop it in a separate branch (instead of using the
|
||
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.
|