docs/hacking-howto: comment out a few sections which are not updated yet

We want to get this release out and will update the sections afterwards. Sorry!
If you need to know stuff *right now*, please ask us on IRC
This commit is contained in:
Michael Stapelberg 2011-07-31 16:19:25 +02:00
parent 033466585d
commit 6ef3866108
1 changed files with 63 additions and 5 deletions

View File

@ -1,15 +1,13 @@
Hacking i3: How To
==================
Michael Stapelberg <michael+i3@stapelberg.de>
February 2010
July 2011
This document is intended to be the first thing you read before looking and/or
touching i3s source code. It should contain all important information to help
you understand why things are like they are. If it does not mention something
you find necessary, please do not hesitate to contact me.
PLEASE BEWARE THAT THIS DOCUMENT IS ONLY PARTIALLY UPDATED FOR -tree YET!
== Window Managers
A window manager is not necessarily needed to run X, but it is usually used in
@ -67,6 +65,13 @@ the layout you need at the moment.
=== The layout table
*********************************************************************************
This section has not been updated for v4.0 yet, sorry! We wanted to release on
time, but we will update this soon. Please talk to us on IRC if you need to
know stuff *NOW* :).
*********************************************************************************
/////////////////////////////////////////////////////////////////////////////////
To accomplish flexible layouts, we decided to simply use a table. The table
grows and shrinks as you need it. Each cell holds a container which then holds
windows (see picture below). You can use different layouts for each container
@ -108,6 +113,7 @@ window).
|========
Furthermore, you can freely resize table cells.
/////////////////////////////////////////////////////////////////////////////////
== Files
@ -237,11 +243,21 @@ Legacy support for Xinerama. See +src/randr.c+ for the preferred API.
== Data structures
*********************************************************************************
This section has not been updated for v4.0 yet, sorry! We wanted to release on
time, but we will update this soon. Please talk to us on IRC if you need to
know stuff *NOW* :).
*********************************************************************************
/////////////////////////////////////////////////////////////////////////////////
See include/data.h for documented data structures. The most important ones are
explained right here.
image:bigpicture.png[The Big Picture]
/////////////////////////////////////////////////////////////////////////////////
So, the hierarchy is:
. *X11 root window*, the root container
@ -280,18 +296,38 @@ desktops''.
=== The layout table
*********************************************************************************
This section has not been updated for v4.0 yet, sorry! We wanted to release on
time, but we will update this soon. Please talk to us on IRC if you need to
know stuff *NOW* :).
*********************************************************************************
/////////////////////////////////////////////////////////////////////////////////
Each workspace has a table, which is just a two-dimensional dynamic array
containing Containers (see below). This table grows and shrinks as you need it
(by moving windows to the right you can create a new column in the table, by
moving them to the bottom you create a new row).
/////////////////////////////////////////////////////////////////////////////////
=== Container
*********************************************************************************
This section has not been updated for v4.0 yet, sorry! We wanted to release on
time, but we will update this soon. Please talk to us on IRC if you need to
know stuff *NOW* :).
*********************************************************************************
/////////////////////////////////////////////////////////////////////////////////
A container is the content of a tables cell. It holds an arbitrary amount of
windows and has a specific layout (default layout, stack layout or tabbed
layout). Containers can consume multiple table cells by modifying their
colspan/rowspan attribute.
/////////////////////////////////////////////////////////////////////////////////
=== Client
A client is x11-speak for a window.
@ -399,7 +435,7 @@ i3 does not care for applications. All it notices is when new windows are
mapped (see `src/handlers.c`, `handle_map_request()`). The window is then
reparented (see section "Manage windows").
After reparenting the window, `render_layout()` is called which renders the
After reparenting the window, `render_tree()` is called which renders the
internal layout table. The new window has been placed in the currently focused
container and therefore the new window and the old windows (if any) need to be
moved/resized so that the currently active layout (default/stacking/tabbed mode)
@ -448,6 +484,15 @@ src/layout.c, function resize_client().
== Rendering (src/layout.c, render_layout() and render_container())
*********************************************************************************
This section has not been updated for v4.0 yet, sorry! We wanted to release on
time, but we will update this soon. Please talk to us on IRC if you need to
know stuff *NOW* :).
*********************************************************************************
/////////////////////////////////////////////////////////////////////////////////
There are several entry points to rendering: `render_layout()`,
`render_workspace()` and `render_container()`. The former one calls
`render_workspace()` for every screen, which in turn will call
@ -520,7 +565,18 @@ floating windows:
* The new width_factor for each involved column (respectively row) will be
calculated.
== User commands / commandmode (src/commands.c)
/////////////////////////////////////////////////////////////////////////////////
== User commands / commandmode (src/cmdparse.{l,y})
*********************************************************************************
This section has not been updated for v4.0 yet, sorry! We wanted to release on
time, but we will update this soon. Please talk to us on IRC if you need to
know stuff *NOW* :).
*********************************************************************************
/////////////////////////////////////////////////////////////////////////////////
Like in vim, you can control i3 using commands. They are intended to be a
powerful alternative to lots of shortcuts, because they can be combined. There
@ -545,6 +601,8 @@ j, k and l, like in vim (h = left, j = down, k = up, l = right). When you just
specify the direction keys, i3 will move the focus in that direction. You can
provide "m" or "s" before the direction to move a window respectively or snap.
/////////////////////////////////////////////////////////////////////////////////
== Moving containers
The movement code is pretty delicate. You need to consider all cases before